From 9234d7d8138b74726c16f1c2ed56274014af43e4 Mon Sep 17 00:00:00 2001 From: Kristian Date: Wed, 11 Nov 2026 00:54:52 +0100 Subject: [PATCH 1/3] deploy the docs with the GitHub Pages actions The Pages source of the repository is "GitHub Actions", so pushing the built HTML to the gh-pages branch does not publish it: the site has stayed at the build of 19 March 2026 (0.10.0), while every push to master since has still built the docs and pushed them to gh-pages. On a push to master the workflow now uploads the built HTML with actions/upload-pages-artifact and deploys it with actions/deploy-pages; the github-pages environment already lets master deploy. The build needs only read access now, and checkout and setup-python move to versions that run on Node 24, which the runners force on the Node 20 actions. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/build_documentation.yaml | 44 +++++++++++++++------- 1 file changed, 31 insertions(+), 13 deletions(-) diff --git a/.github/workflows/build_documentation.yaml b/.github/workflows/build_documentation.yaml index 38fe94a..f5b528a 100644 --- a/.github/workflows/build_documentation.yaml +++ b/.github/workflows/build_documentation.yaml @@ -1,4 +1,4 @@ -# GitHub Actions workflow to build and deploy Sphinx documentation to GitHub Pages +# GitHub Actions workflow to build the Sphinx documentation and deploy it to GitHub Pages name: Docs # Trigger the workflow on pushes, pull requests, or manual dispatch events, @@ -13,19 +13,19 @@ on: workflow_dispatch: # 3. Allow manual triggers from the GitHub UI permissions: - contents: write # Required so the deploy step can push to gh-pages + contents: read # Building only needs to read the repository jobs: - docs: + build: runs-on: ubuntu-latest # Use the latest Ubuntu runner provided by GitHub steps: # 1. Check out the repository contents - name: Checkout repository - uses: actions/checkout@v3 + uses: actions/checkout@v7 - # 2. Set up a Python environment (defaults to latest 3.x) + # 2. Set up a Python environment - name: Set up Python - uses: actions/setup-python@v5 + uses: actions/setup-python@v7 with: python-version: "3.12" @@ -40,12 +40,30 @@ jobs: run: | sphinx-build doc _build - # 5. Deploy the docs to the gh-pages branch (only on push to master) - - name: Deploy - uses: peaceiris/actions-gh-pages@v3 + # 5. Package the built HTML for GitHub Pages (only on push to master) + - name: Upload Pages artifact + uses: actions/upload-pages-artifact@v5 if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' }} with: - publish_branch: gh-pages # Target branch for the published site - github_token: ${{ secrets.GITHUB_TOKEN }} # Auth token provided by GitHub - publish_dir: _build/ # Directory containing the built HTML - force_orphan: true # Create branch history from scratch each deployment + path: _build/ + + # The Pages source of this repository is "GitHub Actions" (Settings > Pages), so the + # site is what this job deploys. Pushing the HTML to a gh-pages branch would not + # publish it. + deploy: + needs: build + if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' }} + runs-on: ubuntu-latest + permissions: + pages: write # Deploy to GitHub Pages + id-token: write # Prove that the deployment comes from this repository + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + concurrency: # One deployment at a time, and never cancel one halfway + group: pages + cancel-in-progress: false + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v5 From 262f2f6932e933b69bc8621aa9feaa029429739e Mon Sep 17 00:00:00 2001 From: Kristian Date: Wed, 11 Nov 2026 00:54:52 +0100 Subject: [PATCH 2/3] take the docs version from pyproject.toml conf.py took the release from the metadata of the installed ledsa, which an editable install keeps from the time it was installed: a local build showed 0.10.0 for the 0.13.0 source. It now reads the pyproject.toml of the source tree it documents, and falls back to the installed metadata on Python older than 3.11, which lacks tomllib. Co-Authored-By: Claude Opus 5.5 --- doc/conf.py | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index 33368a9..ac47ca9 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -13,6 +13,10 @@ import os import sys from importlib.metadata import version as get_version +try: + import tomllib # Python 3.11 and newer +except ModuleNotFoundError: + tomllib = None sys.path.insert(0, os.path.abspath('..')) # -- Project information ----------------------------------------------------- @@ -21,7 +25,13 @@ project = 'LEDSmokeAnalysis' copyright = '2026, CCE' author = 'CCE' -release = get_version('ledsa') +# The version of the source tree these docs document, as its pyproject.toml states it. The metadata of an +# installed ledsa can be older: an editable install keeps the version it was installed with. +if tomllib is not None: + with open(os.path.join(os.path.abspath('..'), 'pyproject.toml'), 'rb') as f: + release = tomllib.load(f)['project']['version'] +else: + release = get_version('ledsa') # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration From 0c2793936f72426ddcf4f6d28a02ca5196af38d9 Mon Sep 17 00:00:00 2001 From: Kristian Date: Wed, 11 Nov 2026 00:54:52 +0100 Subject: [PATCH 3/3] correct the CLI and installation pages of the docs The CLI page named -s1 as --s1 and the acceptance test options --acceptance-test instead of --acceptance_test, and two literals that lacked a backtick rendered as one, "--step_3`, ``--analyse_photo". --setup needs a path rather than defaulting to ".", and --color_correction and the --n_cores of the demo were missing. Every option the page names now exists in the parser. The installation page gets the supported Python versions and the steps to install from a clone, as in the README. Co-Authored-By: Claude Opus 5.5 --- doc/cli_documentation.rst | 25 ++++++++++++++----------- doc/installation.rst | 12 ++++++++---- 2 files changed, 22 insertions(+), 15 deletions(-) diff --git a/doc/cli_documentation.rst b/doc/cli_documentation.rst index 1f2484e..c1ce6bd 100644 --- a/doc/cli_documentation.rst +++ b/doc/cli_documentation.rst @@ -24,16 +24,16 @@ Data Extraction * - ``-conf``, ``--config`` - Create the data extraction configuration file. - -- - * - ``--s1``, ``--step_1``, ``--find_search_areas`` + * - ``-s1``, ``--step_1``, ``--find_search_areas`` - Step 1: Analyze a reference image to find the LEDs and create a labeled plot with the search areas. - -- * - ``-s2``, ``--step_2``, ``--analyse_positions`` - Step 2: Match the LEDs to the arrays according to the line edge indices in the config file. - -- - * - ``-s3``, ``--step_3`, ``--analyse_photo`` + * - ``-s3``, ``--step_3``, ``--analyse_photo`` - Step 3: Analyse all images to extract pixel values inside the search areas and fit them to an LED model (SLOW!). - ``-r`` (Use the red channel, default), ``-g`` (Use the green channel), ``-b`` (Use the blue channel), ``-rgb`` (Run for each channel) - * - ``-s3_fast``, ``--step_3_fast`, ``--analyse_photo_fast`` + * - ``-s3_fast``, ``--step_3_fast``, ``--analyse_photo_fast`` - Step 3: Analyse all images to extract pixel values and calculate the accumulated values inside the search areas (FAST!). - Channel flags as for ``-s3`` * - ``-re``, ``--restart`` @@ -57,7 +57,7 @@ Analysis * - ``-a``, ``--analysis`` - Computes the extinction coefficients of every quantity ``reference_property`` names in ``config_analysis.ini``, each into ``analysis/extinction_coefficients///``. - -- - * - ``--cc`` + * - ``--cc``, ``--color_correction`` - Applies the color correction matrix before calculating the extinction coefficients. Use only if the reference property is not already color corrected. - -- * - ``--cc_channels`` @@ -111,10 +111,10 @@ Testing * - Argument - Description - Options - * - ``-atest``, ``--acceptance-test`` + * - ``-atest``, ``--acceptance_test`` - Run the acceptance test suite. - -- - * - ``-atest_debug``, ``--acceptance-test_debug`` + * - ``-atest_debug``, ``--acceptance_test_debug`` - Run the acceptance test suite in debug mode. - -- @@ -131,9 +131,12 @@ Demo * - ``-d``, ``--demo`` - Flag to indicate that the LEDSA demo should be run. - Must be used with ``--setup`` or ``--run`` - * - ``--setup`` - - Create the required directories for the simulations and download images and config files. - - Optional: Path to setup simulation and image directories. Default to ``'.'`` + * - ``--setup PATH`` + - Create the directories ``image_data`` and ``simulation`` in ``PATH``, download the images (about 5 GB) and write the config files. + - ``PATH`` is required, e.g. ``.`` for the current directory. * - ``--run`` - - Run the LEDSA demo in the current working directory. - - -- \ No newline at end of file + - Run the demo set up in the current working directory. Without a ``simulation`` directory there, it asks for the demo directory. + - ``--n_cores N`` sets the number of cores (default: 1). + * - ``--n_cores N`` + - Number of cores the demo runs on. Only used together with ``--run``. + - Default: 1 \ No newline at end of file diff --git a/doc/installation.rst b/doc/installation.rst index fda0579..a92ee31 100644 --- a/doc/installation.rst +++ b/doc/installation.rst @@ -2,12 +2,16 @@ Installation ============ -LEDSA is easiest installed via :: +LEDSA needs Python 3.9 to 3.12. - pip install ledsa +It is easiest installed from PyPI via :: + python -m pip install ledsa -or can be obtained by cloning the GitHub repository: :: - https://github.com/FireDynamics/LEDSmokeAnalysis.git +or from source, by cloning the GitHub repository and installing the package: :: + + git clone https://github.com/FireDynamics/LEDSmokeAnalysis.git + cd LEDSmokeAnalysis + pip install .