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 |
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 Warning The HTML files are expected to be contained in |
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@v6.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@v6.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@v6.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.
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 |
use-latest-index-in-landing-page |
Use the latest ‘version/{stable|dev}/index.html’ in the landing page. Default
value is |
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@v6.1
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 Enable multi-version documentation .
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 |
use-latest-index-in-landing-page |
Use the latest ‘version/{stable|dev}/index.html’ in the landing page. Default
value is |
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@v6.1
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.1
with:
cname: "<library>.docs.pyansys.com/version/<version-number>"
index-name: "<index-name>"
host-url: "<meilisearch-host-url>"
api-key: ${{ secrets.MEILISEARCH-API-KEY }}