Add skeleton for complete docs #16
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
| ### | |
| # ```{rubric} MarkdownLint GitHub Actions | |
| # ``` | |
| # --- | |
| # This is a basic workflow to help you get started with Actions. | |
| # | |
| # ```{literalinclude} /.github/workflows/documentation.yml | |
| # :language: yaml | |
| # :start-at: "name: Documentation\n" | |
| # :end-before: "###\n" | |
| # ``` | |
| # | |
| # Set a name for the workflow. | |
| name: Documentation | |
| on: | |
| pull_request: | |
| branches: ["main"] | |
| push: | |
| branches: ["main"] | |
| workflow_dispatch: {} | |
| ### | |
| # ```{rubric} Permissions Updates | |
| # ``` | |
| # --- | |
| # Enable read for contents and issues, and write for checks and PRs. | |
| # | |
| # ```{literalinclude} /.github/workflows/documentation.yml | |
| # :language: yaml | |
| # :start-at: "permissions:\n" | |
| # :end-before: "###\n" | |
| # ``` | |
| permissions: | |
| contents: read | |
| issues: read | |
| checks: write | |
| pull-requests: write | |
| ### | |
| # ```{rubric} Workflow Jobs | |
| # ``` | |
| # --- | |
| # A workflow run is made up of one or more | |
| # jobs that can run sequentially or in parallel | |
| # | |
| # ```{literalinclude} /.github/workflows/documentation.yml | |
| # :language: yaml | |
| # :start-at: "jobs:\n" | |
| # :end-before: "###\n" | |
| # ``` | |
| jobs: | |
| ### | |
| # ```{rubric} markdownlint | |
| # ``` | |
| # --- | |
| # Check that the markdown in this repo is up to our (arbitrary) standards. | |
| # | |
| # ```{literalinclude} /.github/workflows/documentation.yml | |
| # :language: yaml | |
| # :start-at: "markdownlint:\n" | |
| # :end-before: "###\n" | |
| # ``` | |
| markdownlint: | |
| runs-on: ubuntu-latest | |
| steps: | |
| - uses: actions/checkout@main | |
| - name: Set up NodeJS | |
| uses: actions/setup-node@main | |
| - name: Install the checker | |
| run: npm i -g markdownlint-cli2 markdownlint-cli2-formatter-junit --save-dev | |
| - name: Lint the Markdown | |
| run: markdownlint-cli2 **/*.md *.md | |
| - name: Publish Test Results | |
| uses: EnricoMi/publish-unit-test-result-action@v2 | |
| if: always() | |
| with: | |
| check_name: markdownlint | |
| comment_title: "Markdown Lint" | |
| files: markdownlint-cli2-junit.xml | |
| ### | |
| # ```{rubric} Build GitHub Pages Site | |
| # ``` | |
| # --- | |
| # Build the pages site using Sphinx and upload the resulting artifact. | |
| # | |
| # ```{literalinclude} /.github/workflows/documentation.yml | |
| # :language: yaml | |
| # :start-at: " build:\n" | |
| # :end-before: "###\n" | |
| # ``` | |
| build: | |
| needs: markdownlint | |
| runs-on: ubuntu-20.04 | |
| permissions: | |
| pages: write | |
| id-token: write | |
| steps: | |
| - uses: actions/checkout@main | |
| with: | |
| fetch-depth: 0 | |
| - uses: actions/setup-python@main | |
| with: | |
| python-version: 3.11 | |
| - name: Setup pages | |
| uses: actions/configure-pages@main | |
| - name: Install pipenv | |
| run: curl https://raw.githubusercontent.com/pypa/pipenv/master/get-pipenv.py | python | |
| - name: Install Python dependencies | |
| run: | | |
| pipenv install --dev | |
| pipenv install -e . | |
| - name: Build the static site | |
| run: pipenv run sphinx-build -a -E . deploy | |
| - name: Upload artifact | |
| uses: actions/upload-pages-artifact@main | |
| with: | |
| path: './deploy' | |
| ### | |
| # ```{rubric} Deploy the Pages site | |
| # ``` | |
| # --- | |
| # Download the artifact and deploy to pages. | |
| # | |
| # ```{literalinclude} /.github/workflows/documentation.yml | |
| # :language: yaml | |
| # :start-at: " pages:\n" | |
| # ``` | |
| pages: | |
| needs: build | |
| runs-on: ubuntu-20.04 | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| permissions: | |
| pages: write | |
| id-token: write | |
| steps: | |
| - name: Download pages artifact | |
| id: download | |
| uses: actions/download-artifact@main | |
| - name: Deploy to GitHub Pages | |
| id: deployment | |
| uses: actions/deploy-pages@v4 |