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 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/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 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 .