Add inital API documentation #61
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: Build documentation | |
| on: | |
| push: | |
| branches: | |
| - master | |
| tags: | |
| - '**' | |
| pull_request: | |
| branches: | |
| - master | |
| jobs: | |
| docs: | |
| runs-on: ubuntu-22.04 | |
| steps: | |
| - name: Checkout | |
| uses: actions/checkout@v4 | |
| - name: Set up Python 3.11 | |
| uses: actions/setup-python@v4 | |
| with: | |
| python-version: "3.11" | |
| - name: Install jupedsim | |
| run: | | |
| python3 -m pip install . | |
| - name: Build docs | |
| run: | | |
| cp -R notebooks/* docs/source/notebooks | |
| python3 -m pip install -r docs/requirements.txt | |
| sphinx-build -T -E -d doctree -b html docs/source docs/build -j $(nproc) | |
| - name: Determine directory to publish docs to | |
| id: docs-publish-dir | |
| uses: jannekem/run-python-script-action@v1 | |
| with: | |
| script: | | |
| import os, re | |
| github_ref = os.environ.get('GITHUB_REF') | |
| m = re.match(r'^refs/tags/v([0-9]+\.[0-9]+\.[0-9]+(-dev\.[0-9]+)?)$', | |
| github_ref) | |
| if m: | |
| target = "${{ github.ref_name }}" | |
| else: | |
| target = '' | |
| set_output('target', target) | |
| - name: Publish docs to GitHub pages | |
| if: steps.docs-publish-dir.outputs.target != '' | |
| uses: peaceiris/actions-gh-pages@v3 | |
| with: | |
| github_token: ${{ secrets.GITHUB_TOKEN }} | |
| publish_dir: docs/build | |
| destination_dir: ${{ steps.docs-publish-dir.outputs.target }} | |
| keep_files: false | |
| - name: Upload documentation as artifacts | |
| uses: actions/upload-artifact@v3 | |
| with: | |
| name: pages | |
| path: | | |
| docs/build/ | |
| outputs: | |
| docs-target: ${{ steps.docs-publish-dir.outputs.target }} | |
| docs-versions: | |
| name: Update docs versions JSON | |
| needs: docs | |
| if: needs.docs.outputs.docs-target != '' | |
| runs-on: ubuntu-22.04 | |
| steps: | |
| - uses: actions/checkout@v4 | |
| with: | |
| ref: gh-pages | |
| - name: Write versions to JSON file | |
| uses: jannekem/run-python-script-action@v1 | |
| with: | |
| script: | | |
| import json | |
| from pathlib import Path | |
| from packaging.version import Version | |
| prefix = "https://www.jupedsim.org/" | |
| cwd = Path.cwd() | |
| versions = [item.name[1:] for item in cwd.iterdir() if item.is_dir() and not item.name.startswith('.') and item.name.startswith("v")] | |
| versions.sort(key=Version, reverse=True) | |
| versions = ["v" + v for v in versions] | |
| versions.insert(0, "stable") | |
| versions_url = [dict(name=version, version=version, url= prefix + version) | |
| for version in versions] | |
| target_file = Path('versions.json') | |
| with target_file.open('w') as f: | |
| json.dump(versions_url, f) | |
| - name: Redirect stable to new release | |
| run: | | |
| rm -rf stable | |
| ln -s ${{needs.docs.outputs.docs-target}} stable | |
| - name: Update files in gh-pages branch | |
| uses: stefanzweifel/git-auto-commit-action@v4 | |
| with: | |
| branch: gh-pages | |
| commit_message: Update versions and stable |