From 17864fffd720cecf7fc6ba0d23e2c65703fb5ff3 Mon Sep 17 00:00:00 2001 From: Jean Henry <126060567+ansjhenry@users.noreply.github.com> Date: Mon, 19 Feb 2024 11:04:26 +0100 Subject: [PATCH] docs: Initialize the documentation (#3) * Initialize the documentation * Fix pre-commit issues * Update the doc url and disable the last action form the test workflow * Rename environment actions to query actions and move create-scade-env to tests actions --- .github/workflows/ci_cd.yml | 28 +- .gitignore | 2 + create-scade-venv/action.yml | 5 +- doc/.vale.ini | 28 ++ doc/Makefile | 30 ++ doc/make.bat | 50 +++ doc/source/_static/.gitkeep | 0 doc/source/conf.py | 385 ++++++++++++++++++ doc/source/index.rst | 30 ++ .../query-actions/examples/get-scade-dir.yml | 8 + .../examples/get-scade-python.yml | 8 + doc/source/query-actions/index.rst | 53 +++ .../examples/create-scade-venv.yml | 10 + .../examples/scade-tests-pytest-basic.yml | 10 + doc/source/tests-actions/index.rst | 58 +++ doc/styles/.gitignore | 4 + doc/styles/Vocab/ANSYS/accept.txt | 8 + doc/styles/Vocab/ANSYS/reject.txt | 0 get-scade-dir/action.yml | 6 +- get-scade-python/action.yml | 11 +- requirements/requirements_doc.txt | 7 + 21 files changed, 728 insertions(+), 13 deletions(-) create mode 100644 doc/.vale.ini create mode 100644 doc/Makefile create mode 100644 doc/make.bat create mode 100644 doc/source/_static/.gitkeep create mode 100644 doc/source/conf.py create mode 100644 doc/source/index.rst create mode 100644 doc/source/query-actions/examples/get-scade-dir.yml create mode 100644 doc/source/query-actions/examples/get-scade-python.yml create mode 100644 doc/source/query-actions/index.rst create mode 100644 doc/source/tests-actions/examples/create-scade-venv.yml create mode 100644 doc/source/tests-actions/examples/scade-tests-pytest-basic.yml create mode 100644 doc/source/tests-actions/index.rst create mode 100644 doc/styles/.gitignore create mode 100644 doc/styles/Vocab/ANSYS/accept.txt create mode 100644 doc/styles/Vocab/ANSYS/reject.txt create mode 100644 requirements/requirements_doc.txt diff --git a/.github/workflows/ci_cd.yml b/.github/workflows/ci_cd.yml index 27802eb..2b61e36 100644 --- a/.github/workflows/ci_cd.yml +++ b/.github/workflows/ci_cd.yml @@ -11,7 +11,7 @@ on: env: MAIN_SCADE_VERSION: '23.2' MAIN_PYTHON_VERSION: '3.10' - DOCUMENTATION_CNAME: 'scade-actions.docs.pyansys.com' + DOCUMENTATION_CNAME: 'actions.scade.docs.pyansys.com' test-library-name: 'ansys-scade-actions' concurrency: @@ -97,7 +97,7 @@ jobs: needs: commit-and-branch-style steps: - name: "Run code style checks" - uses: ansys/actions/code-style@main + uses: ansys/actions/code-style@v5 with: python-version: ${{ env.MAIN_PYTHON_VERSION }} use-python-cache: false @@ -116,7 +116,7 @@ jobs: needs: commit-and-branch-style steps: - name: "Run documentation style checks" - uses: ansys/actions/doc-style@main + uses: ansys/actions/doc-style@v5 with: token: ${{ secrets.GITHUB_TOKEN }} @@ -126,7 +126,7 @@ jobs: needs: doc-style steps: - name: "Build documentation" - uses: ansys/actions/doc-build@main + uses: ansys/actions/doc-build@v5 with: skip-install: true python-version: ${{ env.MAIN_PYTHON_VERSION }} @@ -164,8 +164,20 @@ jobs: target-dir: '.venvs' target-name: ${{ steps.get-scade-python.outputs.python-name }} - - name: Execute tests - uses: ./scade-tests-pytest + # no test application for now + # - name: Execute tests + # uses: ./scade-tests-pytest + # with: + # python-dir: ${{ steps.create-scade-venv.outputs.scripts-dir }} + # checkout: false + + doc-deploy-dev: + name: "Deploy developers documentation" + runs-on: ubuntu-latest + if: github.event_name == 'push' && !contains(github.ref, 'refs/tags') + needs: [doc-build, tests] + steps: + - uses: ansys/actions/doc-deploy-dev@v5 with: - python-dir: ${{ steps.create-scade-venv.outputs.scripts-dir }} - checkout: false + cname: ${{ env.DOCUMENTATION_CNAME }} + token: ${{ secrets.GITHUB_TOKEN }} diff --git a/.gitignore b/.gitignore index b6e4761..2b2f3c3 100644 --- a/.gitignore +++ b/.gitignore @@ -127,3 +127,5 @@ dmypy.json # Pyre type checker .pyre/ +doc/_build/ +*-rendered-example.yml diff --git a/create-scade-venv/action.yml b/create-scade-venv/action.yml index 9c2465c..f39a182 100644 --- a/create-scade-venv/action.yml +++ b/create-scade-venv/action.yml @@ -1,6 +1,9 @@ # create-scade-venv.yml name: 'Create a virtual Python environment' -description: 'A GitHub action creates a virutal Python environment in the target directory from a Python installation' +description: > + A GitHub action that creates a virtual Python environment in the target + directory from a Python installation. + inputs: python-dir: description: 'Directory containing a Python installation' diff --git a/doc/.vale.ini b/doc/.vale.ini new file mode 100644 index 0000000..5bdb32a --- /dev/null +++ b/doc/.vale.ini @@ -0,0 +1,28 @@ +# Core settings +# ============= + +# Location of our `styles` +StylesPath = "styles" + +# The options are `suggestion`, `warning`, or `error` (defaults to “warning”). +MinAlertLevel = warning + +# By default, `code` and `tt` are ignored. +IgnoredScopes = code, tt + +# By default, `script`, `style`, `pre`, and `figure` are ignored. +SkippedScopes = script, style, pre, figure + +# WordTemplate specifies what Vale considers to be an individual word. +WordTemplate = \b(?:%s)\b + +# List of packages to use for our guidelines +Packages = Google + +# Define the Ansys vocabulary +Vocab = ANSYS + +[*.{md,rst}] + +# Apply the following styles +BasedOnStyles = Vale, Google diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..1d2170d --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,30 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. You can also +# set the first two from the environment. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +clean: + rm -rf $(BUILDDIR) + rm -rf $(SOURCEDIR)/**/*-rendered-example.yml + +# Customized pdf fov svg format images +pdf: + @$(SPHINXBUILD) -M latex "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + cd $(BUILDDIR)/latex && latexmk -r latexmkrc -pdf *.tex -interaction=nonstopmode || true + (test -f $(BUILDDIR)/latex/*.pdf && echo pdf exists) || exit 1 diff --git a/doc/make.bat b/doc/make.bat new file mode 100644 index 0000000..6039c18 --- /dev/null +++ b/doc/make.bat @@ -0,0 +1,50 @@ +@echo OFF +setlocal + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=_build + +if "%1" == "" goto help +if "%1" == "clean" goto clean +if "%1" == "pdf" goto pdf + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:clean +rmdir /s /q %BUILDDIR% > /NUL 2>&1 +for /d /r %SOURCEDIR% %%d in (_autosummary) do @if exist "%%d" rmdir /s /q "%%d" +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:pdf + %SPHINXBUILD% -M latex %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + cd "%BUILDDIR%\latex" + for %%f in (*.tex) do ( + pdflatex "%%f" --interaction=nonstopmode) + +:end +popd + diff --git a/doc/source/_static/.gitkeep b/doc/source/_static/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 0000000..f49fcb1 --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,385 @@ +"""Sphinx documentation configuration file.""" + +import os +import pathlib +from datetime import datetime + +import jinja2 +import yaml +from ansys_sphinx_theme import ansys_favicon, get_version_match, pyansys_logo_black +from tabulate import tabulate as Table + +# Constants used for generating documentation +DOC_SOURCE_DIR = pathlib.Path(__file__).parent.parent +DOC_DIR = DOC_SOURCE_DIR.parent +BASE_DIR = DOC_SOURCE_DIR.parent +ACTIONS_PREFIXES = ("get-", "scade-", "create-", "tests-") +ACTIONS_SUFFIXES = "" +ACTIONS_INPUTS_FIELDS = ("description", "required", "type", "default") +ACTIONS_OUTPUTS_FIELDS = ("description",) +ACCEPTED_LICENSES = BASE_DIR / "check-licenses" / "accepted-licenses.txt" +IGNORED_PACKAGES = BASE_DIR / "check-licenses" / "ignored-packages.txt" +IGNORED_SAFETY = BASE_DIR / "check-vulnerabilities" / "ignored-safety.txt" + +# Project information +project = "Ansys SCADE Actions" +copyright = f"(c) 2023-{datetime.today().year} ANSYS, Inc. and/or its affiliates." +author = "ANSYS, Inc." +cname = os.getenv("DOCUMENTATION_CNAME", "nocname.com") + +# Read version from VERSION file in base root directory +source_dir = pathlib.Path(__file__).parent.resolve().absolute() +version_file = source_dir / "../../VERSION" +with open(str(version_file), "r") as file: + __version__ = file.read().splitlines()[0] +release = version = __version__ +branch_name = ( + "main" + if __version__.endswith("dev0") + else f"release/{get_version_match(__version__)}" +) +actions_version = ( + "main" if __version__.endswith("dev0") else f"v{get_version_match(__version__)}" +) + +# Use the default pyansys logo +html_logo = pyansys_logo_black +html_theme = "ansys_sphinx_theme" +html_favicon = ansys_favicon +html_short_title = html_title = project # necessary for proper breadcrumb title +html_context = { + "github_user": "ansys", + "github_repo": "scade-actions", + "github_version": "main", + "doc_path": "doc/source", +} + + +# Specify the location of your GitHub repo +html_theme_options = { + "github_url": "https://github.com/ansys/scade-actions", + "use_edit_page_button": True, + "additional_breadcrumbs": [ + ("PyAnsys", "https://docs.pyansys.com/"), + ("PyAnsys Developer’s Guide", "https://dev.docs.pyansys.com/"), + ], + "switcher": { + "json_url": f"https://{cname}/versions.json", + "version_match": get_version_match(__version__), + }, + "use_meilisearch": { + "api_key": os.getenv("MEILISEARCH_PUBLIC_API_KEY", ""), + "index_uids": { + f"actions-v{get_version_match(__version__).replace('.', '-')}": "Ansys-scade-actions", + }, + }, +} + +# Specify Sphinx extensions to use +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.autosectionlabel", + "sphinx_copybutton", + "sphinx_jinja", + "sphinx_design", +] + +# Specify the static path +html_static_path = ["_static"] + +# Add any paths that contain templates, relative to this directory +templates_path = ["_templates"] + +# Specify the suffixes of source filenames +source_suffix = ".rst" + +# Specify the master toctree document +master_doc = "index" + +# Generate section labels for up to four levels +autosectionlabel_maxdepth = 2 + + +# Auxiliary routines for automatic documentation generation + + +def is_valid_action_dir(path): + """Verify if a directory is a valid action directory. + + The directory is valid if it has a valid action pattern name and contains + an ``action.yml`` file. + + Parameters + ---------- + path : ~pathlib.Path + The ``Path`` instance to verify if contains an ``action.yml`` and has a valid pattern. + + Returns + ------- + bool + Returns ``True`` if the directory is a valid one, ``False`` otherwise. + + """ + # Verify that the path is a directory and not a file + if not path.is_dir(): + return False + + # Verify that the path contains an action.yml file + if not (path / "action.yml").exists(): + return False + + # Verify if is a public and registered action + if path.name.startswith(ACTIONS_PREFIXES) or path.name.endswith(ACTIONS_SUFFIXES): + return True + + return False + + +def generate_description_from_action_file(action_file): + """Generate the description of an action from the action file. + + Parameters + ---------- + action_file : ~pathlib.Path + A ``Path`` object representing the action file. + + Returns + ------- + str + String representing description of the action. + + """ + with open(action_file, "r") as yaml_file: + file_content = yaml.safe_load(yaml_file) + description = file_content["description"] + source_code_link = f"{html_theme_options['github_url']}/blob/{branch_name}/{action_file.parent.name}/action.yml" + return ( + description + + f"\n`Source code for this action <{source_code_link}>`__ :fab:`github`" + ) + + +def _generate_io_table_from_action_file(action_file, kind, fields): + """Generate the RST table containing all the input information for the action. + + Parameters + ---------- + action_file : ~pathlib.Path + A ``Path`` object representing the action file. + kind : str + Nature of the I/O, either "input" or "output". + fields : List[str] + Name of the fields associated to the I/O. + + Returns + ------- + str + String representing the RST table. + + """ + field_names = (kind,) + fields + headers = [field.capitalize() for field in field_names] + table_content = [] + + with open(action_file, "r") as yaml_file: + file_content: dict = yaml.safe_load(yaml_file) + ios = file_content.get(kind + "s", None) + if ios: + for io_name, values in ios.items(): + values = [ + values.get(field, None) for field in field_names if field != kind + ] + table_row = [io_name] + table_row.extend(values) + table_content.append(table_row) + return str(Table(table_content, headers=headers, tablefmt="grid")) + else: + return "" + + +def generate_inputs_table_from_action_file(action_file): + """Generate the RST table containing all the input information for the action. + + Parameters + ---------- + action_file : ~pathlib.Path + A ``Path`` object representing the action file. + + Returns + ------- + str + String representing the RST table. + + """ + return _generate_io_table_from_action_file( + action_file, "input", ACTIONS_INPUTS_FIELDS + ) + + +def generate_outputs_table_from_action_file(action_file): + """Generate the RST table containing all the output information for the action. + + Parameters + ---------- + action_file : ~pathlib.Path + A ``Path`` object representing the action file. + + Returns + ------- + str + String representing the RST table. + + """ + return _generate_io_table_from_action_file( + action_file, "output", ACTIONS_OUTPUTS_FIELDS + ) + + +# Collect all public actions directories and files +public_actions = { + action_dir: action_dir / "action.yml" + for action_dir in BASE_DIR.iterdir() + if is_valid_action_dir(action_dir) +} + +# Generate the Jinja contexts for the input tables +jinja_contexts = { + action_dir.name: { + "description": generate_description_from_action_file(action_file), + "inputs_table": generate_inputs_table_from_action_file(action_file), + "outputs_table": generate_outputs_table_from_action_file(action_file), + } + for action_dir, action_file in public_actions.items() +} + + +def render_example_template_with_actions_version( + example_template_file, actions_version +): + """Renders a example template with desired branch name. + + Parameters + ---------- + example_template_file : ~pathlib.Path + The ``Path`` for the example template file. + actions_version : str + A string representing the actions version. + + Returns + ------- + example_rendered_file : ~pathlib.Path + The ``Path`` for the rendered example file. + + """ + env = jinja2.Environment( + loader=jinja2.FileSystemLoader(example_template_file.parent) + ) + example_template = env.get_template(example_template_file.name) + content = example_template.render(version=actions_version) + output_file_name = example_template_file.name[:-4] + "-rendered-example.yml" + example_rendered_file = example_template_file.parent / output_file_name + with open(example_rendered_file, "w") as file: + file.write(content) + return example_rendered_file + + +def collect_examples_from_action_name(action_name): + """Returns a list of example files in the form of ``Path`` instances. + + Parameters + ---------- + action_name : str + The name of the action. + + Returns + ------- + list[~pathlib.Path] + A list of example files in the form of ``Path`` instances. + + """ + return [ + render_example_template_with_actions_version(path, actions_version) + for path in DOC_SOURCE_DIR.glob("**/*") + if path.is_file() + and path.name.startswith(action_name) + and not path.name.endswith("-rendered-example.yml") + ] + + +def get_example_file_title(example_file): + """Returns the title from a YML example file. + + Parameters + ---------- + example_file : ~pathlib.Path + The ``Path`` for the example file. + + Returns + ------- + str + A ``string`` representing the title of the example. + + Notes + ----- + The string in the 'title' key of the example YML file is used. This key is + contained within the first section of the action file, whose name is + unknown. For this reason, the first key of the file is guessed and used + then to retrieve the value of the 'title' key. + + """ + with open(example_file, "r") as yaml_file: + file_content = yaml.safe_load(yaml_file) + first_key = next(iter(file_content)) + return file_content[first_key]["name"] + + +# Add examples files and titles to the Jinja context for the action +for action_dir in public_actions: + action_name = action_dir.name + examples = collect_examples_from_action_name(action_name) + if not len(examples): + continue + + # Append examples to context + jinja_contexts[action_name]["examples"] = [ + [file.name, get_example_file_title(file)] for file in examples + ] + + +# Dynamically load the file contents for accepted licenses and ignored packages +def load_file_lines_as_list(file_path): + """Loads the lines of a file in the form of a Python list. + + Parameters + ---------- + file_path : ~pathlib.Path + The ``Path`` instance representing the file location. + + Returns + ------- + list[str] + A list of strings representing the lines of the file. + + Notes + ----- + This function is expected to be used for loading the contents of TXT files. + + """ + with open(file_path) as accepted_licenses_file: + return list(accepted_licenses_file.read().split("\n")) + + +if False: + # TODO: should that be replicated this in this context? + # Check licenses + for var, file in zip( + ["accepted_licenses", "ignored_packages"], [ACCEPTED_LICENSES, IGNORED_PACKAGES] + ): + jinja_contexts["check-licenses"][var] = load_file_lines_as_list(file) + + # Check vulnerabilities + jinja_contexts["check-vulnerabilities"]["ignored_safety"] = load_file_lines_as_list( + IGNORED_SAFETY + ) + print(jinja_contexts["check-vulnerabilities"]["ignored_safety"]) diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000..286485d --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,30 @@ +.. include:: ../../README.rst + :start-after: .. readme_common_begins + :end-before: .. readme_common_ends + +For more information on available actions and how to use them, +see each card below: + +.. grid:: 1 1 2 2 + :gutter: 2 + + .. grid-item-card:: :octicon:`search` Query actions + :link: query-actions/index + :link-type: doc + + Query actions allow to retrieve SCADE directories and + Python environments. + + .. grid-item-card:: :octicon:`tools` Tests actions + :link: tests-actions/index + :link-type: doc + + Tests actions allow to setup Python environments for SCADE and + run the test suite. + +.. toctree:: + :hidden: + :maxdepth: 3 + + query-actions/index + tests-actions/index diff --git a/doc/source/query-actions/examples/get-scade-dir.yml b/doc/source/query-actions/examples/get-scade-dir.yml new file mode 100644 index 0000000..1be7594 --- /dev/null +++ b/doc/source/query-actions/examples/get-scade-dir.yml @@ -0,0 +1,8 @@ +get-scade-dir: + name: "Get SCADE installation directory basic example" + runs-on: [self-hosted, 'SCADE'] + steps: + - name: "Get SCADE directory" + uses: ansys-scade/actions/get-scade-dir@{{ version }} + with: + scade-version: "23.2" diff --git a/doc/source/query-actions/examples/get-scade-python.yml b/doc/source/query-actions/examples/get-scade-python.yml new file mode 100644 index 0000000..103ef14 --- /dev/null +++ b/doc/source/query-actions/examples/get-scade-python.yml @@ -0,0 +1,8 @@ +get-scade-python: + name: "Get SCADE Python version basic example" + runs-on: [self-hosted, 'SCADE'] + steps: + - name: "Get SCADE Python" + uses: ansys-scade/actions/get-scade-python@{{ version }} + with: + scade-dir: 'C:\Program Files\Ansys Inc\v232\SCADE' diff --git a/doc/source/query-actions/index.rst b/doc/source/query-actions/index.rst new file mode 100644 index 0000000..43d2de2 --- /dev/null +++ b/doc/source/query-actions/index.rst @@ -0,0 +1,53 @@ +Query actions +=================== + +The query actions allow for querying Ansys SCADE installations +and Python environments. + + +Get SCADE directory action +-------------------------- + +.. jinja:: get-scade-dir + + {{ description }} + + {{ inputs_table }} + + {{ outputs_table }} + + Examples + ++++++++ + + {% for filename, title in examples %} + .. dropdown:: {{ title }} + :animate: fade-in + + .. literalinclude:: examples/{{ filename }} + :language: yaml + + {% endfor %} + + +Get SCADE Python version +------------------------ + +.. jinja:: get-scade-python + + {{ description }} + + {{ inputs_table }} + + {{ outputs_table }} + + Examples + ++++++++ + + {% for filename, title in examples %} + .. dropdown:: {{ title }} + :animate: fade-in + + .. literalinclude:: examples/{{ filename }} + :language: yaml + + {% endfor %} diff --git a/doc/source/tests-actions/examples/create-scade-venv.yml b/doc/source/tests-actions/examples/create-scade-venv.yml new file mode 100644 index 0000000..7c63644 --- /dev/null +++ b/doc/source/tests-actions/examples/create-scade-venv.yml @@ -0,0 +1,10 @@ +create-scade-venv: + name: "Create Python virtual environment basic example" + runs-on: [self-hosted, 'SCADE'] + steps: + - name: "Create Python virtual environment" + uses: ansys-scade/actions/create-scade-venv@{{ version }} + with: + python-dir: 'C:\Program Files\Ansys Inc\v232\SCADE\contrib\Python310' + target-dir: '.venvs' + target-name: 'Python310' diff --git a/doc/source/tests-actions/examples/scade-tests-pytest-basic.yml b/doc/source/tests-actions/examples/scade-tests-pytest-basic.yml new file mode 100644 index 0000000..be6bb9f --- /dev/null +++ b/doc/source/tests-actions/examples/scade-tests-pytest-basic.yml @@ -0,0 +1,10 @@ +tests: + name: "Run tests basic example" + runs-on: [self-hosted, 'SCADE'] + steps: + - name: "Run the tests" + uses: ansys-scade/actions/scade-tests-pytest@main + with: + python-dir: '.venvs\Python310\Scripts' + pytest-extra-args: "--cov=ansys --cov-report=term --cov-branch --cov-report=html:.cov/html" + checkout: false diff --git a/doc/source/tests-actions/index.rst b/doc/source/tests-actions/index.rst new file mode 100644 index 0000000..bf5c595 --- /dev/null +++ b/doc/source/tests-actions/index.rst @@ -0,0 +1,58 @@ +Tests actions +============= + +The tests actions allow to setup Python environments for SCADE and +run the test suite for a SCADE Python library. + + +Create SCADE Python virtual environment action +---------------------------------------------- + +.. jinja:: create-scade-venv + + {{ description }} + + {{ inputs_table }} + + {{ outputs_table }} + + Examples + ++++++++ + + {% for filename, title in examples %} + .. dropdown:: {{ title }} + :animate: fade-in + + .. literalinclude:: examples/{{ filename }} + :language: yaml + + {% endfor %} + + +Test library action +-------------------- +This action runs the test suite for a Python library. This action accepts +markers, options, and post arguments to be passed to pytest before executing +the test session. + +.. jinja:: scade-tests-pytest + + {{ description }} + + {{ inputs_table }} + + {{ outputs_table }} + +Examples +++++++++ + +.. jinja:: scade-tests-pytest + + {% for filename, title in examples %} + .. dropdown:: {{ title }} + :animate: fade-in + + .. literalinclude:: examples/{{ filename }} + :language: yaml + + {% endfor %} diff --git a/doc/styles/.gitignore b/doc/styles/.gitignore new file mode 100644 index 0000000..72177bc --- /dev/null +++ b/doc/styles/.gitignore @@ -0,0 +1,4 @@ +* +!Vocab +!Vocab/** +!.gitignore diff --git a/doc/styles/Vocab/ANSYS/accept.txt b/doc/styles/Vocab/ANSYS/accept.txt new file mode 100644 index 0000000..d70bb4b --- /dev/null +++ b/doc/styles/Vocab/ANSYS/accept.txt @@ -0,0 +1,8 @@ +Ansys +ansys +CI +dev +GitHub +pytest +PyPI +TXT diff --git a/doc/styles/Vocab/ANSYS/reject.txt b/doc/styles/Vocab/ANSYS/reject.txt new file mode 100644 index 0000000..e69de29 diff --git a/get-scade-dir/action.yml b/get-scade-dir/action.yml index 5ad681a..ea44f62 100644 --- a/get-scade-dir/action.yml +++ b/get-scade-dir/action.yml @@ -1,13 +1,15 @@ # get-scade-dir.yml name: 'Retrieve the installation directory of an Ansys SCADE version' -description: 'A GitHub action that takes as input an Ansys SCADE version and returns its installation directory' +description: > + A GitHub action that takes as input an Ansys SCADE version and + returns its installation directory. inputs: scade-version: description: 'SCADE version: 19.2, 20.1, ..., 23.1, ...' required: true outputs: scade-directory: - description: 'Intallation directory of the requested version' + description: 'Installation directory of the requested version' value: ${{ steps.find-scade-dir.outputs.scade-dir }} author: 'ESEG' diff --git a/get-scade-python/action.yml b/get-scade-python/action.yml index 0dc5645..4e74bef 100644 --- a/get-scade-python/action.yml +++ b/get-scade-python/action.yml @@ -1,9 +1,16 @@ # get-scade-python name: 'Retrieve the Python installation installed with Ansys SCADE' -description: 'A GitHub action that takes as input an Ansys SCADE installation directory and returns the name and path to the corresponding Python installation' + +description: > + A GitHub action that takes as input an Ansys SCADE installation directory + and returns the name and path to the corresponding Python installation. + inputs: scade-dir: - description: 'C:\Program Files\ANSYS Inc\v231\SCADE' + description: > + Ansys SCADE Installation directory, e.g.:: + + C:\Program Files\Ansys Inc\v231\SCADE required: true outputs: diff --git a/requirements/requirements_doc.txt b/requirements/requirements_doc.txt new file mode 100644 index 0000000..0a3d756 --- /dev/null +++ b/requirements/requirements_doc.txt @@ -0,0 +1,7 @@ +ansys-sphinx-theme==0.13.4 +pyyaml==6.0.1 +Sphinx==7.1.1 +sphinx-copybutton==0.5.2 +sphinx-jinja==2.0.2 +sphinx_design==0.5.0 +tabulate==0.9.0