Sphinx works great with Github Pages.
Sphinx requires one-time setup as described below.
The URL will be like https://geospace-code.github.io/pymap3d/.
Install Sphinx in an environment otherwise it may downgrade other packages:
autodoc: automatically insert docstrings from modules (y/n) [n]: y
mathjax: include math, rendered in the browser by MathJax (y/n) [n]: y
viewcode: include links to the source code of documented Python objects (y/n) [n]: y
githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]: y
Add to .gitignore
doctrees/
.buildinfo
Edit docs/Makefile to include
SOURCEDIR = .
BUILDDIR = .
Create empty docs/.nojekyll or else Jekyll will reject all directories starting with _, breaking the Sphinx docs.
In general it is not appropriate to assume the default shell is
Bash.
Using a generic script
shebang:
#!/bin/sh
will either use the default shell or invoke legacy
Bourne Shell
1980s compatibility mode.
Either way, a shell script using the general #!/bin/sh may fail on other computers.
To improve shell script robustness, specify a particular shell with the shebang.
Popular shells besides Bash include
Dash
and
Zsh,
which is the macOS default.
To have even better cross-platform robustness, consider using Python instead of shell scripts.
The default shell is selectable in the shebang in the first line of the “my_script.sh” shell script.
For example, to specify Bash shell, put as the first line:
#!/usr/bin/env bash
The currently used shell is revealed by:
echo$SHELL
this $SHELL variable may not strictly be the “default” shell if you have scripts changing the shell on interactive login.
Other users may choose a different default shell.
To run a script in a specific shell, do like:
bash my_script.sh
To permanently change user default shell use
chsh.
Using
sed one-liners,
recursively clean from text files such as blank lines and trailing whitespace.
ℹ️
Note
ensure the globbing pattern is only for the expected text files or unwanted PDF files etc. might be destroyed by just using “*”
The script below is used like:
./clean.sh ~/my_site "*.md"
clean.sh contains:
#!/usr/bin/env bash
set -o errexit
loc=$1pat=$2find $loc -not -path "*/.git*" -type f -name "$pat" -execdir sed --in-place 's/[[:space:]]\+$//' {} \+ -execdir sed --in-place -e :a -e '/^\n*$/{$d;N;};/\n$/ba' {} \+
Note that each “-execdir” command is separate.
Add more commands or take out what is unwanted.
Use cases include keeping files “Git clean” of trailing spaces and extra lines at end of file.
Matlab editor doesn’t autoclean these lines, so use this script for “*.m” files.
OpenSSH client and server are built into Windows.
The setup procedure is easier than using Cygwin.
RDP (Remote Desktop) over SSH can be significantly more secure than RDP alone, assuming SSH is well configured.
Enable OpenSSH Server
in Windows Settings → Apps → Apps & features → Optional features → Add a feature → OpenSSH Server.
This also sets Windows Firewall to allow inbound SSH TCP connections.
Edit “$Env:ProgramData/ssh/sshd_config” on the OpenSSH server PC.
At least set PasswordAuthentication no to require SSH public key for better security.
A minimal SSH keypair can be created for the SSH client by:
ssh-keygen -t ed25519 -f ~/.ssh/my_server
Copy the contents of client laptop file ~/.ssh/my_server.pub to the Windows SSH server computer, creating or adding a line to file ~/.ssh/authorized_keys.
The location of this file is defined in sshd_config as
AuthorizedKeysFile.
Use a unique key for each connecting client–do not reuse SSH keypairs between servers or clients.
If the user is a Windows Administrator on the OpenSSH server computer, add the SSH public key to file “$Env:ProgramData/ssh/administrators_authorized_keys”
Start the SSH server (for this session only) from PowerShell:
Start-Service sshd
To always start OpenSSH on boot, type services.msc and in Properties of OpenSSH server → General set “Startup Type: Automatic”
As on Linux, the “authorized_keys” file must have the correct file permissions ACL. Run this PowerShell script:
The SSH client should be able to connect to the SSH server.
If this doesn’t work, try using SSH locally on the OpenSSH server computer to troubleshoot.
To use RDP (remote desktop) over SSH do this one-step setup
Tips:
Edit text files from Windows console over SSH in the Terminal by using WSL.
Enter commands like nano foo.txt just like in Linux as it’s the WSL shell.
wsl
Change the
default SSH shell.
Assuming PowerShell on the SSH server, the commands would be like (from pwsh PowerShell):
This example uses the aurora, which is produced around most planetary bodies due to energetic particle kinetics as the particles penetrate the ionosphere.
Optical instruments such as cameras give a line integrated measurement for each pixel (angle) of the imagers.
This data can be useful for tomographic techniques, when the location and orientation of the camera is well known, and multiple cameras with overlapping field of view exist.
However, this rich data can be greatly supplemented and even superseded by other instruments, especially incoherent scatter radar, where 3-D + time data are available due to volume integrated target returns.
Many analyses rely on those thin (~ 0.5 degree FWHM) radar beams to complete an analysis.
We rarely know the needed orientation of the radar beams beforehand, and many ISR cannot change the location of their pre-programmed beams.
Although as AESA they can steer almost instantaneously within the radar backend processor limits.
This is just a geospace example of too much data, but not enough to gauge individual analyses without additional processing techniques.
By convention, the environment variable MINGWROOT tells the path to MinGW64 (just above bin/, lib/, include/)
MSYS2: MINGWROOT=%SYSTEMDRIVE%\msys64\mingw64
This variable may be needed to modify the GNU Octave PATH on Windows when using “system()” calls with executables compiled by MinGW.
A similar issues exists on Windows with Matlab and Parallel Computing Toolbox, that provides its own mpiexec.
With a website / blog having thousands of pages and many thousands of external links, it is impractical to check external outbound link quality with any regularity.
Informal link checks revealed that non-https:// websites had a substantially higher chance of becoming a defunct site that gets snapped up by spammers and scammers.
To help mitigate some of the risk of websites going to unintended destinations, we decided to eliminate almost all non-https external links.
An increasing number of undesired websites are enabling https both to improve SEO and trick visitors.
However, this additional friction anecdotally for the external links we’ve seen go bad has so far been rarer for https:// URLs.
We have seen https:// sites be replaced by undesired content, but what often happens is the spammer doesn’t bother to setup the certificates correctly, so either the website won’t load if HSTS was used, or there are prominent warnings that the user has to click through.
There’s nothing to stop spammers from correctly setting certificates, but we feel https-only external links currently afford a meaningful benefit.
WSL2 (including with Windows 20H1 2004) is known to have issues with having the WSL clock get hours or days behind actual time after the computer is suspended.
This issue was not seen in WSL1, but upon upgrading to WSL2 has been almost immediately apparent to multiple people that reported this issue.
This causes errors with build systems (including GNU Make and Ninja) and SSL verification among others.
A workaround for this, when it occurs (have to keep doing workaround) is to synchronize the software clock to the onboard hardware clock from WSL Terminal:
hwclock -s
or if suitable from Windows Terminal:
wsl --shutdown
If that doesn’t work, try using NTP from WSL Terminal:
Sometimes cryptic errors occur if there was a syntax error in a .bib BibTeX bibliography file that doesn’t disappear even when the .bib syntax is corrected.
The fix for this is often to delete the auto-generated files: