From 0bd1b7006b93c976a2275bab1343a027679fde84 Mon Sep 17 00:00:00 2001 From: Chris Butler Date: Tue, 19 Nov 2024 14:57:58 +1100 Subject: [PATCH] feat: decouple docs release and introduce versioning (#1752) * fix: decouple docs Signed-off-by: Chris Butler * feat: add support for mike Signed-off-by: Chris Butler --------- Signed-off-by: Chris Butler --- .github/workflows/docs-update.yml | 75 +++++++++++++++++++++++++++++++ .github/workflows/python-push.yml | 35 --------------- docs/js/.keep | 0 mkdocs.yml | 11 ++++- setup.cfg | 1 + 5 files changed, 86 insertions(+), 36 deletions(-) create mode 100644 .github/workflows/docs-update.yml create mode 100644 docs/js/.keep diff --git a/.github/workflows/docs-update.yml b/.github/workflows/docs-update.yml new file mode 100644 index 000000000..8e4d0951c --- /dev/null +++ b/.github/workflows/docs-update.yml @@ -0,0 +1,75 @@ +# This workflow will install Python dependencies, run tests and lint with a variety of Python versions +# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions +name: Trestle Docs update +on: + push: + branches: + - develop + tags: + - v* + +jobs: + set-versions: + runs-on: ubuntu-latest + outputs: + min: ${{ steps.versions.outputs.min }} + max: ${{ steps.versions.outputs.max }} + steps: + - uses: actions/checkout@v4 + - id: versions + run: | + min_version=$(jq '.PYTHON_MIN' -r version.json) + max_version=$(jq '.PYTHON_MAX' -r version.json) + echo "min=$min_version" + echo "max=$max_version" + echo "min=$min_version" >> $GITHUB_OUTPUT + echo "max=$max_version" >> $GITHUB_OUTPUT + mike-version: + runs-on: ubuntu-latest + needs: [ set-versions] + outputs: + mver: ${{ steps.versions.mver }} + steps: + - uses: actions/checkout@v4 + - name: Set up Python ${{ needs.set-versions.outputs.max }} + uses: actions/setup-python@v5 + # This is deliberately not using a custom credential as it relies on native github actions token to have push rights. + with: + python-version: ${{ needs.set-versions.outputs.max }} + - id: versions + run: | + mike_version=$(python ./scripts/check-version.py ${{ env.GITHUB_REF }}) + echo "mver=$mike_version" >> $GITHUB_OUTPUT + deploy-docs: + runs-on: ubuntu-latest + needs: [ mike-version ] + steps: + - uses: actions/create-github-app-token@v1 + id: app-token + with: + app-id: ${{ secrets.APP_ID }} + private-key: ${{ secrets.PRIVATE_KEY }} + - uses: actions/checkout@v4 + with: + submodules: true + fetch-depth: 0 + token: ${{ steps.app-token.outputs.token }} + - name: Set up Python ${{ needs.set-versions.outputs.max }} + uses: actions/setup-python@v5 + # This is deliberately not using a custom credential as it relies on native github actions token to have push rights. + with: + python-version: ${{ needs.set-versions.outputs.max }} + - name: Install build tools + run: | + make develop + - name: Install documenation dependencies + run: | + make docs-ubuntu-deps + - name: Create release + shell: bash + run: | + mike deploy ${{ needs.mike-version.outputs.mver }} + - name: Ensure latest is latest + shell: bash + run: | + mike set-default latest \ No newline at end of file diff --git a/.github/workflows/python-push.yml b/.github/workflows/python-push.yml index 9d5909115..2ef301f4b 100644 --- a/.github/workflows/python-push.yml +++ b/.github/workflows/python-push.yml @@ -153,41 +153,6 @@ jobs: with: github_token: ${{ steps.app-token.outputs.token }} - deploy-docs: - runs-on: ubuntu-latest - needs: [ deploy, set-versions ] - concurrency: - group: ${{ github.ref }}-${{ github.workflow }}-${{ github.job }}-docs - cancel-in-progress: true - # Temporary hack: allow develop as well as master to deploy docs. - if: github.ref == 'refs/heads/main' - steps: - - uses: actions/create-github-app-token@v1 - id: app-token - with: - app-id: ${{ secrets.APP_ID }} - private-key: ${{ secrets.PRIVATE_KEY }} - - uses: actions/checkout@v4 - with: - submodules: true - fetch-depth: 0 - token: ${{ steps.app-token.outputs.token }} - - name: Set up Python ${{ needs.set-versions.outputs.max }} - uses: actions/setup-python@v5 - # This is deliberately not using a custom credential as it relies on native github actions token to have push rights. - with: - python-version: ${{ needs.set-versions.outputs.max }} - - name: Install build tools - run: | - make develop - - name: Install documenation dependencies - run: | - make docs-ubuntu-deps - - name: Create release - shell: bash - run: | - mkdocs gh-deploy - merge-main-to-develop: name: Merge main -> develop runs-on: ubuntu-latest diff --git a/docs/js/.keep b/docs/js/.keep new file mode 100644 index 000000000..e69de29bb diff --git a/mkdocs.yml b/mkdocs.yml index 51c762f3e..5f808ec26 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -36,7 +36,7 @@ plugins: raise_error_excludes: # This is to remove some false positives for links which work. # Anchors are validated again by core mkdocs - 404: ['#trestle.*'] + 404: [ '#trestle.*' ] - mkdocstrings: default_handler: python handlers: @@ -61,6 +61,15 @@ plugins: - css/mkdocstrings.css htmlmin_opts: remove_comments: true +- mike: + # These fields are all optional; the defaults are as below... + alias_type: symlink + redirect_template: null + deploy_prefix: '' + canonical_version: latest + version_selector: true + css_dir: css + javascript_dir: js repo_name: oscal-compass/compliance-trestle repo_url: https://github.com/oscal-compass/compliance-trestle site_description: Documentation for compliance-trestle package. diff --git a/setup.cfg b/setup.cfg index d965db771..9627497da 100644 --- a/setup.cfg +++ b/setup.cfg @@ -79,6 +79,7 @@ dev = types-requests types-setuptools # # Docs website + mike mkdocs>=1.6.0 mkdocs-awesome-pages-plugin mkdocstrings[python]>=0.25.2