Generate README with GH Actions

.github/workflows/README from docs.yaml

@@ -0,0 +1,51 @@
+name: Generate README
+
+on:
+  pull_request:
+    paths:
+      - "docs/**/*"
+  workflow_run:
+    workflows:
+      - "generate_help_docs"
+
+jobs:
+  make-README:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Fill template
+        working-directory: "docs/"
+        timeout-minutes: 0.1
+        run: |
+          sub_doc_parts_from() {
+            template="$1"
+            directory="$2"
+
+            for file in "$directory"/*; do
+                if [ -f "$file" ]; then
+                    placeholder="{{ $(echo "${file^^}" | tr ./ _) }}"
+                    echo "Saving $file to $placeholder with expanded environment variables" >&2
+                    # Export file contents to text following a pattern in template.md, e.g.:
+                    # section/test_file.md would replace "{{ SECTION_TEST_FILE_MD }}""
+                    template="${template//"$placeholder"/"$(<"$file")"}"
+                fi
+            done
+            echo "$template"
+          }
+          sub_doc_parts_from "$(sub_doc_parts_from "$(<template.md)" "sections")" "help">../README.md
+      - name: Setup git
+        run: |
+          git config --local user.name "github-actions[bot]"
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git remote set-url origin https://${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}
+      - name: Push
+        run: |
+          if git update-index --refresh && git diff-index --quiet HEAD --; then
+            git add README.md
+            git commit -m "Automated update of README.md from docs"
+
+            branch_name="${GITHUB_HEAD_REF:-${GITHUB_REF#refs/heads/}}"
+            git push origin HEAD:$branch_name
+          fi

.github/workflows/black.yaml

@@ -0,0 +1,10 @@
+name: Lint
+
+on: [push, pull_request]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: psf/black@stable

.github/workflows/generate_help_docs.yaml

@@ -0,0 +1,50 @@
+name: Generate README
+
+on:
+  pull_request:
+    paths:
+      - "src/sim_recon/cli/parsing/*"
+      - "src/sim_recon/settings/formatting.py"
+
+jobs:
+  generate-help-docs:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v3
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Copy template
+        run: cp -f docs/template.md README.md
+      - name: Install (without dependencies)
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install . --no-deps
+      - name: Ensure README exists
+        run: |
+          if [ ! -f "README.md" ]; then
+            touch README.md
+          fi
+      - name: Getting help strings from package
+        run: |
+          python -m sim_recon.cli.parsing.otf '--help' >docs/help/sim_otf.txt
+          python -m sim_recon.cli.parsing.recon '--help' >docs/help/sim_recon.txt
+          python -m sim_recon.cli.parsing.otf_view '--help' >docs/help/otf_view.txt
+      - name: Setup git
+        run: |
+          git config --local user.name "github-actions[bot]"
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git remote set-url origin https://${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}
+      - name: Push
+        run: |
+          if git update-index --refresh && git diff-index --quiet HEAD --; then
+            git add docs/help/*
+            git commit -m "Automated update of help docs"
+
+            branch_name="${GITHUB_HEAD_REF:-${GITHUB_REF#refs/heads/}}"
+            git push origin HEAD:$branch_name
+          fi

docs/help/otf_view.txt

@@ -0,0 +1,20 @@
+usage: otf-view [-h] [--show] [--show-only] [-o OUTPUT_DIRECTORY] [-v]
+                [--no-progress]
+                otf_paths [otf_paths ...]
+
+Create OTF views
+
+positional arguments:
+  otf_paths             OTF file paths
+
+options:
+  -h, --help            show this help message and exit
+  --show                Display the plots while running
+  --show-only           Show plots without saving
+  -o OUTPUT_DIRECTORY, --output-directory OUTPUT_DIRECTORY
+                        Save to this directory if saving plots, otherwise each
+                        plot will be saved with its input file
+  -v, --verbose         Show more logging
+  --no-progress         turn off progress bars (only has an effect if tqdm is
+                        installed)
+sdfsdf

docs/help/sim_otf.txt

@@ -0,0 +1,55 @@
+usage: sim-otf [-c CONFIG_PATH] [-p PSF_PATHS [PSF_PATHS ...]]
+               [-o OUTPUT_DIRECTORY] [--overwrite] [--no-cleanup]
+               [--shape XY_SHAPE XY_SHAPE] [-v] [--no-progress]
+               [--nphases NPHASES] [--ls LS] [--na NA] [--nimm NIMM]
+               [--background BACKGROUND] [--beaddiam BEADDIAM] [--angle ANGLE]
+               [--nocompen NOCOMPEN] [--fixorigin FIXORIGIN FIXORIGIN]
+               [--leavekz LEAVEKZ LEAVEKZ LEAVEKZ] [-h]
+
+SIM PSFs to OTFs
+
+options:
+  -c CONFIG_PATH, --config-path CONFIG_PATH
+                        Path to the root config that specifies the paths to
+                        the OTFs and the other configs
+  -p PSF_PATHS [PSF_PATHS ...], --psf PSF_PATHS [PSF_PATHS ...]
+                        Paths to PSF files to be reconstructed (multiple paths
+                        can be given)
+  -o OUTPUT_DIRECTORY, --output-directory OUTPUT_DIRECTORY
+                        If specified, the output directory that the OTFs will
+                        be saved in, otherwise each OTF will be saved in the
+                        same directory as its PSF
+  --overwrite           If specified, files will be overwritten if they
+                        already exist (unique filenames will be used
+                        otherwise)
+  --no-cleanup          If specified, files created during the OTF creation
+                        process will not be cleaned up
+  --shape XY_SHAPE XY_SHAPE
+                        Takes 2 integers (X Y), specifying the shape to crop
+                        PSFs to before converting (powers of 2 are fastest)
+  -v, --verbose         Show more logging
+  --no-progress         turn off progress bars (only has an effect if tqdm is
+                        installed)
+  -h, --help            show this help message and exit
+
+Overrides:
+  Arguments that override configured values. Defaults stated are only used
+  if no value is given or configured.
+
+  --nphases NPHASES     Number of pattern phases per SIM direction
+  --ls LS               Line spacing of SIM pattern in microns
+  --na NA               Detection objective's numerical aperture
+  --nimm NIMM           Refractive index of immersion medium
+  --background BACKGROUND
+                        Camera readout background
+  --beaddiam BEADDIAM   The diameter of the bead in microns, by default 0.12
+  --angle ANGLE         The k0 vector angle with which the PSF is taken, by
+                        default 0
+  --nocompen NOCOMPEN   Do not perform bead size compensation, default False
+                        (do perform)
+  --fixorigin FIXORIGIN FIXORIGIN
+                        The starting and end pixel for interpolation along kr
+                        axis, by default (2, 9)
+  --leavekz LEAVEKZ LEAVEKZ LEAVEKZ
+                        Pixels to be retained on kz axis, by default (0, 0, 0)
+sad