diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index bfb078e..92c807f 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -4,22 +4,46 @@ on: push: branches: - main + workflow_dispatch: permissions: - contents: write + contents: read + pages: write + id-token: write + +concurrency: + group: github-pages + cancel-in-progress: false jobs: deploy: runs-on: ubuntu-latest + + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: - - uses: actions/checkout@v4 - with: - fetch-depth: 0 + - name: Checkout + uses: actions/checkout@v4 - - uses: astral-sh/setup-uv@v5 + - name: Install uv + uses: astral-sh/setup-uv@v5 - - name: Install docs dependencies + - name: Install documentation dependencies run: uv sync --extra docs - - name: Deploy to GitHub Pages - run: uv run mkdocs gh-deploy --force + - name: Configure GitHub Pages + uses: actions/configure-pages@v5 + + - name: Build documentation + run: uv run mkdocs build --strict + + - name: Upload documentation + uses: actions/upload-pages-artifact@v4 + with: + path: site + + - name: Deploy documentation + id: deployment + uses: actions/deploy-pages@v4 diff --git a/README.md b/README.md index cbc4987..1ad6064 100644 --- a/README.md +++ b/README.md @@ -75,6 +75,14 @@ Add tests for new implementations and run the suite: uv run pytest tests ``` +### Documentation + +Any documentation changes would be deployed automatically after a PR merges main. However, please verify locally first with + +```bash +uv run --extra docs mkdocs serve +``` + ## Citation If you use this package, please cite: diff --git a/docs/api/core.md b/docs/api/core.md new file mode 100644 index 0000000..5a83edd --- /dev/null +++ b/docs/api/core.md @@ -0,0 +1,3 @@ +# Core API + +::: PtyLab diff --git a/docs/api/engines.md b/docs/api/engines.md new file mode 100644 index 0000000..8383fbc --- /dev/null +++ b/docs/api/engines.md @@ -0,0 +1,5 @@ +# Engines + +::: PtyLab.Engines + options: + show_submodules: true diff --git a/docs/api/experimental-data.md b/docs/api/experimental-data.md new file mode 100644 index 0000000..a74e1af --- /dev/null +++ b/docs/api/experimental-data.md @@ -0,0 +1,5 @@ +# Experimental Data + +::: PtyLab.ExperimentalData + options: + show_submodules: true diff --git a/docs/api/grid-generation.md b/docs/api/grid-generation.md new file mode 100644 index 0000000..6001a01 --- /dev/null +++ b/docs/api/grid-generation.md @@ -0,0 +1,5 @@ +# Grid Generation + +::: PtyLab.GridGeneration + options: + show_submodules: true diff --git a/docs/api/index.md b/docs/api/index.md new file mode 100644 index 0000000..9e72c2c --- /dev/null +++ b/docs/api/index.md @@ -0,0 +1,4 @@ +# API Reference + +The API reference is generated from PtyLab's Python docstrings. It covers the +public modules and members in each package. diff --git a/docs/api/io.md b/docs/api/io.md new file mode 100644 index 0000000..0ffff8d --- /dev/null +++ b/docs/api/io.md @@ -0,0 +1,5 @@ +# Input and Output + +::: PtyLab.io + options: + show_submodules: true diff --git a/docs/api/monitoring.md b/docs/api/monitoring.md new file mode 100644 index 0000000..238087d --- /dev/null +++ b/docs/api/monitoring.md @@ -0,0 +1,5 @@ +# Monitoring + +::: PtyLab.Monitor + options: + show_submodules: true diff --git a/docs/api/operators.md b/docs/api/operators.md new file mode 100644 index 0000000..b3d99b7 --- /dev/null +++ b/docs/api/operators.md @@ -0,0 +1,5 @@ +# Operators + +::: PtyLab.Operators + options: + show_submodules: true diff --git a/docs/api/parameters.md b/docs/api/parameters.md new file mode 100644 index 0000000..f958c98 --- /dev/null +++ b/docs/api/parameters.md @@ -0,0 +1,5 @@ +# Parameters + +::: PtyLab.Params + options: + show_submodules: true diff --git a/docs/api/probe-engines.md b/docs/api/probe-engines.md new file mode 100644 index 0000000..68a8762 --- /dev/null +++ b/docs/api/probe-engines.md @@ -0,0 +1,5 @@ +# Probe Engines + +::: PtyLab.ProbeEngines + options: + show_submodules: true diff --git a/docs/api/reconstruction.md b/docs/api/reconstruction.md new file mode 100644 index 0000000..99017cd --- /dev/null +++ b/docs/api/reconstruction.md @@ -0,0 +1,5 @@ +# Reconstruction + +::: PtyLab.Reconstruction + options: + show_submodules: true diff --git a/docs/api/regularizers.md b/docs/api/regularizers.md new file mode 100644 index 0000000..201b429 --- /dev/null +++ b/docs/api/regularizers.md @@ -0,0 +1,5 @@ +# Regularizers + +::: PtyLab.Regularizers + options: + show_submodules: true diff --git a/docs/api/utilities.md b/docs/api/utilities.md new file mode 100644 index 0000000..a45094b --- /dev/null +++ b/docs/api/utilities.md @@ -0,0 +1,5 @@ +# Utilities + +::: PtyLab.utils + options: + show_submodules: true diff --git a/mkdocs.yml b/mkdocs.yml index ca05977..4a9deef 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -23,6 +23,8 @@ theme: icon: material/brightness-4 name: Switch to light mode features: + - navigation.tabs + - navigation.tabs.sticky - navigation.sections - navigation.expand - navigation.indexes @@ -60,6 +62,20 @@ nav: - "05 – CPM Reflection": tutorials/tutorial_reflectionPtychography.ipynb - "06 – CPM Interferometric Intensity": tutorials/tutorial_interferometricIntensityConstraint.ipynb - "07 – FPM": tutorials/tutorial_FPM.ipynb + - API Reference: + - api/index.md + - Core: api/core.md + - Engines: api/engines.md + - Experimental Data: api/experimental-data.md + - Grid Generation: api/grid-generation.md + - Monitoring: api/monitoring.md + - Operators: api/operators.md + - Parameters: api/parameters.md + - Probe Engines: api/probe-engines.md + - Reconstruction: api/reconstruction.md + - Regularizers: api/regularizers.md + - Input and Output: api/io.md + - Utilities: api/utilities.md extra_css: - stylesheets/extra.css @@ -79,6 +95,15 @@ markdown_extensions: plugins: - search + - mkdocstrings: + handlers: + python: + paths: + - . + options: + show_root_heading: true + show_source: true + members_order: source - mkdocs-jupyter: include: ["*.ipynb"] execute: false diff --git a/pyproject.toml b/pyproject.toml index 73e732d..627d764 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "ptylab" -version = "0.3.1" +version = "0.3.2" description = "A cross-platform, open-source inverse modeling toolbox for conventional and Fourier ptychography" authors = [ { name = "Lars Loetgering", email = "lars.loetgering@fulbrightmail.org" }, @@ -37,6 +37,7 @@ docs = [ "mkdocs>=1.6.1", "mkdocs-material>=9.7.6", "mkdocs-jupyter>=0.24", + "mkdocstrings[python]>=1.0.6", ] [project.scripts]