Better Package Style layout

.github/workflows/ci-build.yml

@@ -38,6 +38,12 @@ jobs:
         with:
           python-version: 3.8
 
+      - name: Install diagrams dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install nodejs npm graphviz
+          npm install -g @mermaid-js/mermaid-cli
+
       - name: Build HTML Documentation
         run: |
           pip install -r requirements_docs.txt --disable-pip-version-check

.github/workflows/nightly-build.yml

@@ -18,6 +18,12 @@ jobs:
         with:
           python-version: 3.8
 
+      - name: Install mermaid-cli
+        run: |
+          sudo apt-get update
+          sudo apt-get install nodejs npm graphviz
+          npm install -g @mermaid-js/mermaid-cli
+
       - name: Build HTML Documentation
         run: |
           pip install -r requirements_docs.txt --disable-pip-version-check

doc/source/conf.py

@@ -30,10 +30,14 @@
     "sphinx_copybutton",
     "sphinx_toolbox.collapse",
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosectionlabel",
     "sphinx.ext.autosummary",
+    "sphinx.ext.graphviz",
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
     "sphinx.ext.todo",
+    "sphinxcontrib.mermaid",
+    "sphinx_tabs.tabs",
 ]
 
 # Intersphinx mapping
@@ -89,3 +93,22 @@
 #      author, 'ansys.mapdl.core', 'Pythonic interface to MAPDL using gRPC',
 #      'Engineering Software'),
 # ]
+
+# Include numerical references for the figures
+numfig = True
+
+# Do not include the following patterns as documentation source files.
+# See issue: https://github.com/sphinx-doc/sphinx/issues/1668
+exclude_patterns = ["packaging/diag/*", "packaging/code/*"]
+
+# Fix excessive margins in mermaid output.
+# See issue: https://github.com/mermaid-js/mermaid/issues/1800#issuecomment-741617143
+mermaid_output_format = "png"
+mermaid_params = ["--width", "2000"]
+
+# Generate section labels up to three levels deep
+autosectionlabel_maxdepth = 3
+
+# TODO: warning suppression is temporary till https://github.com/pyansys/dev-guide/issues/64
+# gets fully implemented.
+suppress_warnings = ["autosectionlabel.*"]

doc/source/guidelines/dev_practices.rst

@@ -84,11 +84,11 @@ changes any given branch is introducing before looking at the code.
 -  ``doc/``: for any changes only pertaining to documentation
 -  ``no-ci/``: for low-impact activity that should not trigger the CI
    routines
--  ``testing/``: improvements or changes to testing
--  ``release/``: releases (see below)
+-  ``testing/``: Improvements or changes to testing
+-  ``release/``: Releases (see below)
 
-Testing
-~~~~~~~
+Unit Testing
+~~~~~~~~~~~~
 When making changes, periodically test locally before creating a PR.
 Because the following tests are executed after any commit or PR, we
 ask that you perform the following procedure locally to track down

doc/source/guidelines/test_practices.rst

@@ -245,6 +245,8 @@ and a Python wrapping:
        command : str
            Command to run on the remote server.
 
+       """
+
 Your example test would be:
 
 .. code:: python
@@ -282,8 +284,8 @@ Testing Framework
 For consistency, PyAnsys tools and libraries should use either the `unittest
 <https://docs.python.org/3/library/unittest.html>`_ or `pytest
 <https://docs.pytest.org/>`_ frameworks for unit testing. As described in
-:ref:`repo_dir_struct`, unit tests should be placed into the ``tests``
-directory in the root directory of the library::
+:ref:`Required Files for a PyAnsys Project`, unit tests should be placed in the ``tests``
+directory in the library's root directory::
 
    tests/
        test_basic.py

doc/source/overview/administration.rst

@@ -43,14 +43,14 @@ description, or branch protection management.
 
 Each repository is expected to follow this minimum set of standards:
 
-- Minimum code standards following PEP8. See :ref:`best_practices`.
-- CI/CD using GitHub actions or Azure DevOps to enforce coding standards. See :ref:`ci_cd`.
-- Publicly hosted documentation detailing API with examples. See
+- PEP8 code standards. See :ref:`best_practices`.
+- CI/CD using GitHub actions or Azure DevOps to enforce coding standards.
+- Publicly hosted documentation describing the API and providing examples. See
   :ref:`api_documentation`.
-- Unit testing with at least 80% test coverage. See :ref:`ci_cd`.
+- Unit testing with at least 80% test coverage.
 - Infrastructure in place to deploy the library as a package on `PyPi
-  <https://pypi.org/>`_.  See :ref:`packaging`.
-- Proper license file and author. See :ref:`setup_file` and :ref:`license_file`.
+  <https://pypi.org/>`_.  See :ref:`Packaging Style`.
+- Proper license file and author. See :ref:`The \`\`setup.py\`\` File` and :ref:`The \`\`LICENSE\`\` File`.
 
 
 Release Procedures and Versioning

doc/source/overview/contributing.rst

@@ -136,7 +136,7 @@ to :ref:`branch_naming` when you are ready to create a pull request.
 Licensing
 =========
 All contributed code will be licensed under the MIT License. For more information, see
-:ref:`license_file`. The ``LICENSE`` file containing the MIT License must be included in
+:ref:`The \`\`LICENSE\`\` File`. The ``LICENSE`` file containing the MIT License must be included in
 the root directory of a PyAnsys repository.
 
 If you did not write the code that you are contributing yourself, it is your

doc/source/packaging/build-systems.rst

@@ -0,0 +1,173 @@
+.. _ref_build_system:
+
+############
+Build System
+############
+
+The build system is a fundamental tool for packaging Python
+libraries. It generates distribution files that can be shared with
+users and developers. 
+
+
+Artifacts
+=========
+
+The build system allows maintainers to generate artifacts for their Python
+libraries. Here, `artifacts` refers to both wheel and source files:
+
+- ``Wheel files`` have the ``*.whl`` file extension.
+- ``Source files`` have the ``*.tar.gz`` or ``*.zip`` extension.
+
+These are the files to upload to `PyPI`_ when releasing a new version of a
+PyAnsys project.
+
+.. warning::
+
+   Not all files are included by default in the source distribution. A
+   `MANIFEST.in`_ is required at the root of the project to specify additional
+   files.
+
+
+The interaction between the maintainer and the build system is performed using a
+build system tool. This tool provides both a frontend and a backend. The maintainers
+trigger the frontend, which then calls the backend to read the
+project directory and generate the artifacts, as :numref:`build system diag` shows.
+
+.. include:: diag/build_system_diag.rst
+
+
+PEP 517 and PEP 518
+===================
+
+For a long time, the ``setup.py`` file was the only way of specifying the
+project structure, metadata, and installation workflow that `pip`_ was to follow.
+However, having to execute a Python file when installing a Python package
+introduced the following problems:
+
+- It was not possible to know which dependencies required the ``setup.py`` file
+  to be properly executed.
+
+- The default Python package installer, `pip`_, expected `setuptools`_ to be the
+  default build system tool, excluding others like `flit`_ and `poetry`_.
+
+These problems led to the acceptance of `PEP 517`_ and `PEP 518`_.
+
+
+PEP 517
+-------
+
+`PEP 517`_ allows Python developers to specify the build backend tool for
+generating artifacts. The previous :numref:`build system diag` diagram shows the
+most popular backends:
+
+- `Setuptools`_ , while very popular, lacks the ability to declare build time dependencies
+  and is difficult to extend.
+- `Flit`_ is a lightweight build system tool for Python.
+- `Poetry`_ focuses on dependency management and environment isolation.
+
+`PEP 517` introduced the ``build-backend`` key inside the
+``[build-system]`` table in the ``pyproject.toml``.
+
+
+PEP 518
+-------
+
+In addition to the ``setup.py`` file, `PEP 518`_ includes a project file named
+``pyproject.toml``. The main goal of this file is to specify build time dependencies.
+However, some build system tools like `flit`_ or `poetry`_ are able to specify all
+project metadata inside the ``pyproject.toml`` file and eliminate usage of the 
+``setup.py`` file.
+
+To specify the build time requirements, the ``[build-system]`` table must be
+declared in the ``pyproject.toml`` file. Within it, the ``requires`` key is
+assigned to a list of strings, which are the build time
+requirements.
+
+The combination of `PEP 517`_ and `PEP 518`_ leads to the following syntax in a
+``pyproject.toml`` file:
+
+.. code:: toml
+
+   [build-system]
+   requires = ["flit"] # Defined by PEP 518
+   build-backend = "flit_core.api" # Defined by PEP 517
+
+
+Build Backend Tools
+===================
+
+This section lists some of the most popular build systems in the
+Python ecosystem. Although all of them achieve the same goal, there are a few
+differences regarding their capabilities and the way of specifying project
+metadata.
+
+.. TODO: Include links to each build system allowed metadata fields
+
+Setuptools
+----------
+
+`Setuptools`_ has been a part of the Python ecosystem for a long time. Unless
+you require high control over your project's installation steps, you should use
+`flit`_ or `poetry`_.
+
+If you do not need a dynamic installation process, you can consider using a
+``setup.cfg`` file. However, the ``setup.py`` file is still required. The ``setup.cfg`` file
+should have a call to the ``setup()`` function to act as the entry point of the
+build backend system.
+
+All of these `setuptools metadata fields`_ are valid and must be
+specified either in the ``setup.py`` or ``setup.cfg`` file.
+
+
+Flit
+----
+
+Flit is a modern and lightweight build system that requires developers
+to manage virtual environments on their own. Developers must:
+
+* Create a virtual environment and activate it.
+* Install the package in editable mode.
+
+Flit is the default tool for creating a new ``pyansys`` project when using the
+`ansys-templates tool`_.
+
+The ``[project]`` section specifies the project's metadata and required
+dependencies. For more information, see `flit pyproject.toml
+guidelines`_.
+
+
+Poetry
+------
+
+Because of its ``poetry.lock`` file, Poetry provides strong dependency pinning. When
+installing a package, poetry creates a virtual environment, thus ensuring an isolated
+package development environment.
+
+Nevertheless, it is possible to make Poetry ignore the ``poetry.lock`` file with:
+
+.. code:: bash
+
+   poetry config virtualenvs.create false --local
+
+Using `poetry`_ is popular because it:
+
+* Supports pinning dependency versions via a ``poetry.lock`` file that can be
+  used for testing and CI
+* Allows downstream packages to still consume a loose dependency specification
+* Integrates with `dependabot`_ to update the pinned version
+
+The ``[tool.poetry]`` section contains metadata and defines project
+dependencies. For more information, see `poetry pyproject.toml documentation`_.
+
+
+.. _MANIFEST.in: https://packaging.python.org/en/latest/guides/using-manifest-in/
+.. _PyPI: https://pypi.org/
+.. _pip:
+.. _flit: https://flit.pypa.io/en/latest/
+.. _poetry: https://python-poetry.org/
+.. _poetry pyproject.toml documentation: https://python-poetry.org/docs/pyproject/
+.. _setuptools: https://pypi.org/project/setuptools/
+.. _setuptools metadata fields: https://setuptools.pypa.io/en/latest/userguide/declarative_config.html#declarative-config
+.. _flit pyproject.toml guidelines: https://flit.readthedocs.io/en/latest/pyproject_toml.html
+.. _dependabot: https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/about-dependabot-version-updates
+.. _ansys-templates tool: https://github.com/pyansys/ansys-templates

doc/source/packaging/code/license_mit_code.rst

@@ -0,0 +1,23 @@
+.. code:: text
+
+    MIT License
+
+    Copyright (c) <YEAR> ANSYS, Inc. All rights reserved.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the “Software”), to
+    deal in the Software without restriction, including without limitation the
+    rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+    sell copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in
+    all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+    IN THE SOFTWARE.

doc/source/packaging/code/pyproject_code.rst

@@ -0,0 +1,13 @@
+.. tabs::
+
+   .. tab:: setuptools
+
+      .. include:: code/pyproject_setuptools_code.rst
+
+   .. tab:: flit
+
+      .. include:: code/pyproject_flit_code.rst
+
+   .. tab:: poetry
+
+      .. include:: code/pyproject_poetry_code.rst