Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 31 additions & 13 deletions .github/workflows/build_documentation.yaml
Original file line number Diff line number Diff line change
@@ -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,
Expand All @@ -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"

Expand All @@ -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
25 changes: 14 additions & 11 deletions doc/cli_documentation.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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``
Expand All @@ -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/<solver>/<quantity>/``.
- --
* - ``--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``
Expand Down Expand Up @@ -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.
- --

Expand All @@ -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.
- --
- 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
12 changes: 11 additions & 1 deletion doc/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -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 -----------------------------------------------------
Expand All @@ -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
Expand Down
12 changes: 8 additions & 4 deletions doc/installation.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 .

Loading