Improve doc

.github/workflows/ci_cd.yml

@@ -45,21 +45,72 @@ jobs:
 
   doc-build:
     name: "Build documentation"
-    runs-on: ubuntu-latest
-    needs: doc-style
+    runs-on: [self-hosted, pyaedt, toolkits, Windows]
+    timeout-minutes: 10
     steps:
-      - uses: ansys/actions/doc-build@v5
+      - uses: actions/checkout@v4
+
+      - name: "Set up Python"
+        uses: ansys/actions/_setup-python@main
         with:
           python-version: ${{ env.MAIN_PYTHON_VERSION }}
-          check-links: false
+          use-cache: false
+
+      - name: 'Create virtual env'
+        run: |
+          python -m venv .venv
+
+      - name: "Update pip"
+        run: |
+          . .venv\Scripts\Activate.ps1
+          python -m pip install pip -U
+          python -m pip install wheel setuptools -U
+          python -c "import sys; print(sys.executable)"
+
+      - name: Install common toolkit with doc dependencies
+        run: |
+          . .venv\Scripts\Activate.ps1
+          pip install .
+          pip install .[doc]
+
+      - name: Retrieve common toolkit version
+        run: |
+          . .venv\Scripts\Activate.ps1
+          echo "Common Toolkit version is: $(python -c "from ansys.aedt.toolkits.common import __version__; print(); print(__version__)")"
+
+      - name: Build the documentation (HTML)
+        run: |
+          .\.venv\Scripts\Activate.ps1
+          cd doc
+          .\make.bat html
+
+#      - name: Build the documentation (PDF)
+#        run: |
+#          .\.venv\Scripts\Activate.ps1
+#          cd doc
+#          .\make.bat pdf
+
+      - name: Upload HTML Documentation artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: documentation-html
+          path: doc/_build/html
+          retention-days: 1
+
+#      - name: Upload PDF Documentation artifact
+#        uses: actions/upload-artifact@v4
+#        with:
+#          name: documentation-pdf
+#          path: doc/_build/latex/*.pdf
+#          retention-days: 7
 
   smoke-tests:
     name: "Build and Smoke tests"
     strategy:
       fail-fast: false
       matrix:
         os: [ windows-latest, ubuntu-latest ]
-        python-version: [ '3.8', '3.10' ]
+        python-version: [ '3.10' ]
     runs-on: ${{ matrix.os }}
     needs: [ code-style ]
     steps:
@@ -73,7 +124,7 @@ jobs:
     name: "Windows Tests AEDT"
     strategy:
       matrix:
-        python-version: [ '3.8', '3.10' ]
+        python-version: [ '3.10' ]
       fail-fast: false
     runs-on: [self-hosted, pyaedt, toolkits, Windows]
     needs: [smoke-tests]

.pre-commit-config.yaml

@@ -3,6 +3,7 @@ exclude: |
         src/ansys/aedt/toolkits/common/ui/utils/ui_templates/.* |
         tests/.* |
         examples/.* |
+        doc/getting_started/installation.rst |
         README.rst
     )
 

README.rst

@@ -23,11 +23,14 @@ PyAEDT Common Toolkit
   :target: https://github.com/psf/black
   :alt: black
 
+The ``pyaedt-toolkits-common`` package provides common methods to create a new Ansys Electronics Desktop (AEDT) toolkit.
+
+A common toolkit library can bring numerous advantages, enhancing efficiency, consistency, and collaboration
+in the creation and development of AEDT toolkits.
 
-The ``pyaedt-toolkits-common`` package provides common methods to create a new toolkit using PyAEDT.
 This package has two main parts: backend and user interface.
 
-The backend has some common methods to control Ansys Electronics Desktop (AEDT) session, and in addition,
+The backend has some common methods to control AEDT session, and in addition,
 it has a REST API based on `Flask <https://flask.palletsprojects.com/en/2.3.x/>`_.
 
 The user interface has some common methods to create a desktop application based on `Pyside6 <https://doc.qt.io/qtforpython-6/quickstart.html>`_.

doc/Makefile

@@ -33,4 +33,12 @@ html:
 pdf:
 	@$(SPHINXBUILD) -M latex "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 	cd $(BUILDDIR)/latex && latexmk -r latexmkrc -pdf *.tex -interaction=nonstopmode || true
-	(test -f $(BUILDDIR)/latex/ansys-aedt-toolkits-common.pdf && echo pdf exists) || exit 1
+	(test -f $(BUILDDIR)/latex/ansys-common-toolkit.pdf && echo pdf exists) || exit 1
+
+# build docs like the CI build
+cibuild:
+	mkdir source/examples -p
+	echo 'Examples' > source/examples/index.rst
+	echo '========' >> source/examples/index.rst
+	$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -j auto -w build_errors.txt -N
+	python print_errors.py

doc/make.bat

@@ -7,11 +7,15 @@ REM Command file for Sphinx documentation
 if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
+if "%SPHINXOPTS%" == "" (
+	set SPHINXOPTS = -j auto -N -q
+)
 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 (
@@ -22,20 +26,31 @@ if errorlevel 9009 (
 	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/
+	echo.https://sphinx-doc.org/
 	exit /b 1
 )
 
 %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 goto end
 
 :clean
-rmdir /s /q %BUILDDIR% > /NUL 2>&1 
+rmdir /s /q %BUILDDIR% > /NUL 2>&1
 for /d /r %SOURCEDIR% %%d in (_autosummary) do @if exist "%%d" rmdir /s /q "%%d"
 goto end
 
+:pdf
+%SPHINXBUILD% -M latex %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+cd "%BUILDDIR%\latex"
+for %%f in (*.tex) do (
+xelatex "%%f" --interaction=nonstopmode)
+if NOT EXIST ansys-common-toolkit.pdf (
+	Echo "no pdf generated!"
+	exit /b 1)
+Echo "pdf generated!"
+goto end
+
 :help
 %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 
 :end
-popd
+popd

doc/source/Getting_Started/Architecture.rst

@@ -1,8 +1,26 @@
-.. _ref_toolkit_architecture:
+.. _architecture:
 
 Architecture
 ============
 
+This repository is a common API for any new AEDT toolkit. It standardizes AEDT toolkits implementation.
+
+The API provides some methods to connect to an existing AEDT session, open an existing
+AEDT project or initialize a new AEDT session, which should be the basic capability of any toolkit.
+
+The architecture is divided in two main parts:
+
+1. The backend, using `Flask <https://flask.palletsprojects.com/en/2.3.x/>`_. Flask creates a REST API,
+which let interact different services by simply doing HTTP requests.
+
+2. The user interface, using `Pyside6 <https://doc.qt.io/qtforpython-6/quickstart.html>`_. Pyside6 has a designer tool
+which allows to create user interfaces and it is translated to python directly.
+
+Using Flask, the toolkit becomes interface agnostic, then you can decide change it and use a WebUI for instance
+as user interface.
+
+You can install the library like any other open source package. You can add this project as a dependency of the new toolkit.
+
 The architecture is defined in the following picture:
 
 .. image:: ../_static/toolkit_architecture.png

doc/source/Getting_Started/index.rst

@@ -1,35 +1,39 @@
-.. _ref_getting_started:
+.. _getting_started:
 
 ===============
 Getting started
 ===============
 
-If you want to develop a new toolkit, you need first to understand the architecture.
+If you want to develop a new toolkit, you need first to learn how the :ref:`architecture` works.
 
-This repository is a common API for any new AEDT toolkit. It standardizes AEDT toolkits implementation.
+.. grid:: 2
 
-The API provides some methods to connect to an existing AEDT session, open an existing
-AEDT project or initialize a new AEDT session, which should be the basic capability of any toolkit.
+    .. grid-item-card:: Architecture :fa:`person-running`
+        :padding: 2 2 2 2
+        :link: architecture
+        :link-type: doc
 
-The architecture is split in two main parts:
+        Learn more about the toolkit architecture.
 
-1. The backend, using `Flask <https://flask.palletsprojects.com/en/2.3.x/>`_. Flask creates a REST API,
-which let interact different services by simply doing HTTP requests.
+    .. grid-item-card:: Installation :fa:`book-bookmark`
+        :padding: 2 2 2 2
+        :link: installation
+        :link-type: doc
 
-2. The frontend, using `Pyside6 <https://doc.qt.io/qtforpython-6/quickstart.html>`_. Pyside6 has a designer tool
-which allows to create user interfaces and it is translated to python directly.
+        Learn how to install the library.
 
-Using Flask, the toolkit becomes interface agnostic, then you can decide change it and use a WebUI for instance
-as user interface.
+    .. grid-item-card:: Example toolkit :fa:`scroll`
+        :padding: 2 2 2 2
+        :link: example_toolkit
+        :link-type: doc
 
-You can install the library like any other open source package. You can add this project as a dependency of the new toolkit.
-
-If you need more information, go to :ref:`ref_toolkit_architecture`.
+        Example toolkit using the common methods.
 
 
 .. toctree::
    :hidden:
    :maxdepth: 2
 
-   Architecture
-   Installation
+   architecture
+   installation
+   example_toolkit

doc/source/Getting_Started/installation.rst

@@ -0,0 +1,15 @@
+.. _installation:
+
+Installation
+============
+
+If you want to use this library for a toolkit or automated workflow, you can install the backend standalone or
+install backend and user interface common methods.
+
+You can install both backend and user interface methods from PyPI::
+
+    pip -m install git+https://github.com/ansys-internal/pyaedt-toolkits-common.git[all]
+
+You can install only the backend methods from PyPI, this is useful if you only need the common API::
+
+    pip -m install git+https://github.com/ansys-internal/pyaedt-toolkits-common.git

doc/source/conf.py

@@ -161,11 +161,24 @@
 
 # Sphinx gallery customization
 
+nbsphinx_thumbnails = {
+    "examples/aedt_common/api_aedt_simple": "_static/thumbnails/coaxial.png",
+    "examples/properties_common/api_properties": "_static/thumbnails/book.png",
+}
+
 nbsphinx_custom_formats = {
     ".py": ["jupytext.reads", {"fmt": ""}],
 }
 
-exclude_patterns = ["_build", "sphinx_boogergreen_theme_1", "Thumbs.db", ".DS_Store", "*.txt", "conf.py"]
+exclude_patterns = [
+    "_build",
+    "sphinx_boogergreen_theme_1",
+    "Thumbs.db",
+    ".DS_Store",
+    "*.txt",
+    "conf.py",
+    "examples/properties_common/models.py",
+]
 
 # if os.name != "posix":
 #     extensions.append("sphinx_gallery.gen_gallery")

doc/source/Contributing.rst → doc/source/contributing.rst

@@ -6,11 +6,11 @@ Overall guidance on contributing to a PyAnsys repository appears in
 in the *PyAnsys Developer's Guide*. Ensure that you are thoroughly familiar
 with this guide before attempting to contribute to PyAEDT or its toolkits.
 
-The following contribution information is specific to PyAEDT toolkits.
+The following contribution information is specific to this library.
 
 Clone the repository
 --------------------
-To clone and install the latest version of the Motor Segmentation Toolkit in
+To clone and install the latest version of the PyAEDT Common Toolkit in
 development mode, run these commands:
 
 .. code::
@@ -22,7 +22,7 @@ development mode, run these commands:
 
 Post issues
 -----------
-Use the `PyAEDT Common Toolkit Issues <https://github.com/ansys/pyaedt-toolkits-common/issues>`_ page
+Use the `PyAEDT Common Toolkit Issues <https://github.com/ansys-internal/pyaedt-toolkits-common/issues>`_ page
 to create issues to report bugs and request new features.
 
 View documentation