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

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

.gitignore

@@ -127,3 +127,5 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
+doc/_build/
+*-rendered-example.yml

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'

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

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

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
+