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.
Input |
Description |
Required |
Type |
Default |
---|---|---|---|---|
python-version |
Python version used for installing and running |
False |
string |
3.10 |
use-python-cache |
Whether to use the Python cache for installing previously downloaded libraries. If |
False |
boolean |
True |
sphinxopts |
Set of options to pass to the 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 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 |
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 |
False |
boolean |
True |
skip-json-build |
Whether to skip the generation of JSON documentation. Default value is |
False |
boolean |
True |
check-links |
Whether to perform external link checks during the generation of documentation. Default value is |
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.
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 |
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 |
False |
string |
documentation-html |
decompress-artifact |
Wether to decompress the artifact using ouch as decompression tool. Default value is |
False |
string |
False |
repository |
Repository name in the form of |
False |
string |
current |
branch |
Branch name for deploying the documentation. The |
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 |
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 .
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 |
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 |
False |
string |
documentation-html |
decompress-artifact |
Whether to decompress the |
False |
string |
False |
repository |
Repository name in the form of |
False |
string |
current |
branch |
Branch name for deploying the documentation. The |
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 |
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 |
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.
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 |
False |
string |
documentation-html |
template |
The “template” parameter specifies the layout used for the HTML documentation. By default, it is set to |
False |
string |
sphinx_pydata |
decompress-artifact |
Whether to decompress the |
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 }}