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
| # .github/workflows | |
| name: Automated Documentation and Code Formatting | |
| # Workflow triggers | |
| on: | |
| workflow_dispatch: # Allows manual triggering of the workflow | |
| push: # Triggers the workflow on every push to the repository | |
| jobs: | |
| format-sphinx-customized: | |
| runs-on: ubuntu-latest # Specifies the virtual machine to use, in this case, the latest version of Ubuntu | |
| # Defines permissions for this job | |
| permissions: | |
| contents: write # Permissions to write to the repository | |
| steps: | |
| - uses: actions/checkout@v4 # Checks out the code from the repository | |
| # Step to update and prepare the documentation | |
| - name: Prepare and Update Documentation | |
| run: | | |
| # Pulls necessary Docker images for documentation | |
| docker pull dunderlab/docs | |
| docker pull sphinxdoc/sphinx-latexpdf | |
| # Installs required Python packages | |
| pip install nbsphinx | |
| pip install dunderlab-docs | |
| # Sets up initial documentation if a 'docs' directory does not exist | |
| if [ ! -d "docs" ]; then | |
| dunderlab_docs quickstart '--project "${{ vars.DOCS_PROJECT_NAME }}" --author "${{ vars.DOCS_AUTHOR }}" --extensions nbsphinx,dunderlab.docs --no-batchfile --quiet --sep' | |
| fi | |
| # Generates API documentation and builds HTML and Latex PDF if SUBMODULE is set | |
| if [ -n "${{ vars.DOCS_SUBMODULE }}" ]; then | |
| dunderlab_docs apidoc "${{ vars.DOCS_MODULE }}" | |
| dunderlab_docs build html "${{ vars.DOCS_MODULE }}/${{ vars.DOCS_SUBMODULE }}" | |
| dunderlab_docs build latexpdf "${{ vars.DOCS_MODULE }}/${{ vars.DOCS_SUBMODULE }}" | |
| else | |
| dunderlab_docs apidoc "${{ vars.DOCS_MODULE }}" | |
| dunderlab_docs build html "${{ vars.DOCS_MODULE }}" | |
| dunderlab_docs build latexpdf "${{ vars.DOCS_MODULE }}" | |
| fi | |
| # Adds a configuration file for Read the Docs | |
| # Verifies if .readthedocs.yml exists, if not, creates it | |
| if [ ! -f ".readthedocs.yml" ]; then | |
| echo """# .readthedocs.yml | |
| # Read the Docs configuration file | |
| # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details | |
| # Required | |
| version: 2 | |
| # Build documentation in the docs/ directory with Sphinx | |
| sphinx: | |
| configuration: docs/source/conf.py | |
| # Optionally set the version of Python and requirements required to build your docs | |
| python: | |
| install: | |
| - requirements: docs/requirements | |
| # Set the version of Python and other tools you might need | |
| build: | |
| os: ubuntu-22.04 | |
| tools: | |
| python: \"3.11\" | |
| formats: | |
| - epub | |
| """ >> .readthedocs.yml | |
| fi | |
| # Commit all changed files back to the repository | |
| - uses: stefanzweifel/git-auto-commit-action@v5 |