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

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@v6.0
      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@v6.0
      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@v6.0

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
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

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@v6.0
      with:
          cname: "<library>.docs.pyansys.com"
          token: ${{ secrets.GITHUB_TOKEN }}

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 guidelines for migrating to the latest multi-version documentation layout .

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
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

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@v6.0
      with:
          cname: "<library>.docs.pyansys.com"
          token: ${{ secrets.GITHUB_TOKEN }}

Doc deploy index action

This action automates the process of creating indexes and scraping the HTML documentation artifact that contains the development version of a library, then deploying it to a Meilisearch instance.

Source code for this action

Input	Description	Required	Type	Default
cname	The CNAME (canonical Name) that points to the documentation website for a specific version, specifically intended for scraping purposes. The format of the CNAME should be “cname/version/version-number,” where: - “cname” is the main Canonical Name - “version-number” is the specific number associated with the version (e.g., 0.1, 0.2, 0.3).	True	string
index-name	The identifier given to the documentation in pymeilisearch.	True	string
api-key	The API key used to access the Meilisearch instance host.	True	string
host-url	The URL where the Meilisearch instance is hosted.	True	string
python-version	Python version used for execution of the stable docs scraping.	False	string	3.10
doc-artifact-name	The name of the HTML documentation artifact. This artifact is expected to contain all the HTML and static files.The dafault value is documentation-html.	False	string	documentation-html
template	The “template” parameter specifies the layout used for the HTML documentation. By default, it is set to sphinx_pydata which assumes that the document is constructed using the pydata-sphinx-theme or its associated theme, such as the ansys-sphinx-theme.	False	string	sphinx_pydata
decompress-artifact	Whether to decompress the doc-artifact-name file using ouch as decompression tool. Default value is false.	False	string	False
pymeilisearchopts	A list of pyemeilisearch options when scraping URLs. See pymeilisearch user guide for available options	False	string

Examples

Index the documentation and scrap using pymeilisearch

doc-deploy-dev:
  name: "Index the documentation and scrap using pymeilisearch"
  runs-on: ubuntu-latest
  needs: doc-deploy
  if: github.event_name == 'push'
  steps:
    - name: "Deploy the latest documentation index"
      uses: ansys/actions/doc-deploy-index@v6.0
      with:
          cname: "<library>.docs.pyansys.com/version/<version-number>"
          index-name: "<index-name>"
          host-url: "<meilisearch-host-url>"
          api-key: ${{ secrets.MEILISEARCH-API-KEY }}