Documentation actions

Documentation actions build and deploy the documentation of a PyAnsys project.

To use these actions, a project must use Sphinx as documentation parser.

Doc build action

Build library documentation using Sphinx. The action installs documentation dependencies provided either in a requirement file, e.g. requirements/requirements_doc.txt, or in the [doc] section of the additional dependencies in the pyproject.toml file. Assuming that sphinx-build is available after installing the documentation dependencies, the action uses it to generate documentation from the source. It requires that all the documentation is contained in the doc/ directory of a project. Depending on the operating system, the action locates the doc/Makefile (resp. doc/make.bat) file for Linux (resp. Windows) and runs the make html (resp. make.bat html) and make pdf (resp. make.bat pdf) commands. If desired, the make json (resp. make.bat json) command can also be executed to generate JSON documentation.

Source code for this action

Input	Description	Required	Type	Default
python-version	Python version used for installing and running Sphinx.	False	string	3.10
use-python-cache	Whether to use the Python cache for installing previously downloaded libraries. If true, previously downloaded libraries are installed from the Python cache. If false, libraries are downloaded from the PyPI index.	False	boolean	True
sphinxopts	Set of options to pass to the Sphinx builder. Default options include using the maximum number of cores in the CPU of the machine and treating warnings as errors. Note This will override the SPHINXOPTS declared in your Makefile.	False	string	-j auto -W –keep-going
dependencies	String of system dependencies to be installed before building the documentation of the project.	False	string
skip-dependencies-cache	Whether to ignore dependencies cache or not - for OS libraries.	True	boolean	False
requires-xvfb	Whether to install X Virtual Frame Buffer (XVFB) and run the whole test session using XVFB. The default value is false. If true, installs X Virtual Frame Buffer (XVFB) and runs the whole test session using XVFB. Default value is false. Warning This option is not taken into account when runner os is 'Windows'.	False	boolean	False
skip-install	Whether to skip the installation of the project. The default is false. Pure documentation projects require that this action be set to false because there is no Python library associated with the project.	False	boolean	False
requirements-file	Path to the requirements file in case it needs to be in a specific location. This is useful for non python projects, where you don’t necessarily have a requirements file in the root of the project.	False	string	requirements/requirements_doc.txt
checkout	Whether to clone the repository in the CI/CD machine. Default value is true.	False	boolean	True
skip-json-build	Whether to skip the generation of JSON documentation. Default value is true.	False	boolean	True
check-links	Whether to perform external link checks during the generation of documentation. Default value is true.	False	boolean	True
add-pdf-html-docs-as-assets	Whether to add PDF and HTML documentation as assets of the HTML documentation. The HTML documentation is compressed before being added. The PDF file name is expected to be the same as the project name defined in the pyproject.toml file. Default value is false. Warning The HTML files are expected to be contained in doc/_build and the PDF file is copied in doc/_build/html/_static/assets/download. If such directories do not exist in your repo, the action will fail.	False	boolean	False
needs-quarto	Whether to add a Quarto cheatsheet to the documentation. Default value is false. .. warning: Quarto needs Jupyter to be installed. Make sure to add `Jupyter <https://pypi.org/project/jupyter/>` to the requirements list.	False	boolean	False

Examples

Installing additional system dependencies for building documentation

doc-build:
  name: "Installing additional system dependencies for building documentation"
  runs-on: ubuntu-latest
  needs: doc-style
  steps:
    - name: "Run Ansys documentation building action"
      uses: ansys/actions/doc-build@v8.1
      with:
        dependencies: "graphviz mermaid-cli"

Building library documentation that using XVFB

doc-build:
  name: "Building library documentation that using XVFB"
  runs-on: ubuntu-latest
  needs: doc-style
  steps:
    - name: "Run Ansys documentation building action"
      uses: ansys/actions/doc-build@v8.1
      with:
        requires-xvfb: true

Building library documentation

doc-build:
  name: "Building library documentation"
  runs-on: ubuntu-latest
  needs: doc-style
  steps:
    - name: "Run Ansys documentation building action"
      uses: ansys/actions/doc-build@v8.1

Doc deploy dev action

This action deploys the desired HTML documentation artifact containing the development version of a library to the specified branch of a repository. By default, the gh-pages branch of the current repository is assumed.

Source code for this action

Input	Description	Required	Type	Default
cname	The canonical name (CNAME) containing the documentation.	True	string
token	Required password, key or token with the correct credentials for deploying the documentation. If deploying to the current repository, the secrets.GITHUB_TOKEN token is enough. For workflows deploying to other repositories, generate and use a token with writing access to that repository.	True	string
bot-user	Use the PYANSYS_CI_BOT_USERNAME as the user for a git commit & push.	True	string
bot-email	Use the PYANSYS_CI_BOT_EMAIL as the email for a git commit & push.	True	string
doc-artifact-name	Name of the HTML documentation artifact. This artifact is expected to contain all the HTML and static files. If it contains a compressed file, make sure you enable the decompress-artifact option.	False	string	documentation-html
decompress-artifact	Wether to decompress the artifact using ouch as decompression tool. Default value is false.	False	string	False
repository	Repository name in the form of username/repository to be used for deploying the documentation. The current repository is assumed by default.	False	string	current
branch	Branch name for deploying the documentation. The gh-pages branch is used by default.	False	string	gh-pages
commit-message	Commit message used when deploying the documentation.	False	string	DOC: update development documentation
force-orphan	Whether to force the deployment branch to be orphan with only the latest commit or not. Default value is true.	False	string	True
content-element-id	Identifier of the HTML tag that comprises all the content of the article or post.	False	string	main-content
use-latest-index-in-landing-page	Use the latest ‘version/{stable|dev}/index.html’ in the landing page. Default value is true. By default, the index.html is overwritten by version/{stable|dev}/index.html.	False	string	True

Examples

Deploy developers documentation

doc-deploy-dev:
  name: "Deploy developers documentation"
  runs-on: ubuntu-latest
  needs: doc-build
  if: github.event_name == 'push'
  steps:
    - name: "Deploy the latest documentation"
      uses: ansys/actions/doc-deploy-dev@v8.1
      with:
          cname: "<library>.docs.pyansys.com"
          token: ${{ secrets.GITHUB_TOKEN }}
          bot-user: ${{ secrets.PYANSYS_CI_BOT_USERNAME }}
          bot-email: ${{ secrets.PYANSYS_CI_BOT_EMAIL }}

Doc deploy stable action

This action deploys the desired HTML documentation artifact containing the stable version of a library to the specified branch of a repository. By default, the gh-pages branch of the current repository is assumed.

Note

If your project is using ansys/actions@v3 or lower and you would like to update to this version of the actions, see the Enable multi-version documentation .

Source code for this action

Input	Description	Required	Type	Default
cname	The canonical name (CNAME) containing the documentation.	True	string
token	Required password, key or token with the correct credentials for deploying the documentation. If deploying to the current repository, the secrets.GITHUB_TOKEN token is is enough. For workflows deploying to other repositories, generate and use a token with writing access to that repository.	True	string
bot-user	Use the PYANSYS_CI_BOT_USERNAME as the user for a git commit & push.	True	string
bot-email	Use the PYANSYS_CI_BOT_EMAIL as the email for a git commit & push.	True	string
doc-artifact-name	Name of the HTML documentation artifact. This artifact is expected to contain all the HTML and static files. If it contains a compressed file, make sure you enable the decompress-artifact option.	False	string	documentation-html
decompress-artifact	Whether to decompress the doc-artifact-name file using ouch as decompression tool. Default value is false.	False	string	False
repository	Repository name in the form of username/repository to be used for deploying the documentation. The current repository is assumed by default.	False	string	current
branch	Branch name for deploying the documentation. The gh-pages branch is used by default.	False	string	gh-pages
commit-message	Commit message used when deploying the documentation.	False	string	DOC: update development documentation
render-last	The number of stable versions to be shown in the version drop-down.	False	string	3
force-orphan	Whether to force the deployment branch to be orphan or not. Default value is true.	False	string	True
content-element-id	Identifier of the HTML tag that comprises all the content of the article or post.	False	string	main-content
independent-patch-release-docs	Whether to generate documentation for independent patch releases. Default value is false. By default, patch releases will overwrite the documentation of the previous patch release. If this option is enabled, then the documentation of each patch release will be kept.	False	boolean	False
use-latest-index-in-landing-page	Use the latest ‘version/{stable|dev}/index.html’ in the landing page. Default value is true. By default, the index.html is overwritten by version/{stable|dev}/index.html.	False	string	True

Examples

Deploy stable documentation

doc-deploy-stable:
  name: "Deploy stable documentation"
  runs-on: ubuntu-latest
  needs: doc-build
  if: github.event_name == 'push' && contains(github.ref, 'refs/tags')
  steps:
    - name: "Deploy the stable documentation"
      uses: ansys/actions/doc-deploy-stable@v8.1
      with:
          cname: "<library>.docs.pyansys.com"
          token: ${{ secrets.GITHUB_TOKEN }}
          bot-user: ${{ secrets.PYANSYS_CI_BOT_USERNAME }}
          bot-email: ${{ secrets.PYANSYS_CI_BOT_EMAIL }}

Doc changelog action

Adds a newsfragment to the target repository using towncrier containing the title and number of the pull request.

This action will only work on Linux/macOS runners.

Source code for this action

Input	Description	Required	Type	Default
token	Use the PYANSYS_CI_BOT_TOKEN to do a git commit & push. The “contents: write” and “pull-requests: write” permissions are required for this action.	True	string
bot-user	Use the PYANSYS_CI_BOT_USERNAME as the user for a git commit & push.	True	string
bot-email	Use the PYANSYS_CI_BOT_EMAIL as the email for a git commit & push.	True	string
python-version	Python version used for setting up Python.	False	string	3.10
towncrier-version	Towncrier version used for creating fragment files.	False	string	23.11.0
toml-version	Toml version used for retrieving the towncrier directory.	False	string	0.10.2
use-python-cache	Whether to use the Python cache for installing previously downloaded libraries. If true, previously downloaded libraries are installed from the Python cache. If false, libraries are downloaded from the PyPI index.	False	boolean	True
use-conventional-commits	Use conventional commits to cateogrize towncrier fragments.	False	boolean	False
use-default-towncrier-config	Use the default towncrier configuration in the pyproject.toml file.	False	boolean	False

Examples

Create changelog fragment

# Add these lines to .github/workflows/label.yml so the changelog fragment
# is updated when the PR is labeled & the title changes:
# on:
#   pull_request:
#     # opened, reopened, and synchronize are default for pull_request
#     # edited - when PR title or body is changed
#     # labeled - when labels are added to PR
#     types: [opened, reopened, synchronize, edited, labeled]

# Put changelog-fragment action in .github/workflows/label.yml
# Don't forget to add pyansys-ci-bot as a member of your repository
changelog-fragment:
  name: "Create changelog fragment"
  needs: [labeler]
  permissions:
    contents: write
    pull-requests: write
  runs-on: ubuntu-latest
  steps:
    - uses: ansys/actions/doc-changelog@v8.1
      with:
        token: ${{ secrets.PYANSYS_CI_BOT_TOKEN }}
        bot-user: ${{ secrets.PYANSYS_CI_BOT_USERNAME }}
        bot-email: ${{ secrets.PYANSYS_CI_BOT_EMAIL }}
        # uncomment this line to use conventional commits instead of labels
        # use-conventional-commits: true
        # uncomment this if you don't have any towncrier configuration in your pyproject.toml file
        # use-default-towncrier-config: true

Doc deploy changelog action

Builds the CHANGELOG using towncrier fragment files for the tagged version. Creates a pull request into main with the CHANGELOG updates and deleted towncrier fragment files.

This action will only work on Linux/macOS runners.

Pushing a release tag results in this action running twice:

• Once to run towncrier and consolidate the changelog fragment files into a single update of the CHANGELOG file.

• Once to release the package after the CHANGELOG file has been updated.

There are two options when making a release for your repository:

1. You pushed a tag from a release branch (release-from-main is false)

This is the most common case for PyAnsys repositories. The following steps are performed when release-from-main is false:

a) Find a release branch that has the same major and minor version of the tag that was pushed. For example, if your tag was “v0.1.2”, it looks for a release branch named “release/0.1”. If the release branch cannot be found, a temporary branch is used named “maint/changelog-update-vTAG_VERSION”.

b) Checkout the release or temporary branch, update the CHANGELOG file using towncrier, and push the updates to the respective branch.

c) Checkout the main branch and create a pull request branch named “maint/vTAG_VERSION-changelog”. Delete the pull request branch from the remote if it exists, checkout the pull request branch, cherry pick the commit containing the CHANGELOG file changes from the previous step, push the pull request branch, and create a pull request from the branch into main.

d) Checkout the release or temporary branch, delete the tag locally and on the remote, create the new tag locally, and push the tag on the remote. Delete the temporary branch if one was used to update the CHANGELOG file.

e) Exit on error if the CHANGELOG is updated, so that the package is not released from this instance of the workflow.

2. You pushed a tag from the main branch (release-from-main is true)

The following steps are performed when release-from-main is true:

a) Checkout the main branch, update the CHANGELOG file using towncrier, and push the updates to the main branch.

b) Checkout the main branch, delete the tag locally and on the remote, create the new tag locally, and push the new tag on the remote.

c) Exit on error if the CHANGELOG is updated, so that the package is not released from this instance of the workflow.

Source code for this action

Input	Description	Required	Type	Default
token	Use the PYANSYS_CI_BOT_TOKEN to do a git commit & push. The “contents: write” and “pull-requests: write” permissions are required for this action.	True	string
bot-user	Use the PYANSYS_CI_BOT_USERNAME as the user for a git commit & push.	True	string
bot-email	Use the PYANSYS_CI_BOT_EMAIL as the email for a git commit & push.	True	string
python-version	Python version used for setting up Python.	False	string	3.10
towncrier-version	Towncrier version used for updating the CHANGELOG file.	False	string	23.11.0
toml-version	Toml version used for retrieving the towncrier directory.	False	string	0.10.2
use-python-cache	Whether to use the Python cache for installing previously downloaded libraries. If true, previously downloaded libraries are installed from the Python cache. If false, libraries are downloaded from the PyPI index.	False	boolean	True
release-from-main	If false, you pushed a tag from a release branch. This is applicable for most PyAnsys repositories. If true, you pushed a tag from the main branch. See the description for more information about each of the options.	False	boolean	False
use-upper-case	Use of uppercase letters in the “type” field of: The PR created into main to add CHANGELOG changes. The commit created in the release branch to add the new section in CHANGELOG. If false, the title is “chore: … CHANGELOG for v…”. If true, the title is “CHORE: … CHANGELOG for v…”.	False	boolean	False

Examples

Update CHANGELOG for new tag

update-changelog:
  name: "Update CHANGELOG for new tag"
  if: github.event_name == 'push' && contains(github.ref, 'refs/tags')
  runs-on: ubuntu-latest
  permissions:
    contents: write
    pull-requests: write
  steps:
    - uses: ansys/actions/doc-deploy-changelog@v8.1
      with:
        token: ${{ secrets.PYANSYS_CI_BOT_TOKEN }}
        bot-user: ${{ secrets.PYANSYS_CI_BOT_USERNAME }}
        bot-email: ${{ secrets.PYANSYS_CI_BOT_EMAIL }}