maint: documentation review

.github/workflows/cicd.yml

@@ -89,6 +89,7 @@ jobs:
         uses: ansys/actions/doc-build@v5
         with:
           python-version: ${{ env.MAIN_PYTHON_VERSION }}
+          dependencies: "texlive-fonts-extra "
 
   package:
     name: Package library

README.rst

@@ -4,80 +4,45 @@ Ansys Engineering Workflow API
 Overview
 --------
 The Ansys Engineering Workflow API is a Python package that provides a
-common interface for interacting with Ansys engineering workflow engines,
-such as ModelCenter and OptiSLang.
+common interface for interacting with Ansys engineering workflow engines.
 
+It is not a standalone package. It is intended to be used in conjunction with
+other PyAnsys libraries.
 
-Installation
-------------
-The ``ansys-engineeringworkflow-api`` package currently supports Python
-3.9 through 3.12 on Windows, MacOS and Linux.
+Documentation and issues
+------------------------
 
-You can install ``ansys-engineeringworkflow-api`` with:
+Documentation for the latest stable release of the Ansys Engineering Workflow API is hosted
+at `Ansys Engineering Workflow API documentation <https://engineeringworkflow.docs.pyansys.com/version/dev/>`_.
 
-.. code::
+The documentation has four sections:
 
-   pip install ansys-engineeringworkflow-api
+- `Getting started <https://engineeringworkflow.docs.pyansys.com/version/dev/getting_started/index.html>`_: Learn
+  how to install the Ansys Engineering Workflow API.
+- `User guide <https://engineeringworkflow.docs.pyansys.com/version/dev/user_guide/index.html>`_: Understand how to
+  use the Ansys Engineering Workflow API.
+- `API reference <https://rocky.docs.pyansys.com/version/dev/api/index.html>`_: Understand Ansys Engineering Workflow
+  API endpoints, their capabilities, and how to interact with them programmatically.
+- `Contribute <https://engineeringworkflow.docs.pyansys.com/version/dev/contributing/index.html>`_: Learn how to
+  contribute to the Ansys Engineering Workflow API codebase or documentation.
 
-Alternatively, install the latest version from `ansys-engineeringworkflow-api GitHub
-<https://github.com/ansys/ansys-engineeringworkflow-api>`_ via:
+In the upper right corner of the documentation's title bar, there is an option
+for switching from viewing the documentation for the latest stable release
+to viewing the documentation for the development version or previously
+released versions.
 
-.. code::
+On the `Ansys Engineering Workflow API Issues <https://github.com/ansys/ansys-engineeringworkflow-api/issues>`_
+page, you can create issues to report bugs and request new features. On the
+`Ansys Engineering Workflow API Discussions <https://github.com/ansys/ansys-engineeringworkflow-api/discussions>`_
+page or the `Discussions <https://discuss.ansys.com/>`_ page on the Ansys Developer portal,
+you can post questions, share ideas, and get community feedback.
 
-   pip install git+https://github.com/ansys/ansys-engineeringworkflow-api
+To reach the PyAnsys project support team, email `PyAnsys Core team <pyansys.core@ansys.com>`_.
 
+License
+-------
 
-For a local development version, you can install the development
-version of the project with:
+The Ansys Engineering Workflow API is licensed under the `MIT License <https://github.com/ansys/ansys-engineeringworkflow-api/blob/main/LICENSE>`_.
 
-.. code::
-
-   git clone https://github.com/ansys/ansys-engineeringworkflow-api.git
-   cd ansys-engineeringworkflow-api
-   pip install -e .
-
-
-Documentation building
-----------------------
-
-Install the required dependencies for building the documentation with this
-command:
-
-.. code:: bash
-
-    pip install .[doc]
-
-Build and view documentation with the one or more commands for your
-operating system:
-
-.. code:: bash
-
-    # For Linux and MacOS
-    make -C doc/ html && your_browser_name doc/build/html/index.html
-
-    # For Windows
-    .\doc\make.bat html
-    .\doc\build\html\index.html
-
-
-
-TODO
-----
-
-- [ ] Finish documentation such that pre-commit works as intended
-- [ ] Copy (manually, automatically?) main package documentation to README
-- [ ] To/FromAPI String
-	- No extension methods in Python, add to base interface explicitly?
-	- Our string quoting rules per standard doc (Phoenix.ModelCenter.Common.ModelCenterUtils.EscapeString and UnescapeString)
-- [ ] To/From Formatted String
-- [ ] Scalar Types
-- [ ] Array Types
-	- Strong typing of ndarray in numpy only added in version of numpy that doesn't support Python 3.7
-- [ ] File Types
-	- Use interface to separate behavior of files from library
-	- Implement default behavior
-- [ ] Clone
-- [ ] LinkingRules
-- [ ] Variable Factory
-- [ ] Variable State
-- [ ] Variable Scope
+The Ansys Engineering Workflow API makes no commercial claim over Ansys whatsoever.
+This library is not intended for standalone use.

doc/source/conf.py

@@ -6,9 +6,13 @@
 
 from ansys_sphinx_theme import (
     ansys_favicon,
+    ansys_logo_white,
+    ansys_logo_white_cropped,
     get_autoapi_templates_dir_relative_path,
     get_version_match,
+    latex,
     pyansys_logo_black,
+    watermark,
 )
 
 from ansys.engineeringworkflow.api import __version__
@@ -160,6 +164,7 @@
 with open("links.rst") as f:
     rst_epilog += f.read()
 
+
 # -- Options for LaTeX output ------------------------------------------------
 latex_elements = {}
 
@@ -175,3 +180,11 @@
         "manual",
     ),
 ]
+
+# additional logos for the latex coverpage
+latex_additional_files = [watermark, ansys_logo_white, ansys_logo_white_cropped]
+
+# change the preamble of latex with customized title page
+# variables are the title of pdf, watermark
+latex_elements = {"preamble": latex.generate_preamble(html_title)}
+sd_fontawesome_latex = True

doc/source/contributing/index.rst

@@ -5,37 +5,25 @@ Contribute
 
 Overall guidance on contributing to a PyAnsys library appears in the
 `Contributing <dev_guide_contributing_>`_ topic
-in the *PyAnsys Developer's Guide*. Ensure that you are thoroughly familiar
-with this guide before attempting to contribute to Ansys Engineering Workflow API.
+in the *PyAnsys developer's guide*. Ensure that you are thoroughly familiar
+with this guide before attempting to contribute to the Ansys Engineering Workflow API.
 
-The following contribution information is specific to Ansys Engineering Workflow API.
+The following contribution information is specific to the Ansys Engineering Workflow API.
 
-Installation
-------------
+Install in developer mode
+-------------------------
 
-The ``ansys-engineeringworkflow-api`` package currently supports Python
-3.9 through 3.12 on Windows, MacOS, and Linux.
+Installing the ``ansys-engineeringworkflow-api`` package in developer mode allows
+you to modify the source and enhance it. This package supports Python 3.9 through 3.12
+on Windows, MacOS, and Linux.
 
-You can install the ``ansys-engineeringworkflow-api`` package with this command:
-
-.. code::
-
-   pip install ansys-engineeringworkflow-api
-
-Alternatively, install the latest version from `ansys-engineeringworkflow-api GitHub
-<ansys-engineeringworkflow-api_repo_>`_ with this command:
-
-.. code::
-
-   pip install git+https://github.com/ansys/ansys-engineeringworkflow-api
-
-For a local development version, you can create a new virtual environment with this command:
+For a local development version, you can create a clean virtual environment with this command:
 
 .. code:: bash
 
     python -m venv .venv
 
-You can then activate the virtual environment with the command appropriate for your operating system:
+You can then activate this virtual environment with the command appropriate for your operating system:
 
 .. tab-set::
 
@@ -61,7 +49,8 @@ You can then activate the virtual environment with the command appropriate for y
           .\.venv\Scripts\activate
 
 
-Next, install the development version of the project with these commands:
+Next, install the development version of the ``ansys-engineeringworkflow-api`` package
+with these commands:
 
 .. code::
 
@@ -70,8 +59,8 @@ Next, install the development version of the project with these commands:
    pip install -e .
 
 
-Documentation
--------------
+Build documentation
+-------------------
 
 Install the required dependencies for the documentation with this command:
 
@@ -80,7 +69,8 @@ Install the required dependencies for the documentation with this command:
     pip install .[doc]
 
 
-For building documentation, you run the usual rules provided in the Sphinx Makefile for your operating system:
+To build documentation, run the usual rules provided in the Sphinx
+Makefile for your operating system:
 
 .. tab-set::
 
@@ -106,26 +96,27 @@ For building documentation, you run the usual rules provided in the Sphinx Makef
         .\doc\make.bat html
         .\doc\build\html\index.html
 
-
 Post issues
 -----------
 
-Use the `Ansys Engineering Workflow API Issues <ansys-engineeringworkflow-api_issues_>`_ page to submit questions,
-report bugs, and request new features. When possible, use these issue
-templates:
-
-* Bug report template
-* Feature request template
-* Documentation issue template
-* Example request template
+Use the `Ansys Engineering Workflow API Issues <ansys-engineeringworkflow-api_issues_>`_
+page to report bugs and request new features.
 
-If your issue does not fit into one of these categories, create your own issue.
+When possible, use the issue templates provided. If your issue does not fit into one
+of the templates, you can click the link for opening a blank issue.
 
 To reach the PyAnsys support team, email `pyansys.core@ansys.com <pyansys.core@ansys.com>`_.
 
+Verify style and unit tests
+---------------------------
 
-Testing
--------
+If required, from the command line, you can call commands like `black`_, `isort`_, and `flake8`_.
+You can also call unit testing commands like `pytest`_. However, running these commands does not
+guarantee that your project is being tested in an isolated environment, which is why you
+might consider using `tox`_.
+
+Test
+----
 You can install the dependencies required for testing with this command:
 
 .. code:: bash
@@ -142,8 +133,8 @@ You can then run the tests via ``pytest`` with this command:
 Adhere to code style
 --------------------
 
-Ansys Engineering Workflow API follows the PEP8 standard as indicated in the 
-`PyAnsys Developer's Guide <dev_guide_pyansys_pep8_>`_ and implements style checking using
+The Ansys Engineering Workflow API follows the PEP8 standard as indicated in the 
+`PyAnsys developer's guide <dev_guide_pyansys_pep8_>`_ and implements style checking using
 `pre-commit <pre-commit_>`_.
 
 To ensure your code meets minimum code styling standards, run these commands:
@@ -173,3 +164,20 @@ This way, it's not possible for you to push code that fails the style checks:
   docformatter.............................................................Passed
   codespell................................................................Passed
   Validate GitHub Workflows................................................Passed
+
+Distribute
+----------
+
+If you would like to create either source or wheel files, start by running this
+command to install the building requirements:
+
+.. code:: bash
+
+    python -m pip install -e .[doc,tests]
+
+Then, run these commands:
+
+.. code:: bash
+
+    python -m build
+    python -m twine check dist/*

doc/source/getting_started/index.rst

@@ -1,13 +1,21 @@
+.. _getting_started:
+
 Getting started
 ===============
 
-Installation
-------------
+The Ansys Engineering Workflow API supports Python 3.9 through 3.12 on Windows,
+MacOS, and Linux.
 
-Two installation modes of the ``ansys-engineeringworkflow-api`` package are provided: user and developer.
+Two installation modes of the ``ansys-engineeringworkflow-api`` package
+are provided: user and developer. This section describes how to install
+in user mode.
 
-Install in user mode
-^^^^^^^^^^^^^^^^^^^^
+.. note:: 
+    If you are interested in contributing to this package, see :ref:`ref_contribute`
+    for information on installing in developer mode.
+
+Installation
+------------
 
 Before installing the ``ansys-engineeringworkflow-api`` package, make sure that you
 have the latest version of `pip`_ with this command:
@@ -22,35 +30,9 @@ Then, install the latest ``ansys-engineeringworkflow-api`` package with this com
 
     python -m pip install ansys-engineeringworkflow-api
 
-Install in developer mode
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Installing the ``ansys-engineeringworkflow-api`` package in developer mode allows
-you to modify the source and enhance it.
-For more information, see :ref:`ref_contribute`.
-
-Style and testing
------------------
-
-If required, you can call style commands (such as `black`_, `isort`_,
-and `flake8`_) or unit testing commands (such as `pytest`_) from the command line.
-However, this does not guarantee that your project is being tested in an isolated
-environment, which is why you might consider using `tox`_.
+Alternatively, you can install the latest version from the project's `GitHub repository
+<https://github.com/ansys/ansys-engineeringworkflow-api>`_ with this command:
 
+.. code::
 
-Distributing
-------------
-
-If you would like to create either source or wheel files, start by running this
-command to install the building requirements:
-
-.. code:: bash
-
-    python -m pip install -e .[doc,tests]
-
-Then, run these commands:
-
-.. code:: bash
-
-    python -m build
-    python -m twine check dist/*
+   pip install git+https://github.com/ansys/ansys-engineeringworkflow-api