-
Notifications
You must be signed in to change notification settings - Fork 40
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Automate versioned documentation (#951)
# Automate versioned documentation Use `mike` for versioned documentation. Reuse the tested setup from the OPTIMADE Gateway, ## New CD workflow for updating `master` docs. This will deploy and update the `latest` version (alias `master`) whenever a push event to `master` happens. It will not update the CHANGELOG or other things. Indeed, it will fail if the API Reference in the documentation has not been properly updated. The "regular" CD workflow has been updated with versioned documentation deployment, as well as a new feature: The release description on GitHub will be updated with the changelog for that particular version. This changelog will be *appended* to the existing description. One should now make sure to have a proper 1st level markdown header in the description, since the appended changelog will introduce a similar level header: `# Changelog`. ## Add a bunch of new pre-commit hooks and run them Add pre-commit hook for creating API Ref. doc. Added also: - check-symlinks - destroyed-symlinks - requirements-txt-fixer And changed settings for `trailing-whitespace` to utilize the `markdown-linebreak-ext` option instead of excluding README.md. This is better, since it will now find and correct single trailing white space, but not double (which is part of markdown syntax). To learn more about what the hooks do see: https://github.com/pre-commit/pre-commit-hooks#readme Update pre-commit hook `black`. ## Include untracked files in API Ref. when deploying. Untracked files might be new files under the API Reference folder that reflect new modules. ## Other updates Move around and rename files under `.github`. Update to vMAJOR for all GH Action tags. Checking that they actually point to the latest full version number. Only use target for `git status --porcelain`.
- Loading branch information
Showing
15 changed files
with
240 additions
and
112 deletions.
There are no files selected for viewing
File renamed without changes.
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
File renamed without changes.
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,67 @@ | ||
| name: CD Documentation | ||
|
|
||
| on: | ||
| push: | ||
| branches: | ||
| - master | ||
|
|
||
| jobs: | ||
| deploy: | ||
| name: Deploy `latest` documentation | ||
| if: github.repository_owner == 'Materials-Consortia' | ||
| runs-on: ubuntu-latest | ||
|
|
||
| steps: | ||
| - name: Release check | ||
| run: | | ||
| COMMIT_MSG="$(gh api /repos/${{ github.repository}}/commits/main --jq '.commit.message')" | ||
| if [[ "${COMMIT_MSG}" =~ ^Release\ v.*\ -\ Changelog$ ]]; then | ||
| echo "In a release - do not run this job !" | ||
| echo "RELEASE_RUN=true" >> $GITHUB_ENV | ||
| else | ||
| echo "Not a release - update docs" | ||
| echo "RELEASE_RUN=false" >> $GITHUB_ENV | ||
| fi | ||
| env: | ||
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | ||
|
|
||
| - name: Checkout repository | ||
| if: env.RELEASE_RUN == 'false' | ||
| uses: actions/checkout@v2 | ||
| with: | ||
| fetch-depth: 0 | ||
| submodule: true | ||
|
|
||
| - name: Set up Python 3.8 | ||
| if: env.RELEASE_RUN == 'false' | ||
| uses: actions/setup-python@v2 | ||
| with: | ||
| python-version: 3.8 | ||
|
|
||
| - name: Install dependencies | ||
| if: env.RELEASE_RUN == 'false' | ||
| run: | | ||
| python -m pip install --upgrade pip | ||
| pip install -U setuptools wheel | ||
| pip install -U -e .[all] | ||
| - name: Set up git user | ||
| if: env.RELEASE_RUN == 'false' | ||
| run: | | ||
| git config --global user.name "OPTIMADE Developers" | ||
| git config --global user.email "dev@optimade.org" | ||
| - name: Check API Reference and landing page | ||
| if: env.RELEASE_RUN == 'false' | ||
| run: | | ||
| invoke create-api-reference-docs --pre-clean | ||
| if [ -n "$(git status --porcelain docs/api_reference)" ]; then | ||
| echo "The following files in the documentation have not been committed:" | ||
| git status --porcelain docs/api_reference | ||
| exit 1 | ||
| fi | ||
| - name: Deploy documentation | ||
| if: env.RELEASE_RUN == 'false' | ||
| run: mike deploy --push --remote origin --branch gh-pages --update-aliases --config-file mkdocs.yml latest master |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,85 @@ | ||
| name: Publish and Deploy | ||
|
|
||
| on: | ||
| release: | ||
| types: | ||
| - published | ||
|
|
||
| jobs: | ||
|
|
||
| publish: | ||
| name: Publish OPTIMADE Python tools | ||
| runs-on: ubuntu-latest | ||
| if: github.repository == 'Materials-Consortia/optimade-python-tools' && startsWith(github.ref, 'refs/tags/v') | ||
| env: | ||
| PUBLISH_UPDATE_BRANCH: master | ||
|
|
||
| steps: | ||
| - name: Checkout repository | ||
| uses: actions/checkout@v2 | ||
| with: | ||
| submodules: true | ||
| fetch-depth: 0 | ||
|
|
||
| - name: Set up Python 3.8 | ||
| uses: actions/setup-python@v2 | ||
| with: | ||
| python-version: 3.8 | ||
|
|
||
| - name: Install Python dependencies | ||
| run: | | ||
| python -m pip install -U pip | ||
| pip install -U setuptools | ||
| pip install -U -e .[all] | ||
| - name: Update changelog | ||
| uses: CharMixer/auto-changelog-action@v1 | ||
| with: | ||
| token: ${{ secrets.RELEASE_PAT_CASPER }} | ||
| release_branch: ${{ env.PUBLISH_UPDATE_BRANCH }} | ||
|
|
||
| - name: Update API Reference docs and version - Commit changes and update tag | ||
| run: .github/utils/update_docs.sh | ||
|
|
||
| - name: Update '${{ env.PUBLISH_UPDATE_BRANCH }}' | ||
| uses: CasperWA/push-protected@v2 | ||
| with: | ||
| token: ${{ secrets.RELEASE_PAT_CASPER }} | ||
| branch: ${{ env.PUBLISH_UPDATE_BRANCH }} | ||
| unprotect_reviews: true | ||
| sleep: 15 | ||
| force: true | ||
| tags: true | ||
|
|
||
| - name: Get tagged versions | ||
| run: echo "PREVIOUS_VERSION=$(git tag -l --sort -version:refname | sed -n 2p)" >> $GITHUB_ENV | ||
|
|
||
| - name: Create release-specific changelog | ||
| uses: CharMixer/auto-changelog-action@v1 | ||
| with: | ||
| token: ${{ secrets.RELEASE_PAT_CASPER }} | ||
| release_branch: ${{ env.PUBLISH_UPDATE_BRANCH }} | ||
| since_tag: "${{ env.PREVIOUS_VERSION }}" | ||
| output: "release_changelog.md" | ||
|
|
||
| - name: Append changelog to release body | ||
| run: | | ||
| gh api /repos/${{ github.repository }}/releases/${{ github.event.release.id }} --jq '.body' > release_body.md | ||
| cat release_changelog.md >> release_body.md | ||
| gh api /repos/${{ github.repository }}/releases/${{ github.event.release.id }} -X PATCH -F body='@release_body.md' | ||
| env: | ||
| GITHUB_TOKEN: ${{ secrets.RELEASE_PAT_CASPER }} | ||
|
|
||
| - name: Build source distribution | ||
| run: python ./setup.py sdist | ||
|
|
||
| - name: Publish package to PyPI | ||
| uses: pypa/gh-action-pypi-publish@master | ||
| with: | ||
| user: __token__ | ||
| password: ${{ secrets.PYPI_PASSWORD }} | ||
|
|
||
| - name: Deploy documentation | ||
| run: | | ||
| mike deploy --push --remote origin --branch gh-pages --update-aliases --config-file mkdocs.yml ${GITHUB_REF#refs/tags/v} stable | ||
| mike deploy --push --remote origin --branch gh-pages --update-aliases --config-file mkdocs.yml latest master |
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
Oops, something went wrong.