From c9e071203522d3b8b4ecda2af67f8761e20c2cd4 Mon Sep 17 00:00:00 2001 From: Susana Hahn Date: Mon, 9 Jun 2025 18:43:31 -0600 Subject: [PATCH 1/3] Included mkdoclingo --- docs/reference/encodings/index.md | 12 ++++++++++++ pyproject.toml | 2 +- 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/reference/encodings/index.md b/docs/reference/encodings/index.md index fb7f670..8d87a5b 100644 --- a/docs/reference/encodings/index.md +++ b/docs/reference/encodings/index.md @@ -3,3 +3,15 @@ icon: material/file-code --- # Encodings + + + diff --git a/pyproject.toml b/pyproject.toml index cb2a813..075205f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -19,7 +19,7 @@ format = ["black", "isort", "autoflake"] lint_pylint = ["pylint"] typecheck = ["types-setuptools", "mypy"] test = ["coverage[toml]"] -doc = ["mkdocs", "mkdocs-material", "mkdocstrings[python]"] +doc = ["mkdocs", "mkdocs-material", "mkdocstrings[python]", "mkdoclingo"] dev = ["fillname[test,typecheck,lint_pylint]"] [project.scripts] From e5d61235a86524aa889b015f7ed650185b6b1de8 Mon Sep 17 00:00:00 2001 From: Susana Hahn Date: Mon, 9 Jun 2025 19:01:23 -0600 Subject: [PATCH 2/3] Documentation deploy and dev --- .github/workflows/doc.yml | 51 +++++++++++++++++++++++++++++++++++++++ DEPLOYMENT.md | 12 +++++++++ DEVELOPMENT.md | 20 +++++++++++++-- noxfile.py | 15 +----------- 4 files changed, 82 insertions(+), 16 deletions(-) create mode 100644 .github/workflows/doc.yml diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml new file mode 100644 index 0000000..1a3602f --- /dev/null +++ b/.github/workflows/doc.yml @@ -0,0 +1,51 @@ +name: Deploy Documentation +on: + workflow_dispatch: + push: + tags: + - 'v[0-9]+.[0-9]+.[0-9]+' + +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Set up Python 3.11 + uses: actions/setup-python@v5 + with: + python-version: 3.11 + - name: Install dependencies + run: | + python -m pip install --upgrade pip + python -m pip install -e .[doc] + - name: Build the documentation + run: mkdocs build + - name: Setup Pages + id: pages + uses: actions/configure-pages@v5 + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: "./site" + deploy: + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{steps.deployment.outputs.page_url}} + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md index 0cbbd77..bec251c 100644 --- a/DEPLOYMENT.md +++ b/DEPLOYMENT.md @@ -9,6 +9,18 @@ two services. Please follow this packaging [guide] to setup your accounts accordingly. We also recommend to setup a github [environment] to restrict which contributors can deploy packages. +## Automatic Documentation Deployment + +You can automatically publish project documentation to GitHub Pages on every +new tag. To enable this: + +- Go to your repository on GitHub. +- Navigate to **Settings** > **Pages**. +- Under **Build and deployment**, set **Source** to **GitHub Actions**. + +This setup ensures your documentation is updated and available online whenever +you create a new release tag via Github workflows. + [environment]: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment/ [guide]: https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/ [pypi]: https://pypi.org/ diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 25fd335..40addce 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,8 +1,8 @@ # Development To improve code quality, we use [nox] to run linters, type checkers, unit -tests, documentation and more. We recommend installing nox using [pipx] to have -it available globally. +tests, and more. We recommend installing nox using [pipx] to have it available +globally. ```bash # install @@ -35,6 +35,22 @@ python -m pipx install pre-commit pre-commit install ``` +## Documentation + +Make sure the documentation dependencies for the project are properly installed +with + +```bash +pip install .[doc] +``` + +To run the documentation locally use the following command and click the +provided link to open it in the browser. + +```bash +mkdocs serve +``` + [editable]: https://setuptools.pypa.io/en/latest/userguide/development_mode.html [nox]: https://nox.thea.codes/en/stable/index.html [pipx]: https://pypa.github.io/pipx/ diff --git a/noxfile.py b/noxfile.py index 9c64122..f938643 100644 --- a/noxfile.py +++ b/noxfile.py @@ -1,5 +1,4 @@ import os -import sys import nox @@ -22,19 +21,7 @@ def doc(session): - further arguments are passed to mkbuild """ - options = session.posargs[:] - open_doc = "serve" in options - if open_doc: - options.remove("serve") - - session.install("-e", ".[doc]") - - if open_doc: - open_cmd = "xdg-open" if sys.platform == "linux" else "open" - session.run(open_cmd, "http://localhost:8000/systems/fillname/") - session.run("mkdocs", "serve", *options) - else: - session.run("mkdocs", "build", *options) + session.error("Not longer supported, use `mkdocs serve` instead") @nox.session From b6c22de510e60af8634ec930c95c35621bf817db Mon Sep 17 00:00:00 2001 From: Susana Hahn Date: Tue, 10 Jun 2025 10:30:27 -0600 Subject: [PATCH 3/3] Removed noox doc --- noxfile.py | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/noxfile.py b/noxfile.py index f938643..4da1023 100644 --- a/noxfile.py +++ b/noxfile.py @@ -11,19 +11,6 @@ EDITABLE_TESTS = False -@nox.session -def doc(session): - """ - Build the documentation. - - Accepts the following arguments: - - serve: open documentation after build - - further arguments are passed to mkbuild - """ - - session.error("Not longer supported, use `mkdocs serve` instead") - - @nox.session def dev(session): """