From 91c4676d12891c6d1303a9acc5cea3c318a3a420 Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Mon, 28 Mar 2022 16:31:54 +0200 Subject: [PATCH 01/37] New Package Style layout --- doc/source/packaging/ci_cd.rst | 24 -- doc/source/packaging/doc_directory.rst | 16 - doc/source/packaging/index.rst | 12 +- doc/source/packaging/library_names.rst | 53 --- doc/source/packaging/library_structure.rst | 12 - doc/source/packaging/license.rst | 10 - doc/source/packaging/packaging.rst | 323 ------------------ doc/source/packaging/readme_file.rst | 26 -- .../packaging/repo_directory_structure.rst | 33 -- doc/source/packaging/setup_file.rst | 56 --- doc/source/packaging/source_organization.rst | 47 --- doc/source/packaging/structure.rst | 94 +++++ .../packaging/{template.rst => templates.rst} | 12 +- 13 files changed, 102 insertions(+), 616 deletions(-) delete mode 100644 doc/source/packaging/ci_cd.rst delete mode 100644 doc/source/packaging/doc_directory.rst delete mode 100644 doc/source/packaging/library_names.rst delete mode 100644 doc/source/packaging/library_structure.rst delete mode 100644 doc/source/packaging/license.rst delete mode 100644 doc/source/packaging/packaging.rst delete mode 100644 doc/source/packaging/readme_file.rst delete mode 100644 doc/source/packaging/repo_directory_structure.rst delete mode 100644 doc/source/packaging/setup_file.rst delete mode 100644 doc/source/packaging/source_organization.rst create mode 100644 doc/source/packaging/structure.rst rename doc/source/packaging/{template.rst => templates.rst} (96%) diff --git a/doc/source/packaging/ci_cd.rst b/doc/source/packaging/ci_cd.rst deleted file mode 100644 index 7bda3be1a..000000000 --- a/doc/source/packaging/ci_cd.rst +++ /dev/null @@ -1,24 +0,0 @@ -.. _ci_cd: - -CI/CD -##### -CI/CD (continuous integration/continuous delivery) is -achieved using either public `Azure DevOps -`_ or -`GitHub Workflow Actions `_ -for unit testing, release builds, and documentation builds. -The selected method should also be used for branch protection. -For more information, see :ref:`repository_management`. - -Here are some good examples: - -- `PyAnsys Sphinx documentation theme action `_: - Generates Ansys Python package documentation using the `PyAnsys Sphinx theme `__. -- `MAPDL documentation action `_: - Generates MAPDL documentation using product containers. -- `PyAEDT unit testing action `_: - Runs unit testing using an application preinstalled on a self-hosted agent. -- `MAPDL Azure DevOps action `_: - Uses a containerized application to run unit testing for an Azure pipeline. -- `DPF-Core Azure DevOps action `_: - Uses a universal package to run unit testing. diff --git a/doc/source/packaging/doc_directory.rst b/doc/source/packaging/doc_directory.rst deleted file mode 100644 index 10ccad9c4..000000000 --- a/doc/source/packaging/doc_directory.rst +++ /dev/null @@ -1,16 +0,0 @@ -Documentation Directory -####################### -The directory ``doc`` contains the documentation for the library -package, including: - -- The same information as in the README file in the root directory - of the library's repository. You should reuse the ``README.rst`` - file if possible to avoid duplication. -- In-depth getting started information, including installation details. -- API reference containing `Sphinx autosummary API documentation - `_. -- User guide containing basic examples, thorough descriptions of the library, - use case scenarios, and descriptive examples explaining methodologies. -- Examples consisting of `Jupyter Notebooks `_. -- Contributing section, which can be linked to the general "Contributing" - section in this developer's guide. diff --git a/doc/source/packaging/index.rst b/doc/source/packaging/index.rst index c0cd15c8b..2558be61a 100644 --- a/doc/source/packaging/index.rst +++ b/doc/source/packaging/index.rst @@ -40,17 +40,7 @@ model and API. :hidden: :maxdepth: 3 - template - library_structure - library_names - repo_directory_structure - ci_cd - source_organization - readme_file - setup_file - doc_directory - license - packaging.rst + templates .. _gRPC: https://grpc.io/ .. _pythoncom: http://timgolden.me.uk/pywin32-docs/pythoncom.html diff --git a/doc/source/packaging/library_names.rst b/doc/source/packaging/library_names.rst deleted file mode 100644 index d2b930f9a..000000000 --- a/doc/source/packaging/library_names.rst +++ /dev/null @@ -1,53 +0,0 @@ -Project, Repository, and Library Names -###################################### -Large organizations providing Python packages -follow a consistent naming pattern. Ansys follows -these naming conventions: - -- The project name is to be ``Py``. For example, - ``PyMAPDL`` is the project name for MAPDL and ``PyAEDT`` - is the project name for AEDT. -- The repository name as hosted on GitHub should be all - lowercase to follow GitHub community standards. For - example, `pymapdl`_ and `pyaedt`_. -- The Python library name is to be in the format - ``ansys--``. For example, - `ansys-mapdl-core `_ - is the name for the core MAPDL library. - -Using long Python library names provides two primary advantages: - -- `Namespace Packages`_ can be used to designate official - Ansys packages -- Consistent branding and style can be applied to PyAnsys libraries - - -gRPC Interface Package ----------------------- -Lower level gRPC interface packages like `ansys-api-mapdl`_ should always be -named ``ansys-api-`` or may contain an additional level with -``ansys-api--``. - -This is to standarize the API packages: - -.. code:: - - ─ansys - │ ├───api - │ │ ├─── - │ │ │ ├───VERSION - │ │ │ ├───v1 - │ │ │ │ ├───sample.proto - - -Where the package name within ``sample.proto`` would be: - -.. code:: - - package ansys.api..v1; - - -.. _PyMAPDL: https://github.com/pyansys/pymapdl -.. _PyAEDT: https://github.com/pyansys/PyAEDT -.. _Namespace Packages: https://packaging.python.org/guides/packaging-namespace-packages/ -.. _ansys-api-mapdl: https://pypi.org/project/ansys-api-mapdl/ diff --git a/doc/source/packaging/library_structure.rst b/doc/source/packaging/library_structure.rst deleted file mode 100644 index 3a2b993aa..000000000 --- a/doc/source/packaging/library_structure.rst +++ /dev/null @@ -1,12 +0,0 @@ -Library Structure -================= -All PyAnsys libraries are expected to follow a consistent pattern for: - - - Project, repository, and library names - - Repository directory structure - - Licensing - - Package configuration in the ``setup.py`` file - - Unit testing - - CI/CD using Azure DevOps or GitHub Workflow Actions - - Documentation - diff --git a/doc/source/packaging/license.rst b/doc/source/packaging/license.rst deleted file mode 100644 index 922a01c63..000000000 --- a/doc/source/packaging/license.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _license_file: - -License File -############ -PyAnsys libraries are expected to have this license file included in -the root directory of their repositories. - ------------- - -.. include:: ../../../LICENSE diff --git a/doc/source/packaging/packaging.rst b/doc/source/packaging/packaging.rst deleted file mode 100644 index 99a7008fd..000000000 --- a/doc/source/packaging/packaging.rst +++ /dev/null @@ -1,323 +0,0 @@ -.. _packaging: - -Packaging -######### - -A Python package organizes and structures a Python library, which contains -several modules and assets such as examples or binary extensions. A Python -package offers an easy, reliable, and comprehensive way to distribute and -install a Python library on a variety of platforms and environments. - -.. note:: - - If you want to create a new PyAnsys project according to the guidelines - presented in the following lines, consider using the `ansys-templates tool`_. - - -Python Scripts, Modules, Sub-packages, and Packages ---------------------------------------------------- - -It is important to understand the difference between Python scripts, modules, -sub-packages, and packages: - -* ``Script``: Any Python file with logic source code. -* ``Module``: Any Python script hosted next to an ``__init__.py`` file. -* ``Sub-package``: Any directory containing various Python modules. -* ``Package``: Any directory containing Python modules and sub-packages. - -The following structure is shown to better explain previous concepts: - -.. code:: bash - - . - ├── src - │   └── package - │   ├── subpackage_a - │   │   ├── __init__.py - │   │   └── module_c.py - │   ├── __init__.py - │   ├── module_a.py - │   └── module_b.py - ├── LICENSE - ├── README.rst - └── pyproject.toml - - -Namespace Packaging -------------------- -A PyAnsys library uses `namespace packaging`_. Namespace packages allow you -to easily split sub-packages from a package into single, independent -distributions. - -There are different approaches available for creating a namespace package. For -the ``ansys`` namespace, we use the `PEP 420`_ `native namespace packages`_ -approach. - -Therefore, the source directory of any `PyAnsys library` should look like this: - -.. code:: bash - - . - └── src - └── ansys - └── product - └── library - └── __init__.py - - -Required Files --------------- - -* ``README.rst`` file: Describes the purpose of the package. - *The format of this file must be reStructuredText.* - -* ``LICENSE`` file: Specifies copyrights and required authorization. - -* ``pyproject.toml`` file: Provides package metadata and defines how the package - is built. There are different build backends available, such as `setuptools`_, - `poetry`_, and `flit`_. - -* ``src/ansys/product/library/__init__.py`` file: Usually contains the - version of the package in a variable named ``__version__``. The value of this - variable can be parsed from the ``pyproject.toml`` file so that the version - is only specified in one location. - - -Additional Directories ----------------------- - -The following directories may be specified at the same level as the ``src/`` one: - -* ``tests/``: Contains all unit tests for the package. It is - likely that these tests take advantage of the `pytest`_ framework. - -* ``doc/``: Contain all documentation files and examples on - how to use the package. - - -Project File and Build System ------------------------------- - -The ``pyproject.toml`` file is the standardized build configuration file for Python -projects. It must contain at least a ``[build-system]`` section, which determines -how the project is built. Some commonly used packaging tools are `setuptools`_, -`poetry`_, and `flit`_. All three of these packaging tools are currently supported by -the ``pyansys-advanced`` template, which is included in the `ansys-templates tool`_. - - -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 by running: - -.. 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 the project's -dependencies. For more information, see `poetry pyproject.toml documentation`_. - - -Setuptools -^^^^^^^^^^ - -Setuptools is a very well known build system in the Python ecosystem. It is used -in projects requiring a ``setup.py`` file and can be used in projects with a -``pyproject.toml`` file, although not all metadata in this second file -is fully supported yet. - -The main advantage of this build system is the ability to create custom build -steps in the form of Python code. - - -Specifying Package Version --------------------------- - -It is very common for packages to specify their current version in the -``__version__`` variable. This variable is usually declared in the -``__init__.py`` file included in the ``library`` directory. - -However, it is also required to specify the version in the ``pyproject.toml`` or -``setup.py`` file. This leads to a duplicate declaration of the project's version, -which could lead to a potential mismatch between both. - -Therefore, a good practice is to take advantage of the `importlib.metadata package`_ -for parsing the version from package metadata. This guarantees that there is no mismatch -between both version declarations. - - -.. code:: python - - try: - import importlib.metadata as importlib_metadata - except ModuleNotFoundError: - import importlib_metadata - - __version__ = importlib_metadata.version(__name__.replace(".", "-")) - - -Extra Tools Configuration -------------------------- - -There are plenty of tools in the Python ecosystem that enable developers to -write clean code according to different coding style guidelines. Some of these -tools are `black`_, `isort`_, `flake8`_, and `mypy`_. - -Some of these tools can be configured. This configuration might be specified in -custom files required by the tool or in the ``pyproject.toml`` file, thus reducing the -number of files in the project directory. - -.. note:: - - When using `setuptools`_ as a build backend, providing the metadata in - the ``pyproject.toml`` file is not yet fully supported. Instead, it also - requires a ``setup.cfg`` file, ``setup.py`` file, or both files. - -In the `pyansys template`, all these configurations are included by default in -the ``.pre-commit-config.yaml`` file because ``pre-commit`` is not able to parse the -``pyproject.toml`` file nor the ``setup.py`` file. - - -Generate the Package and Upload It on PyPI ------------------------------------------- - -The first time that you want to upload a package on PyPI under `ansys `_ -account, you must perform the following process manually. - -Create the python package. - -.. code:: - - pip install build - python -m build - -If using flit or poetry, you can also run: - -.. code:: - - flit build - poetry build - -Verify the distribution's long description rendering with ``twine``. - -.. code:: - - pip install twine - twine check dist/* - - -Upload the package to PyPI using ``twine`` and the upload token generated for -the ``ansys`` PyPI account. As soon as the package has been released for the -first time, it is possible to create an independent token dedicated to this -package. This way the token stored in the GitHub secrets and used in the -release's workflow is only related to that specific package. This limits the -exposure to any potential token security flaws. Contact -alexander.kaszynski@ansys.com for the token. - -.. code:: - - python -m twine upload -u __token__ -p --skip-existing dist/* - -For the next release upload, you can do it through the CI/CD workflow after generating a token just for this package. -Create a `secret`_ in GitHub settings. -Name it ``PYPI_TOKEN`` and assign it the token provided by PyPI. -This token will be reused in the CI/CD workflow handling the package distribution. - -Tag a Release -------------- -To deploy a new package on PyPI, you must tag a release under a release branch. The PyAnsys project -follows the `trunk-based development`_ source-control branching model, where the main development -branch is always in a releasable state. - -To tag the release, update your main local branch. - -.. code:: - - git checkout main - git pull - -Then, create a release branch. - -.. code:: - - git checkout -b release/MAJOR.MINOR - -Bump the version number in the ``_version`` file to ``MAJOR.MINOR.PATCH``. - -Commit and push your changes and then create the tag. - -.. code:: - - git commit -am "Increase version to v" - git tag v - git push --tags - -Following this tag creation, the workflow responsible for the distribution -will be automatically triggered. - -Install a Package ------------------ -Install a package with: - -.. code:: - - pip install ansys-- - -To create a package complying with the above standards, here is the minimal content of your PyAnsys library: - -.. code:: - - ansys///__init__.py - LICENSE - README.rst - pyproject.toml - tests/ - - -.. _namespace packaging: https://packaging.python.org/guides/packaging-namespace-packages/ -.. _native namespace packages: https://packaging.python.org/guides/packaging-namespace-packages/#native-namespace-packages -.. _PEP 420: https://www.python.org/dev/peps/pep-0420/ -.. _setuptools: https://setuptools.pypa.io -.. _poetry: https://python-poetry.org/docs/ -.. _flit pyproject.toml guidelines: https://flit.readthedocs.io/en/latest/pyproject_toml.html -.. _flit: https://flit.readthedocs.io -.. _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/pyansys-templates -.. _poetry pyproject.toml documentation: https://python-poetry.org/docs/pyproject/ -.. _black: https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#configuration-via-a-file -.. _mypy: https://mypy.readthedocs.io/en/stable/config_file.html#the-mypy-configuration-file -.. _trunk-based development: https://trunkbaseddevelopment.com/ -.. _secret: https://docs.github.com/en/actions/reference/encrypted-secrets -.. _setup.py: https://packaging.python.org/tutorials/packaging-projects/#configuring-metadata -.. _importlib.metadata package: https://docs.python.org/3/library/importlib.metadata.html -.. _isort: https://github.com/PyCQA/isort -.. _flake8: https://flake8.pycqa.org/en/latest/ -.. _pytest: https://docs.pytest.org/en/latest/ diff --git a/doc/source/packaging/readme_file.rst b/doc/source/packaging/readme_file.rst deleted file mode 100644 index e07ac735c..000000000 --- a/doc/source/packaging/readme_file.rst +++ /dev/null @@ -1,26 +0,0 @@ -README File -########### -Each PyAnsys library should have a README file in the root directory. -To create this file, use either `reStructuredText Markup Syntax`_ to -create a file named ``README.rst`` or `Markdown Syntax`_ to create a file -named ``README.md`` - -While Markdown syntax has better GitHub support, text in RST files can -be reused within Sphinx documentation, which avoids duplicating any -auto-generated Sphinx pages. For example, see `pyansys-sphinx-theme index.rst`_. - -.. _pyansys-sphinx-theme index.rst: https://github.com/pyansys/pyansys-sphinx-theme/blob/main/doc/source/index.rst -.. _reStructuredText Markup Syntax: https://docutils.sourceforge.io/rst.html -.. _Markdown Syntax: https://www.markdownguide.org/basic-syntax/ - - -The README file should at the minimum contain these elements: - -- PyAnsys library title -- General description -- Installation directions (via ``pip install`` and ``git clone``) -- Basic usage -- Links to the full documentation - -The README file is also reused within the ``long_description`` in -the package's ``setup.py`` file. diff --git a/doc/source/packaging/repo_directory_structure.rst b/doc/source/packaging/repo_directory_structure.rst deleted file mode 100644 index 21979929e..000000000 --- a/doc/source/packaging/repo_directory_structure.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. _repo_dir_struct: - -Repository Directory Structure ------------------------------- -The source for a PyAnsys library is hosted in an individual -repository under the `PyAnsys Organization Account -`__. The repository should contain -the source, documentation, and unit testing of the library in -this directory structure: - -:: - - .ci/azure-pipelines.yml (optional) - .github/workflows/ci.yml - ansys/ - / - / - __init__.py - my_module.py - my_other_module.py - doc/ - conf.py - index.rst - requirements.txt - LICENSE - README.rst - requirements.txt - setup.py - tests/ - requirements.txt - test_basic.py - test_advanced.py - diff --git a/doc/source/packaging/setup_file.rst b/doc/source/packaging/setup_file.rst deleted file mode 100644 index bcc6717b9..000000000 --- a/doc/source/packaging/setup_file.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. _setup_file: - -Setup File -########## -The setup file for a PyAnsys library package, ``setup.py``, should contain -these elements: - -- Name (such as ``ansys-mapdl-core``) -- Packages (such as ``ansys.mapdl.core``) -- Short description -- Long description in a ``README.md`` or ``README.rst`` file -- `Single-sourced package version `_ -- Author of ``"ANSYS, Inc."`` -- Maintainer's name and email -- Dependency requirements -- Applicable classifiers - -The ``ansys--`` would have at the minimum -the following within its ``setup.py``. - -.. code:: python - - """Setup file for ansys--""" - import codecs - import os - from io import open as io_open - from setuptools import setup - - THIS_PATH = os.path.abspath(os.path.dirname(__file__)) - __version__ = None - version_file = os.path.join(THIS_PATH, 'ansys', '', - '', '_version.py') - with io_open(version_file, mode='r') as fd: - exec(fd.read()) - - setup( - name='ansys--', - packages=['ansys..'], - version=__version__, - description='Short description', - long_description=open('README.rst').read(), - long_description_content_type='text/x-rst', - url='https://github.com/pyansys/pyansys-package-example/', - license='MIT', - author='ANSYS, Inc.', - maintainer='First Last', - maintainer_email='first.last@ansys.com', - install_requires=['grpcio>=1.30.0'], - python_requires='>=3.5', - classifiers=[ - 'Development Status :: 4 - Beta', - 'Programming Language :: Python :: 3', - 'License :: OSI Approved :: MIT License', - 'Operating System :: OS Independent', - ], - ) diff --git a/doc/source/packaging/source_organization.rst b/doc/source/packaging/source_organization.rst deleted file mode 100644 index cc5b7e547..000000000 --- a/doc/source/packaging/source_organization.rst +++ /dev/null @@ -1,47 +0,0 @@ -Source Organization -################### -PyAnsys libraries follow the `Namespace Packages`_ convention to allow -multiple libraries to use the same shared ``ansys`` namespace: - -``ansys///`` - -For example, the `PyMAPDL`_ library with the ``ansys-mapdl-core`` package -name has the following directory structure: - -:: - - setup.py - ansys/ - mapdl/ - core/ - __init__.py - launcher.py - mapdl_grpc.py - ... - -This allows the `PyMAPDL`_ library to be imported with: - -.. code:: python - - >>> from ansys.mapdl import core as pymapdl - -When using this convention, other namespace packages can use the -``ansys-mapdl`` namespace. - -.. code:: python - - >>> from ansys.mapdl import reader as pymapdl_reader - -.. note:: - - Do not include ``__init__.py`` in first-level and second-level - directories. If ``__init__.py`` is included in these levels, - namespace packages will conflict, allowing only one to be imported. - -While the ``ansys-`` namespace is verbose, using it -consistently is important because it allows multiple products and services -to share the same namespace. This makes it easy when searching for "ansys" -packages within the `Python Package Index PyPi `_. - -.. _Namespace Packages: https://packaging.python.org/guides/packaging-namespace-packages/ -.. _PyMAPDL: https://github.com/pyansys/pymapdl diff --git a/doc/source/packaging/structure.rst b/doc/source/packaging/structure.rst new file mode 100644 index 000000000..8fc3cd4b5 --- /dev/null +++ b/doc/source/packaging/structure.rst @@ -0,0 +1,94 @@ +.. ref_project_structure:: + +################# +Project Structure +################# + +Most of the projects in the PyAnsys ecosystem ship in the form of a Python +Package. This is the formal way of distributing Python-based projects. + +The guide presented in this page is compliant with the `Python Packaging +Authority`_ and the `PyAnsys`_ recommendations. + +.. note:: + + The best way to keep up-to-date with Python Packaging is to check the `Python + Packaging User Guide`_, maintained by the `Python Packaging Authority`_ (PyPA). + PyAnsys guidelines are build on top of PyPA ones. + + +.. TODO: Explain the difference between Package and Library? + Package: only holds modules + Library: a collection of packages + + +PyAnsys Project Required Files +============================== + +The fundamental PyAnsys Library structure is composed by the following files and +directories: + +.. code:: bash + + pyproduct_library/ + │ + ├── doc/ + │ ├── make.bat + │ ├── Makefile + │ └── source/ + │ ├── index.rst + │ └── conf.py + │ + ├── src/ + │ └── ansys/ + │ └── product/ + │ └── library/ + │ └── __init__.py + │ + ├── tests/ + │ └── test_*.py + │ + ├── LICENSE + ├── README.rst + ├── pyproject.toml + └── setup.py (optional) + +The following directories can be identified in previous structure: + +- ``doc/`` is devoted to store any piece of information related to documentation, + guidelines and examples. + +- ``src/`` is used to collect all the Python modules and scripts that form + the project. + +- ``tests/`` stores all the unit tests whose purpose is to check the integrity + of the project. + + +The ``doc/`` Directory +---------------------- + + +The ``src/`` Directory +---------------------- + + +The ``tests/`` Directory +------------------------ + + +The ``LICENSE`` File +-------------------- + + +The ``README.rst`` File +----------------------- + + + + + +.. REFERENCES & LINKS + +.. _`Python Packaging User Guide`: https://packaging.python.org/en/latest/ +.. _`Python Packaging Authority`: https://www.pypa.io/en/latest/ diff --git a/doc/source/packaging/template.rst b/doc/source/packaging/templates.rst similarity index 96% rename from doc/source/packaging/template.rst rename to doc/source/packaging/templates.rst index 9f0e8c14c..63aa89f97 100644 --- a/doc/source/packaging/template.rst +++ b/doc/source/packaging/templates.rst @@ -1,14 +1,16 @@ -################ -Library Template -################ +.. _templates: + +######### +Templates +######### Starting a new project from scratch is a tedious task. For this reason, the `ansys-templates`_ tool was created to simplify the starting process and make it more dynamic. Any rendered project will be compliant with the latest PyAnsys coding and API style guidelines. -The ansys-templates tool -======================== +The ``ansys-templates`` tool +============================ The `ansys-templates`_ is a command line interface which provides you with a collection of templates. This tool allows you to create new PyAnsys projects From 45899c00ed0e9796fdcc9c11b0dcef3239c13a13 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jorge=20Mart=C3=ADnez?= <28702884+jorgepiloto@users.noreply.github.com> Date: Tue, 29 Mar 2022 11:10:16 +0200 Subject: [PATCH 02/37] Apply suggestions from code review Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> --- doc/source/packaging/structure.rst | 23 ++++++++++------------- doc/source/packaging/templates.rst | 4 ++-- 2 files changed, 12 insertions(+), 15 deletions(-) diff --git a/doc/source/packaging/structure.rst b/doc/source/packaging/structure.rst index 8fc3cd4b5..b53d8576e 100644 --- a/doc/source/packaging/structure.rst +++ b/doc/source/packaging/structure.rst @@ -5,16 +5,16 @@ Project Structure ################# Most of the projects in the PyAnsys ecosystem ship in the form of a Python -Package. This is the formal way of distributing Python-based projects. +package. This is the formal way of distributing Python-based projects. The guide presented in this page is compliant with the `Python Packaging -Authority`_ and the `PyAnsys`_ recommendations. +Authority`_ and `PyAnsys`_ recommendations. .. note:: - The best way to keep up-to-date with Python Packaging is to check the `Python + The best way to keep up to date with Python packaging is to check the `Python Packaging User Guide`_, maintained by the `Python Packaging Authority`_ (PyPA). - PyAnsys guidelines are build on top of PyPA ones. + PyAnsys guidelines are built on top of PyPA guidelines. .. TODO: Explain the difference between Package and Library? @@ -22,8 +22,8 @@ Authority`_ and the `PyAnsys`_ recommendations. Library: a collection of packages -PyAnsys Project Required Files -============================== +Required Files for a PyAnsys Project +==================================== The fundamental PyAnsys Library structure is composed by the following files and directories: @@ -53,16 +53,13 @@ directories: ├── pyproject.toml └── setup.py (optional) -The following directories can be identified in previous structure: +Descriptions follow for some of the directories in the structure: -- ``doc/`` is devoted to store any piece of information related to documentation, - guidelines and examples. +- ``doc/`` contains files related to documentation, guidelines, and examples. -- ``src/`` is used to collect all the Python modules and scripts that form - the project. +- ``src/`` contains all Python modules and scripts that form the project. -- ``tests/`` stores all the unit tests whose purpose is to check the integrity - of the project. +- ``tests/`` contains all unit tests for checking the integrity of the project. The ``doc/`` Directory diff --git a/doc/source/packaging/templates.rst b/doc/source/packaging/templates.rst index 63aa89f97..e007c8708 100644 --- a/doc/source/packaging/templates.rst +++ b/doc/source/packaging/templates.rst @@ -12,8 +12,8 @@ PyAnsys coding and API style guidelines. The ``ansys-templates`` tool ============================ -The `ansys-templates`_ is a command line interface which provides you with a -collection of templates. This tool allows you to create new PyAnsys projects +The `ansys-templates`_ is a command line interface that provides you with a +collection of templates. This tool allows you to create new PyAnsys projects. from scratch in a dynamic way by asking you several questions before generating the new project. From 3c220c1660f4c3363f79fecbe6a330316ce88aaf Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Tue, 29 Mar 2022 11:07:10 +0200 Subject: [PATCH 03/37] Enable graphviz and numrefs --- doc/source/conf.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/doc/source/conf.py b/doc/source/conf.py index 057344175..9af1371c0 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -31,6 +31,7 @@ "sphinx_toolbox.collapse", "sphinx.ext.autodoc", "sphinx.ext.autosummary", + "sphinx.ext.graphviz", "sphinx.ext.intersphinx", "sphinx.ext.napoleon", "sphinx.ext.todo", @@ -89,3 +90,10 @@ # 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/diagrams/*"] From 129356ddf06ae4e7fd274b0e67d8e10e9ac82673 Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Tue, 29 Mar 2022 11:45:54 +0200 Subject: [PATCH 04/37] WIP: structure --- .../diagrams/ansys_project_diagram.rst | 34 +++++++++++ .../diagrams/python_elements_diagram.rst | 50 ++++++++++++++++ .../diagrams/python_pkg_lib_diagram.rst | 40 +++++++++++++ doc/source/packaging/index.rst | 1 + doc/source/packaging/structure.rst | 57 ++++++++++++++++--- 5 files changed, 175 insertions(+), 7 deletions(-) create mode 100644 doc/source/packaging/diagrams/ansys_project_diagram.rst create mode 100644 doc/source/packaging/diagrams/python_elements_diagram.rst create mode 100644 doc/source/packaging/diagrams/python_pkg_lib_diagram.rst diff --git a/doc/source/packaging/diagrams/ansys_project_diagram.rst b/doc/source/packaging/diagrams/ansys_project_diagram.rst new file mode 100644 index 000000000..0c918265e --- /dev/null +++ b/doc/source/packaging/diagrams/ansys_project_diagram.rst @@ -0,0 +1,34 @@ +.. _high level pyansys structure: +.. graphviz:: + :caption: High-level structure of a PyAnsys project + :alt: High-level structure of a PyAnsys project + :align: center + + digraph "sphinx-ext-graphviz" { + size="6,4"; + rankdir="LR"; + graph [ + fontname="Verdana", fontsize="10", color="black", fillcolor="white" + ]; + node [ + fontname="Verdana", fontsize="10", style="filled", color="black", fillcolor="#ffc107" + ]; + + pyansys_project [ + label="PyAnsys Project", shape="folder" + ]; + + python_library [ + label="Python Library", shape="folder" + ]; + + other_files [ + label="Other Files", shape="node" + ]; + + pyansys_project -> python_library; + pyansys_project -> other_files; + + } + + diff --git a/doc/source/packaging/diagrams/python_elements_diagram.rst b/doc/source/packaging/diagrams/python_elements_diagram.rst new file mode 100644 index 000000000..c693c1019 --- /dev/null +++ b/doc/source/packaging/diagrams/python_elements_diagram.rst @@ -0,0 +1,50 @@ +.. _python elements diagram: +.. graphviz:: + :caption: Differences between Python modules, sub-packages and, packages + :alt: Differences between Python modules, sub-packages and, packages + :align: center + + digraph "sphinx-ext-graphviz" { + size="6,4"; + rankdir="LR"; + graph [ + fontname="Verdana", fontsize="10", color="black", fillcolor="white" + ]; + node [ + fontname="Verdana", fontsize="10", style="filled", color="black", fillcolor="#ffc107" + ]; + + package [ + label="Package A", shape="folder" + ]; + + sub_package [ + label="Sub-package A", shape="folder" + ]; + + init_file1 [ + label="__init__.py", shape="file" + ]; + + init_file2 [ + label="__init__.py", shape="file" + ]; + + module_foo [ + label="foo.py", shape="file" + ]; + + module_bar [ + label="bar.py", shape="file" + ]; + + package -> sub_package; + package -> init_file1; + package -> module_bar; + + sub_package -> init_file2; + sub_package -> module_foo; + + } + + diff --git a/doc/source/packaging/diagrams/python_pkg_lib_diagram.rst b/doc/source/packaging/diagrams/python_pkg_lib_diagram.rst new file mode 100644 index 000000000..9d6c0bf2f --- /dev/null +++ b/doc/source/packaging/diagrams/python_pkg_lib_diagram.rst @@ -0,0 +1,40 @@ +.. _python pkg lib diagram: +.. graphviz:: + :caption: Difference between Python library and package + :alt: Difference between Python library and package + :align: center + + digraph "sphinx-ext-graphviz" { + size="6,4"; + rankdir="LR"; + graph [ + fontname="Verdana", fontsize="10", color="black", fillcolor="white" + ]; + node [ + fontname="Verdana", fontsize="10", style="filled", color="black", fillcolor="#ffc107" + ]; + + python_library [ + label="Python Library", shape="folder" + ]; + + pkg_A [ + label="Package A", shape="folder" + ]; + + pkg_B [ + label="Package B", shape="folder" + ]; + + pkg_other [ + label="...", shape="folder" + ]; + + + python_library -> pkg_A + python_library -> pkg_B + python_library -> pkg_other + + } + + diff --git a/doc/source/packaging/index.rst b/doc/source/packaging/index.rst index 2558be61a..e83b6f8d1 100644 --- a/doc/source/packaging/index.rst +++ b/doc/source/packaging/index.rst @@ -41,6 +41,7 @@ model and API. :maxdepth: 3 templates + structure .. _gRPC: https://grpc.io/ .. _pythoncom: http://timgolden.me.uk/pywin32-docs/pythoncom.html diff --git a/doc/source/packaging/structure.rst b/doc/source/packaging/structure.rst index b53d8576e..0bf8adb6f 100644 --- a/doc/source/packaging/structure.rst +++ b/doc/source/packaging/structure.rst @@ -1,14 +1,23 @@ -.. ref_project_structure:: +.. _ref_project_structure: ################# Project Structure ################# Most of the projects in the PyAnsys ecosystem ship in the form of a Python -package. This is the formal way of distributing Python-based projects. +library with other additional files. All these files form what it is called a +"project". A project can be uploaded to a repository to better track the changes +applied to it. The high-level structure of a PyAnsys project is exposed in +figure :numref:`high level pyansys structure`. -The guide presented in this page is compliant with the `Python Packaging -Authority`_ and `PyAnsys`_ recommendations. +.. include:: diagrams/ansys_project_diagram.rst + +Python Libraries +================ + +A Python library is the formal way of distributing Python source code. It allows +to reuse and specify Python code dependencies. The guide presented in this page +is compliant with the `Python Packaging Authority`_ and PyAnsys recommendations. .. note:: @@ -17,9 +26,43 @@ Authority`_ and `PyAnsys`_ recommendations. PyAnsys guidelines are built on top of PyPA guidelines. -.. TODO: Explain the difference between Package and Library? - Package: only holds modules - Library: a collection of packages +Scripts, Modules, Sub-packages, and Packages +-------------------------------------------- + +To understand the structure of a Python Library, it is important to know +the difference between Python scripts, modules, sub-packages, and packages. +Figure :numref:`python elements diagram` provides a graphical interpretation. + +* ``Script``: Any Python file with logic source code. +* ``Module``: Any Python script hosted next to an ``__init__.py`` file. +* ``Sub-package``: Any directory containing various Python modules. +* ``Package``: Any directory containing Python modules and sub-packages. + +.. include:: diagrams/python_elements_diagram.rst + + +Differences Between a Python Package and Library +------------------------------------------------ + +Although both terms are used interchangeably, there is a key difference between +them: a Python package is a collection of Python modules and sub-packages while +a Python Library is a collection of Python packages. Figure :numref:`python pkg +lib diagram` exposes this. + +.. include:: diagrams/python_pkg_lib_diagram.rst + + +Other Files +=========== + +Additional files can be stored next to a Python Library. These files will not be +included when distributing the library. Most of these files are metadata, tool +configuration files, and CI workflows definitions. + +.. tip:: + + Avoid having lots of additional files. This reduces mainteinance tasks and + provides a clean root project directory. Required Files for a PyAnsys Project From 1662c1df211883aabd1c587c3396bbb87ca584c8 Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Tue, 29 Mar 2022 12:21:18 +0200 Subject: [PATCH 05/37] Unify Python library diagrams --- .../diagrams/ansys_project_diagram.rst | 2 +- .../diagrams/python_elements_diagram.rst | 50 ------------------- ...diagram.rst => python_library_diagram.rst} | 32 ++++++++++-- doc/source/packaging/structure.rst | 18 +------ 4 files changed, 31 insertions(+), 71 deletions(-) delete mode 100644 doc/source/packaging/diagrams/python_elements_diagram.rst rename doc/source/packaging/diagrams/{python_pkg_lib_diagram.rst => python_library_diagram.rst} (53%) diff --git a/doc/source/packaging/diagrams/ansys_project_diagram.rst b/doc/source/packaging/diagrams/ansys_project_diagram.rst index 0c918265e..70607b578 100644 --- a/doc/source/packaging/diagrams/ansys_project_diagram.rst +++ b/doc/source/packaging/diagrams/ansys_project_diagram.rst @@ -1,6 +1,6 @@ .. _high level pyansys structure: .. graphviz:: - :caption: High-level structure of a PyAnsys project + :caption: A PyAnsys project is composed by a Python library and other files. :alt: High-level structure of a PyAnsys project :align: center diff --git a/doc/source/packaging/diagrams/python_elements_diagram.rst b/doc/source/packaging/diagrams/python_elements_diagram.rst deleted file mode 100644 index c693c1019..000000000 --- a/doc/source/packaging/diagrams/python_elements_diagram.rst +++ /dev/null @@ -1,50 +0,0 @@ -.. _python elements diagram: -.. graphviz:: - :caption: Differences between Python modules, sub-packages and, packages - :alt: Differences between Python modules, sub-packages and, packages - :align: center - - digraph "sphinx-ext-graphviz" { - size="6,4"; - rankdir="LR"; - graph [ - fontname="Verdana", fontsize="10", color="black", fillcolor="white" - ]; - node [ - fontname="Verdana", fontsize="10", style="filled", color="black", fillcolor="#ffc107" - ]; - - package [ - label="Package A", shape="folder" - ]; - - sub_package [ - label="Sub-package A", shape="folder" - ]; - - init_file1 [ - label="__init__.py", shape="file" - ]; - - init_file2 [ - label="__init__.py", shape="file" - ]; - - module_foo [ - label="foo.py", shape="file" - ]; - - module_bar [ - label="bar.py", shape="file" - ]; - - package -> sub_package; - package -> init_file1; - package -> module_bar; - - sub_package -> init_file2; - sub_package -> module_foo; - - } - - diff --git a/doc/source/packaging/diagrams/python_pkg_lib_diagram.rst b/doc/source/packaging/diagrams/python_library_diagram.rst similarity index 53% rename from doc/source/packaging/diagrams/python_pkg_lib_diagram.rst rename to doc/source/packaging/diagrams/python_library_diagram.rst index 9d6c0bf2f..83a24ce80 100644 --- a/doc/source/packaging/diagrams/python_pkg_lib_diagram.rst +++ b/doc/source/packaging/diagrams/python_library_diagram.rst @@ -1,7 +1,7 @@ .. _python pkg lib diagram: .. graphviz:: - :caption: Difference between Python library and package - :alt: Difference between Python library and package + :caption: A Python library is a collection of packages. + :alt: A Python library is a collection of packages. :align: center digraph "sphinx-ext-graphviz" { @@ -30,11 +30,37 @@ label="...", shape="folder" ]; - python_library -> pkg_A python_library -> pkg_B python_library -> pkg_other + sub_package [ + label="Sub-package A", shape="folder" + ]; + + init_file1 [ + label="__init__.py", shape="file" + ]; + + init_file2 [ + label="__init__.py", shape="file" + ]; + + module_foo [ + label="module_foo.py", shape="file" + ]; + + module_bar [ + label="module_bar.py", shape="file" + ]; + + pkg_A -> sub_package; + pkg_A -> init_file1; + pkg_A -> module_foo; + + sub_package -> init_file2; + sub_package -> module_bar; + } diff --git a/doc/source/packaging/structure.rst b/doc/source/packaging/structure.rst index 0bf8adb6f..f763dd03c 100644 --- a/doc/source/packaging/structure.rst +++ b/doc/source/packaging/structure.rst @@ -31,15 +31,12 @@ Scripts, Modules, Sub-packages, and Packages To understand the structure of a Python Library, it is important to know the difference between Python scripts, modules, sub-packages, and packages. -Figure :numref:`python elements diagram` provides a graphical interpretation. * ``Script``: Any Python file with logic source code. * ``Module``: Any Python script hosted next to an ``__init__.py`` file. * ``Sub-package``: Any directory containing various Python modules. * ``Package``: Any directory containing Python modules and sub-packages. -.. include:: diagrams/python_elements_diagram.rst - Differences Between a Python Package and Library ------------------------------------------------ @@ -49,20 +46,7 @@ them: a Python package is a collection of Python modules and sub-packages while a Python Library is a collection of Python packages. Figure :numref:`python pkg lib diagram` exposes this. -.. include:: diagrams/python_pkg_lib_diagram.rst - - -Other Files -=========== - -Additional files can be stored next to a Python Library. These files will not be -included when distributing the library. Most of these files are metadata, tool -configuration files, and CI workflows definitions. - -.. tip:: - - Avoid having lots of additional files. This reduces mainteinance tasks and - provides a clean root project directory. +.. include:: diagrams/python_library_diagram.rst Required Files for a PyAnsys Project From 9ef877373ae45f84ce40349ad8004d91eb7c549d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jorge=20Mart=C3=ADnez?= <28702884+jorgepiloto@users.noreply.github.com> Date: Tue, 29 Mar 2022 12:27:47 +0200 Subject: [PATCH 06/37] Fix library typo Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> --- doc/source/packaging/structure.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/packaging/structure.rst b/doc/source/packaging/structure.rst index f763dd03c..a70963227 100644 --- a/doc/source/packaging/structure.rst +++ b/doc/source/packaging/structure.rst @@ -52,7 +52,7 @@ lib diagram` exposes this. Required Files for a PyAnsys Project ==================================== -The fundamental PyAnsys Library structure is composed by the following files and +The fundamental PyAnsys library structure contains the following files and directories: .. code:: bash From bcd5abde9926c941b9f54fe2a19bcd68757a0fa8 Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Tue, 29 Mar 2022 13:17:10 +0200 Subject: [PATCH 07/37] Complete diagram --- .../pyproduct_library_structure_diagram.rst | 71 +++++++++++++++++++ doc/source/packaging/structure.rst | 25 +------ 2 files changed, 72 insertions(+), 24 deletions(-) create mode 100644 doc/source/packaging/diagrams/pyproduct_library_structure_diagram.rst diff --git a/doc/source/packaging/diagrams/pyproduct_library_structure_diagram.rst b/doc/source/packaging/diagrams/pyproduct_library_structure_diagram.rst new file mode 100644 index 000000000..26fc13950 --- /dev/null +++ b/doc/source/packaging/diagrams/pyproduct_library_structure_diagram.rst @@ -0,0 +1,71 @@ +.. _pyproduct library structure diagram: +.. graphviz:: + :caption: Minimum required PyAnsys project structure + :alt: Minimum required PyAnsys project structure + :align: center + + digraph "sphinx-ext-graphviz" { + size="8,6"; + rankdir="LR"; + graph [ + fontname="Verdana", fontsize="10", color="black", fillcolor="white" + ]; + node [ + fontname="Verdana", fontsize="10", style="filled", color="black", fillcolor="#ffc107" + ]; + + pyproduct_library [ + label="PyAnsys Project", shape="folder" + ]; + + doc [ + label="doc", shape="folder" + ] + + src [ + label="src", shape="folder" + ] + + ansys [ + label="ansys", shape="folder" + ] + + product [ + label="product", shape="folder" + ] + + library [ + label="library", shape="folder" + ] + + init_file [ + label="__init__.py", shape="file" + ] + + tests [ + label="tests", shape="folder" + ] + + pyproject [ + label="pyproject.toml", shape="file" + ] + + setup [ + label="setup.py", shape="file" + ] + + + pyproduct_library -> doc; + pyproduct_library -> src; + pyproduct_library -> tests; + pyproduct_library -> pyproject; + pyproduct_library -> setup; + + src -> ansys; + ansys -> product; + product -> library; + library -> init_file; + + } + + diff --git a/doc/source/packaging/structure.rst b/doc/source/packaging/structure.rst index a70963227..ea6ba009f 100644 --- a/doc/source/packaging/structure.rst +++ b/doc/source/packaging/structure.rst @@ -55,30 +55,7 @@ Required Files for a PyAnsys Project The fundamental PyAnsys library structure contains the following files and directories: -.. code:: bash - - pyproduct_library/ - │ - ├── doc/ - │ ├── make.bat - │ ├── Makefile - │ └── source/ - │ ├── index.rst - │ └── conf.py - │ - ├── src/ - │ └── ansys/ - │ └── product/ - │ └── library/ - │ └── __init__.py - │ - ├── tests/ - │ └── test_*.py - │ - ├── LICENSE - ├── README.rst - ├── pyproject.toml - └── setup.py (optional) +.. include:: diagrams/pyproduct_library_structure_diagram.rst Descriptions follow for some of the directories in the structure: From 4678199c8dca04008abc342f6bd9ff1233bbe85a Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Wed, 30 Mar 2022 09:36:17 +0200 Subject: [PATCH 08/37] Document doc/ dir structure --- .../diagrams/doc_structure_diagram.rst | 59 +++++++++++++++++++ doc/source/packaging/structure.rst | 38 +++++++++++- 2 files changed, 96 insertions(+), 1 deletion(-) create mode 100644 doc/source/packaging/diagrams/doc_structure_diagram.rst diff --git a/doc/source/packaging/diagrams/doc_structure_diagram.rst b/doc/source/packaging/diagrams/doc_structure_diagram.rst new file mode 100644 index 000000000..d031a9834 --- /dev/null +++ b/doc/source/packaging/diagrams/doc_structure_diagram.rst @@ -0,0 +1,59 @@ +.. _doc structure diagram: +.. graphviz:: + :caption: Minimum required PyAnsys project structure + :alt: Minimum required PyAnsys project structure + :align: center + + digraph "sphinx-ext-graphviz" { + size="8,6"; + rankdir="LR"; + graph [ + fontname="Verdana", fontsize="10", color="black", fillcolor="white" + ]; + node [ + fontname="Verdana", fontsize="10", style="filled", color="black", fillcolor="#ffc107" + ]; + + doc [ + label="doc", shape="folder" + ]; + + build [ + label="_build", shape="folder" + ] + + source [ + label="source", shape="folder" + ] + + make_bat [ + label="make.bat", shape="file" + ] + + makefile [ + label="Makefile", shape="file" + ] + + static [ + label="_static", shape="folder" + ] + + index_file [ + label="index.rst", shape="file" + ] + + conf_file [ + label="conf.py", shape="file" + ] + + doc -> build; + doc -> source; + doc -> make_bat; + doc -> makefile; + + source -> conf_file; + source -> index_file; + source -> static; + } + + diff --git a/doc/source/packaging/structure.rst b/doc/source/packaging/structure.rst index ea6ba009f..647092350 100644 --- a/doc/source/packaging/structure.rst +++ b/doc/source/packaging/structure.rst @@ -52,7 +52,7 @@ lib diagram` exposes this. Required Files for a PyAnsys Project ==================================== -The fundamental PyAnsys library structure contains the following files and +The structure of any PyAnsys library contains the following files and directories: .. include:: diagrams/pyproduct_library_structure_diagram.rst @@ -65,10 +65,44 @@ Descriptions follow for some of the directories in the structure: - ``tests/`` contains all unit tests for checking the integrity of the project. +- ``setup.py`` or ``pyproject.toml`` is known as the project's file. + The ``doc/`` Directory ---------------------- +When distributing software it is important to document it. Documenting software +means giving guidelines on how to install and use it but also which functions, +methods and/or classes does it ship with. Examples can also be considered +documentation. The purpose of the ``doc/`` directory is to store all +documentation related files. + +Projects in the PyAnsys ecosystem take advantage of `Sphinx`_, a tool used for +building documentation for Python-based projects. A ``doc/`` directory making +use of `Sphinx`_ requires the following structure, as shown by figure +:numref:`doc structure diagram`: + + +.. include:: diagrams/doc_structure_diagram.rst + +- ``_build`` contains the rendered documentation in various formats: HTML, + PDF... + +- ``source`` contains the RST files which will be rendered when building the + documentation. + +- ``make.bat`` and ``Makefile`` are used to automate cleaning and building + commands. The ``make.bat`` is intended to be used by Windows users while + ``Makefile`` is devised for MacOS/Linux ones. + +The ``source/`` directory needs to contain at least the following files: + +- ``conf.py`` is a Python script used to declare the configuration of `Sphinx`_. +- ``index.rst`` is the index page of the documentation. + +In case you would like to include images or documents, it is recommended to add +those in the ``_static/`` directory. + The ``src/`` Directory ---------------------- @@ -91,5 +125,7 @@ The ``README.rst`` File .. REFERENCES & LINKS +.. _`PyAnsys`: https://docs.pyansys.com/ .. _`Python Packaging User Guide`: https://packaging.python.org/en/latest/ .. _`Python Packaging Authority`: https://www.pypa.io/en/latest/ +.. _`Sphinx`: https://www.sphinx-doc.org/en/master/ From d5980e806ac4f4d418d36aea360062c4350f8d98 Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Wed, 30 Mar 2022 09:56:33 +0200 Subject: [PATCH 09/37] Document src/ dir structure --- .../diagrams/doc_structure_diagram.rst | 4 +- .../diagrams/src_structure_diagram.rst | 64 +++++++++++++++++++ doc/source/packaging/structure.rst | 22 +++++++ 3 files changed, 88 insertions(+), 2 deletions(-) create mode 100644 doc/source/packaging/diagrams/src_structure_diagram.rst diff --git a/doc/source/packaging/diagrams/doc_structure_diagram.rst b/doc/source/packaging/diagrams/doc_structure_diagram.rst index d031a9834..c9680f9c2 100644 --- a/doc/source/packaging/diagrams/doc_structure_diagram.rst +++ b/doc/source/packaging/diagrams/doc_structure_diagram.rst @@ -1,7 +1,7 @@ .. _doc structure diagram: .. graphviz:: - :caption: Minimum required PyAnsys project structure - :alt: Minimum required PyAnsys project structure + :caption: Generic structure for the ``doc/`` directory + :alt: Generic structure for the ``doc/`` directory :align: center digraph "sphinx-ext-graphviz" { diff --git a/doc/source/packaging/diagrams/src_structure_diagram.rst b/doc/source/packaging/diagrams/src_structure_diagram.rst new file mode 100644 index 000000000..a4bda878c --- /dev/null +++ b/doc/source/packaging/diagrams/src_structure_diagram.rst @@ -0,0 +1,64 @@ +.. _src structure diagram: +.. graphviz:: + :caption: Generic structure for the src/ directory + :alt: Generic structure for the src/ directory + :align: center + + digraph "sphinx-ext-graphviz" { + size="8,6"; + rankdir="LR"; + graph [ + fontname="Verdana", fontsize="10", color="black", fillcolor="white" + ]; + node [ + fontname="Verdana", fontsize="10", style="filled", color="black", fillcolor="#ffc107" + ]; + + src [ + label="src", shape="folder" + ]; + + ansys [ + label="ansys", shape="folder" + ] + + product [ + label="product", shape="folder" + ] + + library [ + label="library", shape="folder" + ] + + pkg_A [ + label="Package A", shape="folder" + ] + + init_file_pkgA [ + label="__init__.py", shape="file" + ] + + other_files_pkgA [ + label="...", shape="file" + ] + + init_file [ + label="__init__.py", shape="file" + ] + + other_files [ + label="...", shape="file" + ] + + src -> ansys; + ansys -> product; + product -> library; + library -> init_file; + library -> other_files; + library -> pkg_A; + pkg_A -> init_file_pkgA; + pkg_A -> other_files_pkgA; + + } + + diff --git a/doc/source/packaging/structure.rst b/doc/source/packaging/structure.rst index 647092350..f07faf5ab 100644 --- a/doc/source/packaging/structure.rst +++ b/doc/source/packaging/structure.rst @@ -107,6 +107,26 @@ those in the ``_static/`` directory. The ``src/`` Directory ---------------------- +All the Python source code must be located in this directory. This is where the +build system will look when generating the wheel and source distributions. + +.. warning:: + + Folders inside the ``src/`` cannot contain spaces or hypens. Replace these + symbols by using the underscore '_'. + +The structure of the ``src/`` directory determines the namespace of the PyAnsys +library. Namespace allow you to easily split sub-packages from a package into +single, independent distributions. + +There are different approaches available for creating a namespace package. For +the ansys namespace, we use the `PEP 420`_ `native namespace packages`_ approach. + +Therefore, the source directory of any PyAnsys library must look like the one +exposed by figure :numref:`src structure diagram`: + +.. include:: diagrams/src_structure_diagram.rst + The ``tests/`` Directory ------------------------ @@ -125,6 +145,8 @@ The ``README.rst`` File .. REFERENCES & LINKS +.. _`PEP 420`: https://peps.python.org/pep-0420/ +.. _`native namespace packages`: https://packaging.python.org/en/latest/guides/packaging-namespace-packages/#native-namespace-packages .. _`PyAnsys`: https://docs.pyansys.com/ .. _`Python Packaging User Guide`: https://packaging.python.org/en/latest/ .. _`Python Packaging Authority`: https://www.pypa.io/en/latest/ From 5fb0a6b0e7fd8c5579208e7acfa8b451ea5a5ab4 Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Wed, 30 Mar 2022 10:24:38 +0200 Subject: [PATCH 10/37] Document tests/ dir structure --- .../diagrams/tests_structure_diagram.rst | 39 +++++++++++++++++++ doc/source/packaging/structure.rst | 13 +++++++ 2 files changed, 52 insertions(+) create mode 100644 doc/source/packaging/diagrams/tests_structure_diagram.rst diff --git a/doc/source/packaging/diagrams/tests_structure_diagram.rst b/doc/source/packaging/diagrams/tests_structure_diagram.rst new file mode 100644 index 000000000..72b4d13aa --- /dev/null +++ b/doc/source/packaging/diagrams/tests_structure_diagram.rst @@ -0,0 +1,39 @@ +.. _tests structure diagram: +.. graphviz:: + :caption: Minimum required PyAnsys project structure + :alt: Minimum required PyAnsys project structure + :align: center + + digraph "sphinx-ext-graphviz" { + size="8,6"; + rankdir="LR"; + graph [ + fontname="Verdana", fontsize="10", color="black", fillcolor="white" + ]; + node [ + fontname="Verdana", fontsize="10", style="filled", color="black", fillcolor="#ffc107" + ]; + + tests [ + label="tests", shape="folder" + ]; + + tests_package_A [ + label="tests_package_A", shape="folder" + ]; + + test_module_foo [ + label="test_module_foo.py", shape="file" + ] + + test_module_bar [ + label="test_module_bar.py", shape="file" + ] + + tests -> tests_package_A; + tests -> test_module_foo; + tests_package_A -> test_module_bar; + + } + + diff --git a/doc/source/packaging/structure.rst b/doc/source/packaging/structure.rst index f07faf5ab..94de2901d 100644 --- a/doc/source/packaging/structure.rst +++ b/doc/source/packaging/structure.rst @@ -131,6 +131,19 @@ exposed by figure :numref:`src structure diagram`: The ``tests/`` Directory ------------------------ +To guarantee the integrity of a PyAnsys project, a good test suite is required. +PyAnsys projects use the `pytest`_ testing framework. + +A good practice is to emulate the structure of the ``src/ansys/product/library`` +directory although it is not always necessary. + +.. include:: diagrams/tests_structure_diagram.rst + +Notice the usage of ``tests_*/`` when creating new directories inside the +``tests/`` one. On the other hand, unit testing files are named using the +``test_*.py`` prefix. This is the preferred way of naming directories and files +inside the ``tests/`` directory. + The ``LICENSE`` File -------------------- From 1c3e7116bbfc705021a95eda7fd0439e2d95f146 Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Wed, 30 Mar 2022 10:54:02 +0200 Subject: [PATCH 11/37] Document LICENSE file --- doc/source/conf.py | 2 +- .../pyproduct_library_structure_diagram.rst | 10 ++++++++ .../packaging/resources/license_mit.rst | 23 +++++++++++++++++++ doc/source/packaging/structure.rst | 14 +++++++++++ 4 files changed, 48 insertions(+), 1 deletion(-) create mode 100644 doc/source/packaging/resources/license_mit.rst diff --git a/doc/source/conf.py b/doc/source/conf.py index 9af1371c0..cc5d33057 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -96,4 +96,4 @@ # Do not include the following patterns as documentation source files. # See issue: https://github.com/sphinx-doc/sphinx/issues/1668 -exclude_patterns = ["packaging/diagrams/*"] +exclude_patterns = ["packaging/diagrams/*", "packaging/resources/*"] diff --git a/doc/source/packaging/diagrams/pyproduct_library_structure_diagram.rst b/doc/source/packaging/diagrams/pyproduct_library_structure_diagram.rst index 26fc13950..54ceae5d4 100644 --- a/doc/source/packaging/diagrams/pyproduct_library_structure_diagram.rst +++ b/doc/source/packaging/diagrams/pyproduct_library_structure_diagram.rst @@ -46,6 +46,14 @@ label="tests", shape="folder" ] + readme [ + label="README.rst", shape="file" + ] + + license [ + label="LICENSE", shape="file" + ] + pyproject [ label="pyproject.toml", shape="file" ] @@ -58,6 +66,8 @@ pyproduct_library -> doc; pyproduct_library -> src; pyproduct_library -> tests; + pyproduct_library -> license; + pyproduct_library -> readme; pyproduct_library -> pyproject; pyproduct_library -> setup; diff --git a/doc/source/packaging/resources/license_mit.rst b/doc/source/packaging/resources/license_mit.rst new file mode 100644 index 000000000..45a5e404b --- /dev/null +++ b/doc/source/packaging/resources/license_mit.rst @@ -0,0 +1,23 @@ +.. code:: text + + MIT License + + Copyright (c) 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. diff --git a/doc/source/packaging/structure.rst b/doc/source/packaging/structure.rst index 94de2901d..7b829adb0 100644 --- a/doc/source/packaging/structure.rst +++ b/doc/source/packaging/structure.rst @@ -148,6 +148,18 @@ inside the ``tests/`` directory. The ``LICENSE`` File -------------------- +The ``LICENSE`` file provides the legal framework for the software. The +recommended license for `PyAnsys`_ projects is `MIT License`_. A template for +this license is provided below: + +.. include:: resources/license_mit.rst + +.. note:: + + Just because a software does not ship with a LICENSE file, it does not mean + it is free or open source. If you require from using this software, contact + its development team so they can provide you with the right license. + The ``README.rst`` File ----------------------- @@ -158,9 +170,11 @@ The ``README.rst`` File .. REFERENCES & LINKS +.. _`MIT License`: https://opensource.org/licenses/MIT .. _`PEP 420`: https://peps.python.org/pep-0420/ .. _`native namespace packages`: https://packaging.python.org/en/latest/guides/packaging-namespace-packages/#native-namespace-packages .. _`PyAnsys`: https://docs.pyansys.com/ .. _`Python Packaging User Guide`: https://packaging.python.org/en/latest/ .. _`Python Packaging Authority`: https://www.pypa.io/en/latest/ +.. _`pytest`: https://docs.pytest.org/en/latest/ .. _`Sphinx`: https://www.sphinx-doc.org/en/master/ From 00050902ee3fb7f04ab7f61cd06f4be91349760e Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Wed, 30 Mar 2022 11:39:06 +0200 Subject: [PATCH 12/37] Improve doc/ directory explanations --- .../diagrams/src_structure_diagram.rst | 2 +- doc/source/packaging/structure.rst | 17 +++++++++++++---- 2 files changed, 14 insertions(+), 5 deletions(-) diff --git a/doc/source/packaging/diagrams/src_structure_diagram.rst b/doc/source/packaging/diagrams/src_structure_diagram.rst index a4bda878c..46254bb47 100644 --- a/doc/source/packaging/diagrams/src_structure_diagram.rst +++ b/doc/source/packaging/diagrams/src_structure_diagram.rst @@ -31,7 +31,7 @@ ] pkg_A [ - label="Package A", shape="folder" + label="package_A", shape="folder" ] init_file_pkgA [ diff --git a/doc/source/packaging/structure.rst b/doc/source/packaging/structure.rst index 7b829adb0..e8bb822a8 100644 --- a/doc/source/packaging/structure.rst +++ b/doc/source/packaging/structure.rst @@ -73,9 +73,17 @@ The ``doc/`` Directory When distributing software it is important to document it. Documenting software means giving guidelines on how to install and use it but also which functions, -methods and/or classes does it ship with. Examples can also be considered -documentation. The purpose of the ``doc/`` directory is to store all -documentation related files. +methods and/or classes does it ship with. Case scenarios and examples are also +be considered documentation. + +It is recommended to have the following sections in a PyAnsys project +documentation: + +- ``Getting Started`` section explains requirements and installation details. +- ``User Guide`` section explains how to use the software. +- ``API Reference`` section contains source code documentation. +- ``Examples`` section case scenarios demonstrating the capabilities of the software. +- ``Contributing`` section can be linked to generic PyAnsys contributing guidelines. Projects in the PyAnsys ecosystem take advantage of `Sphinx`_, a tool used for building documentation for Python-based projects. A ``doc/`` directory making @@ -98,7 +106,8 @@ use of `Sphinx`_ requires the following structure, as shown by figure The ``source/`` directory needs to contain at least the following files: - ``conf.py`` is a Python script used to declare the configuration of `Sphinx`_. -- ``index.rst`` is the index page of the documentation. +- ``index.rst`` is the index page of the documentation. Try to reuse the + ``README.rst`` file in here to avoid duplication. In case you would like to include images or documents, it is recommended to add those in the ``_static/`` directory. From bbc59283ac60fda4796f75d61f43a1299cf0aa71 Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Wed, 30 Mar 2022 12:17:41 +0200 Subject: [PATCH 13/37] Document Naming Convention section --- .../diagrams/ansys_project_diagram.rst | 34 --------- .../diagrams/grpc_structure_diagram.rst | 55 ++++++++++++++ .../diagrams/pyansys_namespace_diagram.rst | 49 ++++++++++++ doc/source/packaging/structure.rst | 74 ++++++++++++++++--- 4 files changed, 167 insertions(+), 45 deletions(-) delete mode 100644 doc/source/packaging/diagrams/ansys_project_diagram.rst create mode 100644 doc/source/packaging/diagrams/grpc_structure_diagram.rst create mode 100644 doc/source/packaging/diagrams/pyansys_namespace_diagram.rst diff --git a/doc/source/packaging/diagrams/ansys_project_diagram.rst b/doc/source/packaging/diagrams/ansys_project_diagram.rst deleted file mode 100644 index 70607b578..000000000 --- a/doc/source/packaging/diagrams/ansys_project_diagram.rst +++ /dev/null @@ -1,34 +0,0 @@ -.. _high level pyansys structure: -.. graphviz:: - :caption: A PyAnsys project is composed by a Python library and other files. - :alt: High-level structure of a PyAnsys project - :align: center - - digraph "sphinx-ext-graphviz" { - size="6,4"; - rankdir="LR"; - graph [ - fontname="Verdana", fontsize="10", color="black", fillcolor="white" - ]; - node [ - fontname="Verdana", fontsize="10", style="filled", color="black", fillcolor="#ffc107" - ]; - - pyansys_project [ - label="PyAnsys Project", shape="folder" - ]; - - python_library [ - label="Python Library", shape="folder" - ]; - - other_files [ - label="Other Files", shape="node" - ]; - - pyansys_project -> python_library; - pyansys_project -> other_files; - - } - - diff --git a/doc/source/packaging/diagrams/grpc_structure_diagram.rst b/doc/source/packaging/diagrams/grpc_structure_diagram.rst new file mode 100644 index 000000000..6f952bc30 --- /dev/null +++ b/doc/source/packaging/diagrams/grpc_structure_diagram.rst @@ -0,0 +1,55 @@ +.. _grpc structure diagram: +.. graphviz:: + :caption: Namespace convention for gRPC interface packages + :alt: Namespace convention for gRPC interface packages + :align: center + + digraph "sphinx-ext-graphviz" { + size="8,6"; + rankdir="LR"; + graph [ + fontname="Verdana", fontsize="10", color="black", fillcolor="white" + ]; + node [ + fontname="Verdana", fontsize="10", style="filled", color="black", fillcolor="#ffc107" + ]; + + ansys_api_product [ + label="ansys-api-product", shape="folder" + ]; + + ansys [ + label="ansys", shape="folder" + ]; + + api [ + label="api", shape="folder" + ]; + + product [ + label="product", shape="folder" + ]; + + version [ + label="VERSION", shape="file" + ]; + + v0 [ + label="v0", shape="folder" + ]; + + proto_files [ + label="\*.proto", shape="file" + ]; + + + ansys_api_product -> ansys; + ansys -> api; + api -> product; + product -> version; + product -> v0; + v0 -> proto_files; + + } + + diff --git a/doc/source/packaging/diagrams/pyansys_namespace_diagram.rst b/doc/source/packaging/diagrams/pyansys_namespace_diagram.rst new file mode 100644 index 000000000..6b7bbe09d --- /dev/null +++ b/doc/source/packaging/diagrams/pyansys_namespace_diagram.rst @@ -0,0 +1,49 @@ +.. _pyansys_namespace_diagram: +.. graphviz:: + :caption: Namespace convention for PyAnsys projects + :alt: Namespace convention for PyAnsys projects + :align: center + + digraph "sphinx-ext-graphviz" { + size="8,6"; + rankdir="LR"; + graph [ + fontname="Verdana", fontsize="10", color="black", fillcolor="white" + ]; + node [ + fontname="Verdana", fontsize="10", style="filled", color="black", fillcolor="#ffc107" + ]; + + pyproduct_library [ + label="pyproduct-library", shape="folder" + ]; + + src [ + label="src", shape="folder" + ] + + ansys [ + label="ansys", shape="folder" + ] + + product [ + label="product", shape="folder" + ] + + library [ + label="library", shape="folder" + ] + + init_file [ + label="__init__.py", shape="file" + ] + + pyproduct_library -> src; + src -> ansys; + ansys -> product; + product -> library; + library -> init_file; + + } + + diff --git a/doc/source/packaging/structure.rst b/doc/source/packaging/structure.rst index e8bb822a8..1515bcda1 100644 --- a/doc/source/packaging/structure.rst +++ b/doc/source/packaging/structure.rst @@ -7,10 +7,58 @@ Project Structure Most of the projects in the PyAnsys ecosystem ship in the form of a Python library with other additional files. All these files form what it is called a "project". A project can be uploaded to a repository to better track the changes -applied to it. The high-level structure of a PyAnsys project is exposed in -figure :numref:`high level pyansys structure`. +applied to it. + + +Naming Convention +================= + +Large organizations providing Python packages follow a consistent naming +pattern. Ansys follows two naming conventions, depending on the nature of the project. + +PyAnsys Library +--------------- + +- The project name is to be ``Py``. For example, ``PyMAPDL`` is the + project name for MAPDL and ``PyAEDT`` is the project name for AEDT. + +- The repository name as hosted on GitHub should be all lowercase to follow + GitHub community standards. For example, `pymapdl`_ and `pyaedt`_. + +- The Python library name is to be in the format + ``ansys--``. For example, `ansys-mapdl-core + `_ is the name for the core MAPDL + library. + +.. include:: diagrams/pyansys_namespace_diagram.rst + +Previous structure leads to the following namespace when executing the import +statement: + +.. code:: python + + import ansys.product import library + +Using long Python library names provides two primary advantages: + +- `Namespace Packages`_ can be used to designate official Ansys packages +- Consistent branding and style can be applied to PyAnsys libraries + + +gRPC Interface Package +---------------------- +Lower level gRPC interface packages like `ansys-api-mapdl`_ should always be +named ``ansys-api-`` or may contain an additional level with +``ansys-api--``. + +.. include:: diagrams/grpc_structure_diagram.rst + +Previous structure leas to the following namespace within the ``*.proto`` files: + +.. code:: + + package ansys.api..v0; -.. include:: diagrams/ansys_project_diagram.rst Python Libraries ================ @@ -179,11 +227,15 @@ The ``README.rst`` File .. REFERENCES & LINKS -.. _`MIT License`: https://opensource.org/licenses/MIT -.. _`PEP 420`: https://peps.python.org/pep-0420/ -.. _`native namespace packages`: https://packaging.python.org/en/latest/guides/packaging-namespace-packages/#native-namespace-packages -.. _`PyAnsys`: https://docs.pyansys.com/ -.. _`Python Packaging User Guide`: https://packaging.python.org/en/latest/ -.. _`Python Packaging Authority`: https://www.pypa.io/en/latest/ -.. _`pytest`: https://docs.pytest.org/en/latest/ -.. _`Sphinx`: https://www.sphinx-doc.org/en/master/ +.. _MIT License: https://opensource.org/licenses/MIT +.. _PEP 420: https://peps.python.org/pep-0420/ +.. _native namespace packages: https://packaging.python.org/en/latest/guides/packaging-namespace-packages/#native-namespace-packages +.. _Namespace Packages: https://packaging.python.org/guides/packaging-namespace-packages/ +.. _PyAnsys: https://docs.pyansys.com/ +.. _Python Packaging User Guide: https://packaging.python.org/en/latest/ +.. _Python Packaging Authority: https://www.pypa.io/en/latest/ +.. _pytest: https://docs.pytest.org/en/latest/ +.. _Sphinx: https://www.sphinx-doc.org/en/master/ +.. _PyMAPDL: https://github.com/pyansys/pymapdl +.. _PyAEDT: https://github.com/pyansys/PyAEDT +.. _ansys-api-mapdl: https://pypi.org/project/ansys-api-mapdl/ From 7fdbc90a81c9316d3079bf956b4316c277b31287 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jorge=20Mart=C3=ADnez?= <28702884+jorgepiloto@users.noreply.github.com> Date: Thu, 31 Mar 2022 09:56:06 +0200 Subject: [PATCH 14/37] Apply suggestions from code review Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> --- doc/source/packaging/structure.rst | 33 +++++++++++++++--------------- 1 file changed, 16 insertions(+), 17 deletions(-) diff --git a/doc/source/packaging/structure.rst b/doc/source/packaging/structure.rst index 1515bcda1..5afbee5bb 100644 --- a/doc/source/packaging/structure.rst +++ b/doc/source/packaging/structure.rst @@ -32,7 +32,7 @@ PyAnsys Library .. include:: diagrams/pyansys_namespace_diagram.rst -Previous structure leads to the following namespace when executing the import +The previous structure leads to the following namespace when executing the import statement: .. code:: python @@ -47,13 +47,13 @@ Using long Python library names provides two primary advantages: gRPC Interface Package ---------------------- -Lower level gRPC interface packages like `ansys-api-mapdl`_ should always be -named ``ansys-api-`` or may contain an additional level with +Lower-level gRPC interface packages like `ansys-api-mapdl`_ should always be +named ``ansys-api-`` and may contain an additional level: ``ansys-api--``. .. include:: diagrams/grpc_structure_diagram.rst -Previous structure leas to the following namespace within the ``*.proto`` files: +The previous structure leads to the following namespace within the ``*.proto`` files: .. code:: @@ -120,18 +120,17 @@ The ``doc/`` Directory ---------------------- When distributing software it is important to document it. Documenting software -means giving guidelines on how to install and use it but also which functions, -methods and/or classes does it ship with. Case scenarios and examples are also -be considered documentation. +means giving guidelines on how to install and describing all functions, +methods, and classes that it ships with. Case scenarios and examples should also +be part of the documentation. -It is recommended to have the following sections in a PyAnsys project -documentation: +A PyAnsys project should have the following documentation sections: -- ``Getting Started`` section explains requirements and installation details. -- ``User Guide`` section explains how to use the software. -- ``API Reference`` section contains source code documentation. -- ``Examples`` section case scenarios demonstrating the capabilities of the software. -- ``Contributing`` section can be linked to generic PyAnsys contributing guidelines. +- ``Getting Started``: Defines requirements and provides installation information +- ``User Guide``: Explains how to use the software +- ``API Reference``: Describes the source code +- ``Examples``: Provides use case scenarios that demonstrate the capabilities of the software +- ``Contributing``: Supplies project-specific contribution guides and can link to general PyAnsys contribution guidelines Projects in the PyAnsys ecosystem take advantage of `Sphinx`_, a tool used for building documentation for Python-based projects. A ``doc/`` directory making @@ -151,11 +150,11 @@ use of `Sphinx`_ requires the following structure, as shown by figure commands. The ``make.bat`` is intended to be used by Windows users while ``Makefile`` is devised for MacOS/Linux ones. -The ``source/`` directory needs to contain at least the following files: +The ``source/`` directory must contain at least these files: - ``conf.py`` is a Python script used to declare the configuration of `Sphinx`_. -- ``index.rst`` is the index page of the documentation. Try to reuse the - ``README.rst`` file in here to avoid duplication. +- ``index.rst`` is the index page of the documentation. In this file, try to reuse the + ``README.rst`` file to avoid duplication. In case you would like to include images or documents, it is recommended to add those in the ``_static/`` directory. From 8a85c7bb37e6a741a0c40be4f04c260b71f7ac63 Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Thu, 31 Mar 2022 10:10:08 +0200 Subject: [PATCH 15/37] Document README.rst section --- doc/source/packaging/structure.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/doc/source/packaging/structure.rst b/doc/source/packaging/structure.rst index 5afbee5bb..f2dad640b 100644 --- a/doc/source/packaging/structure.rst +++ b/doc/source/packaging/structure.rst @@ -220,8 +220,24 @@ this license is provided below: The ``README.rst`` File ----------------------- +Each PyAnsys library should have a ``README.rst`` file in the root directory. +The preferred format of this file is `reStructuredText Markup Syntax`_ or a +although `Markdown Syntax`_ can be used too. While Markdown syntax has better +GitHub support, text in RST files can be reused within Sphinx documentation. +This avoids duplication between the ``README.rst`` and the main ``index.rst`` in +the ``doc/source/`` directory. +The ``README.rst`` file should at the minimum contain these elements: + +- PyAnsys library title +- General description +- Installation directions (via ``pip install`` and ``git clone``) +- Basic usage +- Links to the full documentation + +The ``README.rst`` file is also reused within the project file metadata. It is +usually included in the ``long-description`` field. .. REFERENCES & LINKS @@ -238,3 +254,5 @@ The ``README.rst`` File .. _PyMAPDL: https://github.com/pyansys/pymapdl .. _PyAEDT: https://github.com/pyansys/PyAEDT .. _ansys-api-mapdl: https://pypi.org/project/ansys-api-mapdl/ +.. _reStructuredText Markup Syntax: https://docutils.sourceforge.io/rst.html +.. _Markdown Syntax: https://www.markdownguide.org/basic-syntax/ From a59965fbc39fe0d3b5cf063175cc66b94743cf96 Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Thu, 31 Mar 2022 12:02:03 +0200 Subject: [PATCH 16/37] Document pyproject.toml and setup.py sections --- doc/source/conf.py | 1 + .../resources/setup_file_template.rst | 28 +++++++ doc/source/packaging/structure.rst | 74 +++++++++++++++++++ 3 files changed, 103 insertions(+) create mode 100644 doc/source/packaging/resources/setup_file_template.rst diff --git a/doc/source/conf.py b/doc/source/conf.py index cc5d33057..a0fa6470e 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -35,6 +35,7 @@ "sphinx.ext.intersphinx", "sphinx.ext.napoleon", "sphinx.ext.todo", + "sphinx_tabs.tabs", ] # Intersphinx mapping diff --git a/doc/source/packaging/resources/setup_file_template.rst b/doc/source/packaging/resources/setup_file_template.rst new file mode 100644 index 000000000..3fce14eb2 --- /dev/null +++ b/doc/source/packaging/resources/setup_file_template.rst @@ -0,0 +1,28 @@ +.. code:: python + + """Installation file for ansys-mapdl-core.""" + + from setuptools import find_namespace_packages, setup + + setup( + name="ansys--", + packages=find_namespace_packages(where="src", include="ansys*"), + package_dir={"": "src"}, + version="", + description="", + long_description=open("README.rst").read(), + license="MIT", + author="ANSYS, Inc.", + author_email="pyansys.support@ansys.com", + maintainer="PyAnsys developers", + maintainer_email="pyansys.maintainers@ansys.com", + classifiers=[ + "Development Status :: 4 - Beta", + "Programming Language :: Python :: 3", + "License :: OSI Approved :: MIT License", + "Operating System :: OS Independent", + ], + url="-", + python_requires=">=3.", + install_requires=["importlib-metadata >=4.0"], + ) diff --git a/doc/source/packaging/structure.rst b/doc/source/packaging/structure.rst index f2dad640b..781e25b1c 100644 --- a/doc/source/packaging/structure.rst +++ b/doc/source/packaging/structure.rst @@ -240,6 +240,77 @@ The ``README.rst`` file is also reused within the project file metadata. It is usually included in the ``long-description`` field. +The ``pyproject.toml`` File +--------------------------- + +The `PEP 518`_ introduced the usage of a new project file called +``pyproject.toml``. More information about this file can be found in the +REF-TO-BUILD-SYSTEMS-TOML section. + +This file is mandatory as it allows ``pip`` to resolve the requirements for +building the library. The following tabs expose the ``[build-system]`` section +for some of the most popular build tools in the Python ecosystem: + + +.. tabs:: + + .. tab:: setuptools + + .. code:: toml + + [build-system] + requires = ["setuptools", "wheel"] + + .. tab:: flit + + .. code:: toml + + # Refer to https://dev.docs.pyansys.com/packaging/build-systems#flit + [build-system] + requires = ["flit_core>=3.2,<4"] + build-backend = "flit_core.buildapi" + + + .. tab:: poetry + + .. code:: toml + + # Refer to https://dev.docs.pyansys.com/packaging/build-systems#poetry + [build-system] + requires = ["poetry"] + build-backend = "poetry.masonry.api" + + +The ``setup.py`` File +--------------------- + +For a long time, the ``setup.py`` has been the usual way of building and +distributing Python libraries. As opposite to the static ``pyproject.toml`` +file, ``setup.py`` is Python script. This means that Python code is interpreted +when building the library. This allows to customize the building process but +also may introduced security issues. + +.. tip:: + + Consider using a ``pyproject.toml`` file instead of a ``setup.py`` when + possible. + + +The ``setup.py`` file is only compatible with `Setuptools`_. A ``setup.cfg`` can +also be used for specifying the metadata and packages, but the ``setup.py`` file +must be present too. More information about its usage can be found in the +following links: + +* `Building and Distributing Packages with Setuptools`_ +* `Configuring setuptools using setup.cfg files`_ + +As a minimum configuration for PyAnsys projects, the following ``setup.py`` +template can be used: + + +.. include:: resources/setup_file_template.rst + + .. REFERENCES & LINKS .. _MIT License: https://opensource.org/licenses/MIT @@ -256,3 +327,6 @@ usually included in the ``long-description`` field. .. _ansys-api-mapdl: https://pypi.org/project/ansys-api-mapdl/ .. _reStructuredText Markup Syntax: https://docutils.sourceforge.io/rst.html .. _Markdown Syntax: https://www.markdownguide.org/basic-syntax/ +.. _PEP 518: https://peps.python.org/pep-0518/ +.. _Building and Distributing Packages with Setuptools: https://setuptools.pypa.io/en/latest/setuptools.html +.. _Configuring setuptools using setup.cfg files: https://setuptools.pypa.io/en/latest/userguide/declarative_config.html From a79e4e0d95b92bf4924dd3d1316f51cf662b21c0 Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Thu, 31 Mar 2022 12:02:24 +0200 Subject: [PATCH 17/37] Add build-systems.rst section --- doc/source/packaging/build-systems.rst | 28 ++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 doc/source/packaging/build-systems.rst diff --git a/doc/source/packaging/build-systems.rst b/doc/source/packaging/build-systems.rst new file mode 100644 index 000000000..ae9f3d8d7 --- /dev/null +++ b/doc/source/packaging/build-systems.rst @@ -0,0 +1,28 @@ +.. _ref_build_systems: + +Build-systems +############# + + +The PEP 517 and PEP 518 +======================= + + +PEP 517 +------- + + +PEP 518 +------- + + +Setuptools +========== + + +Flit +==== + + +Poetry +====== From 036fcf219d3eebcb57648a5433f0b13cc38e82db Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Thu, 31 Mar 2022 12:15:39 +0200 Subject: [PATCH 18/37] Add sphinx-tabs requiremnt --- requirements_docs.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/requirements_docs.txt b/requirements_docs.txt index 2506bf211..dae64ebf6 100644 --- a/requirements_docs.txt +++ b/requirements_docs.txt @@ -2,3 +2,4 @@ Sphinx==4.5.0 pyansys-sphinx-theme==0.2.3 sphinx-copybutton==0.5.0 sphinx_toolbox==2.18.0 +sphinx-tabs>=3.3.1 From a8fda149eb1dc53a0582a5eec446f6ec8cace8d5 Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Thu, 31 Mar 2022 13:02:01 +0200 Subject: [PATCH 19/37] Fix setuptools link --- doc/source/packaging/structure.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/source/packaging/structure.rst b/doc/source/packaging/structure.rst index 781e25b1c..e15703a86 100644 --- a/doc/source/packaging/structure.rst +++ b/doc/source/packaging/structure.rst @@ -330,3 +330,4 @@ template can be used: .. _PEP 518: https://peps.python.org/pep-0518/ .. _Building and Distributing Packages with Setuptools: https://setuptools.pypa.io/en/latest/setuptools.html .. _Configuring setuptools using setup.cfg files: https://setuptools.pypa.io/en/latest/userguide/declarative_config.html +.. _setuptools: https://setuptools.pypa.io/en/latest/index.html From af98b56c85597ae4c6aaf080e909e40b5f361001 Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Fri, 1 Apr 2022 08:20:07 +0200 Subject: [PATCH 20/37] Apply code suggestions --- doc/source/packaging/structure.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/packaging/structure.rst b/doc/source/packaging/structure.rst index e15703a86..750d8f7f5 100644 --- a/doc/source/packaging/structure.rst +++ b/doc/source/packaging/structure.rst @@ -156,8 +156,8 @@ The ``source/`` directory must contain at least these files: - ``index.rst`` is the index page of the documentation. In this file, try to reuse the ``README.rst`` file to avoid duplication. -In case you would like to include images or documents, it is recommended to add -those in the ``_static/`` directory. +If you would like to include images or documents, add them in the ``_static/`` +directory. The ``src/`` Directory From 2200a583e7357df9a9dc530d66144fec2a8d6cdc Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Fri, 1 Apr 2022 13:15:23 +0200 Subject: [PATCH 21/37] Add build-systems.rst diagrams --- doc/source/conf.py | 1 + doc/source/packaging/build-systems.rst | 27 +++++++-- .../diagrams/build_system_diagram.rst | 59 +++++++++++++++++++ .../diagrams/grpc_structure_diagram.rst | 2 +- .../pyproduct_library_structure_diagram.rst | 2 +- doc/source/packaging/index.rst | 1 + requirements_docs.txt | 1 + 7 files changed, 86 insertions(+), 7 deletions(-) create mode 100644 doc/source/packaging/diagrams/build_system_diagram.rst diff --git a/doc/source/conf.py b/doc/source/conf.py index a0fa6470e..42ca23a93 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -35,6 +35,7 @@ "sphinx.ext.intersphinx", "sphinx.ext.napoleon", "sphinx.ext.todo", + "sphinxcontrib.mermaid", "sphinx_tabs.tabs", ] diff --git a/doc/source/packaging/build-systems.rst b/doc/source/packaging/build-systems.rst index ae9f3d8d7..a4b192cea 100644 --- a/doc/source/packaging/build-systems.rst +++ b/doc/source/packaging/build-systems.rst @@ -1,7 +1,19 @@ -.. _ref_build_systems: +.. _ref_build_system: -Build-systems ############# +Build-system +############# + +This chapter explains in deep what the build-system is and which build-backend +tools are available in the Python ecosystem. + + +The build-system +================ + +AAA + +.. include:: diagrams/build_system_diagram.rst The PEP 517 and PEP 518 @@ -15,14 +27,19 @@ PEP 517 PEP 518 ------- +Build-backend Tools +=================== + +Distutils +--------- Setuptools -========== +---------- Flit -==== +---- Poetry -====== +------ diff --git a/doc/source/packaging/diagrams/build_system_diagram.rst b/doc/source/packaging/diagrams/build_system_diagram.rst new file mode 100644 index 000000000..b9a1087c9 --- /dev/null +++ b/doc/source/packaging/diagrams/build_system_diagram.rst @@ -0,0 +1,59 @@ +.. mermaid:: + :align: center + + flowchart LR + + maintainers[Maintainers] + + subgraph build_system[Build System] + direction LR + + subgraph frontend[Frontend] + direction LR + setuptools + flit + poetry + end + + subgraph backend[Backend] + direction LR + setuptools.build_back + flit_core.api + poetry.masonry.api + end + + subgraph project[PyAnsys Project] + direction LR + sourcefiles[src/ tests/ doc/ ] + metadata[LICENSE README.rst] + pyproject.toml + end + + end + + subgraph artifacts[Artifacts] + direction LR + *.whl + *.tar.gz + end + + %% Link definitions + maintainers-- Trigger -->build_system + frontend-- Calls -->backend + project-- Read by -->backend + build_system-- Generates -->artifacts + *.whl --- *.tar.gz + + %% Define style for nodes and subgraphs + classDef NodeStyle stroke:black,color:black,fill:white,stroke-width:2px,font-size:12pt; + classDef SubgraphStyle stroke:black,color:black,fill:white,stroke-width:2px,font-size:14pt,font-weight:bold; + + %% Asign style to elements + class maintainers,setuptools,flit,poetry,setuptools.build_back,flit_core.api,poetry.masonry.api,pyproject.toml,metadata,sourcefiles,*.whl,*.tar.gz NodeStyle; + class build_system,frontend,backend,project,artifacts SubgraphStyle; + + %% HACK: add some space between subgraph header and its nodes + linkStyle 1 fill:none,color:black,stroke:black; + linkStyle 2 fill:none,color:black,stroke:black; + linkStyle 3 fill:none,color:black,stroke:black; + linkStyle 4 fill:none,color:white,stroke:white; diff --git a/doc/source/packaging/diagrams/grpc_structure_diagram.rst b/doc/source/packaging/diagrams/grpc_structure_diagram.rst index 6f952bc30..e3457f853 100644 --- a/doc/source/packaging/diagrams/grpc_structure_diagram.rst +++ b/doc/source/packaging/diagrams/grpc_structure_diagram.rst @@ -8,7 +8,7 @@ size="8,6"; rankdir="LR"; graph [ - fontname="Verdana", fontsize="10", color="black", fillcolor="white" + fontname="Verdana", fontsize="10", color="black", fillcolor="white",splines=ortho ]; node [ fontname="Verdana", fontsize="10", style="filled", color="black", fillcolor="#ffc107" diff --git a/doc/source/packaging/diagrams/pyproduct_library_structure_diagram.rst b/doc/source/packaging/diagrams/pyproduct_library_structure_diagram.rst index 54ceae5d4..e4a61be20 100644 --- a/doc/source/packaging/diagrams/pyproduct_library_structure_diagram.rst +++ b/doc/source/packaging/diagrams/pyproduct_library_structure_diagram.rst @@ -8,7 +8,7 @@ size="8,6"; rankdir="LR"; graph [ - fontname="Verdana", fontsize="10", color="black", fillcolor="white" + fontname="Verdana", fontsize="10", color="black", fillcolor="white", splines=ortho ]; node [ fontname="Verdana", fontsize="10", style="filled", color="black", fillcolor="#ffc107" diff --git a/doc/source/packaging/index.rst b/doc/source/packaging/index.rst index e83b6f8d1..7d699c97e 100644 --- a/doc/source/packaging/index.rst +++ b/doc/source/packaging/index.rst @@ -42,6 +42,7 @@ model and API. templates structure + build-systems .. _gRPC: https://grpc.io/ .. _pythoncom: http://timgolden.me.uk/pywin32-docs/pythoncom.html diff --git a/requirements_docs.txt b/requirements_docs.txt index dae64ebf6..0b623af83 100644 --- a/requirements_docs.txt +++ b/requirements_docs.txt @@ -3,3 +3,4 @@ pyansys-sphinx-theme==0.2.3 sphinx-copybutton==0.5.0 sphinx_toolbox==2.18.0 sphinx-tabs>=3.3.1 +sphinxcontrib-mermaid>=0.7.1 From 3cb9fb3c7c10eeb096205614fa47f73b2d7d31ce Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Fri, 1 Apr 2022 16:51:11 +0200 Subject: [PATCH 22/37] Add build system section --- doc/source/conf.py | 5 + doc/source/packaging/build-systems.rst | 146 ++++++++++++++++-- .../diagrams/build_system_diagram.rst | 3 + 3 files changed, 145 insertions(+), 9 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 42ca23a93..a4e5b653d 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -99,3 +99,8 @@ # Do not include the following patterns as documentation source files. # See issue: https://github.com/sphinx-doc/sphinx/issues/1668 exclude_patterns = ["packaging/diagrams/*", "packaging/resources/*"] + +# 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'] diff --git a/doc/source/packaging/build-systems.rst b/doc/source/packaging/build-systems.rst index a4b192cea..e9c9d1eec 100644 --- a/doc/source/packaging/build-systems.rst +++ b/doc/source/packaging/build-systems.rst @@ -1,17 +1,37 @@ .. _ref_build_system: -############# -Build-system -############# +############ +Build System +############ -This chapter explains in deep what the build-system is and which build-backend -tools are available in the Python ecosystem. +The build system is a fundamental tool when it comes to packaging Python +libraries. It allows to generate distribution files which can be shared with +users and developers. -The build-system +The Build System ================ -AAA +The build-system allows maintainers to generate artifacts for their Python +libraries. The word 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 be uploaded 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 interation between the maintainer and the build-system is performed using a +build-system tool. This tool provides a frontend and a backend. The maintainers +trigger the frontend which then calls the backend. Then the backend reads the +project directory and generates the artifacts, as :numref:`build system diagram`: .. include:: diagrams/build_system_diagram.rst @@ -19,27 +39,135 @@ AAA The 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 to be followed by `pip`_. +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`_. + +Previous reasons lead to the acceptance of the `PEP 517`_ and `PEP 518`_. + PEP 517 ------- +The `PEP 517` allowed Python developers to specify the build-backend tool to +generate the artifacts. As seen in :numref:`build system diagram` figure, the +most popular backends are provided by: + +- `Setuptools`_ very popular but lacks from build time dependency declaration + and it is difficult to extend. +- `Flit`_ is a lightweight build system tool for Python. +- `Poetry`_ focuses on dependency management and environment isolation. + +The `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, a new project file named +``pyproject.toml`` file was specified by the `PEP 518`_. The main goal of this +file was to specify build time dependencies. However, some build system tools +like `flit`_ or `poetry`_ are able to specify all the project metadata inside +the ``pyproject.toml`` file and eliminate the usage of the ``setup.py``. + +To specify the build time requirements, the ``[build-system]`` table needs to be +declared in the ``pyproject.toml`` file. Within it, the ``requires`` key is +assigned to a list of strings, each one of those being the build time +requirements. + +The combination of `PEP 517`_ and `PEP 518`_ leads to the following syntax in te +``pyproject.toml`` files: + +.. code:: toml + + [build-system] + requires = ["flit"] # Defined by PEP 518 + build-backend = "flit_core.api" # Defined by PEP 517 + + Build-backend Tools =================== -Distutils ---------- +This section collects some of the most popular build systems available 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 around for a long time in the Python ecosystem. Unless +you require from a high control over the installation steps of your project, +`flit`_ and `poetry`_ should be used. + +If you do not need from a dynamic installation process, you may consider using a +``setup.cfg`` file. However, the ``setup.py`` is still required. This file +should have a call to the ``setup()`` function to act as the entry point of the +build backend system. + +All the following `setuptools metadata fields`_ are valid ones. These need to be +specified either in the ``setup.py`` or ``setup.cfg``. + 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 by running: + +.. 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 the project's +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 diff --git a/doc/source/packaging/diagrams/build_system_diagram.rst b/doc/source/packaging/diagrams/build_system_diagram.rst index b9a1087c9..22bd9694c 100644 --- a/doc/source/packaging/diagrams/build_system_diagram.rst +++ b/doc/source/packaging/diagrams/build_system_diagram.rst @@ -1,4 +1,7 @@ +.. _build system diagram: .. mermaid:: + :caption: Maintainers use the build system to create artifacts + :alt: Maintainers use the build system to create artifacts :align: center flowchart LR From 4ce03e614449c5b2abe872fee147f34d609553f2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jorge=20Mart=C3=ADnez?= <28702884+jorgepiloto@users.noreply.github.com> Date: Fri, 1 Apr 2022 18:48:04 +0200 Subject: [PATCH 23/37] Apply suggestions from code review Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> --- doc/source/packaging/build-systems.rst | 60 +++++++++++++------------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/doc/source/packaging/build-systems.rst b/doc/source/packaging/build-systems.rst index e9c9d1eec..4f716743a 100644 --- a/doc/source/packaging/build-systems.rst +++ b/doc/source/packaging/build-systems.rst @@ -4,21 +4,21 @@ Build System ############ -The build system is a fundamental tool when it comes to packaging Python -libraries. It allows to generate distribution files which can be shared with +The build system is a fundamental tool for packaging Python +libraries. It generates distribution files that can be shared with users and developers. -The Build System +Artifacts ================ The build-system allows maintainers to generate artifacts for their Python -libraries. The word artifacts refers to both wheel and source files: +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 be uploaded to `PyPI`_ when releasing a new version of a +These are the files to upload to `PyPI`_ when releasing a new version of a PyAnsys project. .. warning:: @@ -30,17 +30,17 @@ PyAnsys project. The interation between the maintainer and the build-system is performed using a build-system tool. This tool provides a frontend and a backend. The maintainers -trigger the frontend which then calls the backend. Then the backend reads the +trigger the frontend, which then calls the backend. The backend then reads the project directory and generates the artifacts, as :numref:`build system diagram`: .. include:: diagrams/build_system_diagram.rst -The PEP 517 and PEP 518 -======================= +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 to be followed by `pip`_. +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: @@ -50,22 +50,22 @@ introduced the following problems: - The default Python package installer, `pip`_, expected `setuptools`_ to be the default build system tool, excluding others like `flit`_ and `poetry`_. -Previous reasons lead to the acceptance of the `PEP 517`_ and `PEP 518`_. +These problems led to the acceptance of `PEP 517`_ and `PEP 518`_. PEP 517 ------- -The `PEP 517` allowed Python developers to specify the build-backend tool to -generate the artifacts. As seen in :numref:`build system diagram` figure, the -most popular backends are provided by: +`PEP 517` allows Python developers to specify the build-backend tool for +generating artifacts. As seen in the :numref:`build system diagram` figure, these +are the most popular backends: -- `Setuptools`_ very popular but lacks from build time dependency declaration - and it is difficult to extend. +- `Setuptools`_ , while very popular, lacks build time dependency declaration + and is difficult to extend. - `Flit`_ is a lightweight build system tool for Python. - `Poetry`_ focuses on dependency management and environment isolation. -The `PEP 517` introduced the ``build-backend`` key inside the +`PEP 517` introduced the ``build-backend`` key inside the ``[build-system]`` table in the ``pyproject.toml``. @@ -78,13 +78,13 @@ file was to specify build time dependencies. However, some build system tools like `flit`_ or `poetry`_ are able to specify all the project metadata inside the ``pyproject.toml`` file and eliminate the usage of the ``setup.py``. -To specify the build time requirements, the ``[build-system]`` table needs to be +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, each one of those being the build time +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 te -``pyproject.toml`` files: +The combination of `PEP 517`_ and `PEP 518`_ leads to the following syntax in a +``pyproject.toml`` file: .. code:: toml @@ -96,7 +96,7 @@ The combination of `PEP 517`_ and `PEP 518`_ leads to the following syntax in te Build-backend Tools =================== -This section collects some of the most popular build systems available in the +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. @@ -106,17 +106,17 @@ metadata. Setuptools ---------- -`Setuptools`_ has been around for a long time in the Python ecosystem. Unless -you require from a high control over the installation steps of your project, -`flit`_ and `poetry`_ should be used. +`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 from a dynamic installation process, you may consider using a -``setup.cfg`` file. However, the ``setup.py`` is still required. This file +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 the following `setuptools metadata fields`_ are valid ones. These need to be -specified either in the ``setup.py`` or ``setup.cfg``. +All of these `setuptools metadata fields`_ are valid and must be +specified either in the ``setup.py`` or ``setup.cfg`` file. Flit @@ -143,7 +143,7 @@ Because of its ``poetry.lock`` file, Poetry provides strong dependency pinning. 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 by running: +Nevertheless, it is possible to make Poetry ignore the ``poetry.lock`` file with: .. code:: bash @@ -156,7 +156,7 @@ Using `poetry`_ is popular because it: * 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 the project's +The ``[tool.poetry]`` section contains metadata and defines project dependencies. For more information, see `poetry pyproject.toml documentation`_. From ce83137998b329d1c2cc1e45d47a0db1fe87f05b Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Fri, 1 Apr 2022 18:38:42 +0200 Subject: [PATCH 24/37] Enable Sphinx autolabeling --- doc/source/conf.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/source/conf.py b/doc/source/conf.py index a4e5b653d..5caaf9972 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -30,6 +30,7 @@ "sphinx_copybutton", "sphinx_toolbox.collapse", "sphinx.ext.autodoc", + "sphinx.ext.autosectionlabel", "sphinx.ext.autosummary", "sphinx.ext.graphviz", "sphinx.ext.intersphinx", @@ -104,3 +105,6 @@ # 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 From 340d1442a4d06563de896d3f556af79a4bd9b0b6 Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Fri, 1 Apr 2022 18:39:57 +0200 Subject: [PATCH 25/37] Fix cross references --- doc/source/overview/administration.rst | 4 ++-- doc/source/overview/contributing.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/source/overview/administration.rst b/doc/source/overview/administration.rst index d6afd25ef..4d04af46f 100644 --- a/doc/source/overview/administration.rst +++ b/doc/source/overview/administration.rst @@ -49,8 +49,8 @@ Each repository is expected to follow this minimum set of standards: :ref:`api_documentation`. - Unit testing with at least 80% test coverage. See :ref:`ci_cd`. - Infrastructure in place to deploy the library as a package on `PyPi - `_. See :ref:`packaging`. -- Proper license file and author. See :ref:`setup_file` and :ref:`license_file`. + `_. See :ref:`Packaging Style`. +- Proper license file and author. See :ref:`The \`\`setup.py\`\` File` and :ref:`The \`\`LICENSE\`\` File`. Release Procedures and Versioning diff --git a/doc/source/overview/contributing.rst b/doc/source/overview/contributing.rst index 23aa59335..62174bcc9 100644 --- a/doc/source/overview/contributing.rst +++ b/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 From 6f6e17f045f64dcdd62f3cd7a280259a5c2131ba Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Mon, 4 Apr 2022 09:42:53 +0200 Subject: [PATCH 26/37] Fix setuptools tab --- doc/source/packaging/structure.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/source/packaging/structure.rst b/doc/source/packaging/structure.rst index 750d8f7f5..8f2d0af2f 100644 --- a/doc/source/packaging/structure.rst +++ b/doc/source/packaging/structure.rst @@ -249,7 +249,7 @@ REF-TO-BUILD-SYSTEMS-TOML section. This file is mandatory as it allows ``pip`` to resolve the requirements for building the library. The following tabs expose the ``[build-system]`` section -for some of the most popular build tools in the Python ecosystem: +for some of the most popular build-system backend tools in the Python ecosystem: .. tabs:: @@ -260,6 +260,7 @@ for some of the most popular build tools in the Python ecosystem: [build-system] requires = ["setuptools", "wheel"] + build-backend = "setuptools.build_meta" .. tab:: flit From 92822fde2150a3e0732881f23f48202208b3ad3a Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Mon, 4 Apr 2022 10:01:05 +0200 Subject: [PATCH 27/37] Rename diagrams -> diag --- doc/source/conf.py | 2 +- doc/source/packaging/build-systems.rst | 6 +++--- .../diag/architecture_diag.png} | Bin .../build_system_diag.rst} | 2 +- .../doc_structure_diag.rst} | 2 +- .../grpc_structure_diag.rst} | 2 +- .../pyansys_namespace_diag.rst} | 2 +- .../pyproduct_library_structure_diag.rst} | 2 +- .../python_library_diag.rst} | 2 +- .../src_structure_diag.rst} | 2 +- .../tests_structure_diag.rst} | 2 +- doc/source/packaging/index.rst | 2 +- doc/source/packaging/structure.rst | 20 +++++++++--------- 13 files changed, 23 insertions(+), 23 deletions(-) rename doc/source/{images/diagram.png => packaging/diag/architecture_diag.png} (100%) rename doc/source/packaging/{diagrams/build_system_diagram.rst => diag/build_system_diag.rst} (98%) rename doc/source/packaging/{diagrams/doc_structure_diagram.rst => diag/doc_structure_diag.rst} (97%) rename doc/source/packaging/{diagrams/grpc_structure_diagram.rst => diag/grpc_structure_diag.rst} (97%) rename doc/source/packaging/{diagrams/pyansys_namespace_diagram.rst => diag/pyansys_namespace_diag.rst} (97%) rename doc/source/packaging/{diagrams/pyproduct_library_structure_diagram.rst => diag/pyproduct_library_structure_diag.rst} (97%) rename doc/source/packaging/{diagrams/python_library_diagram.rst => diag/python_library_diag.rst} (98%) rename doc/source/packaging/{diagrams/src_structure_diagram.rst => diag/src_structure_diag.rst} (98%) rename doc/source/packaging/{diagrams/tests_structure_diagram.rst => diag/tests_structure_diag.rst} (96%) diff --git a/doc/source/conf.py b/doc/source/conf.py index 5caaf9972..4b4fd33f2 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -99,7 +99,7 @@ # Do not include the following patterns as documentation source files. # See issue: https://github.com/sphinx-doc/sphinx/issues/1668 -exclude_patterns = ["packaging/diagrams/*", "packaging/resources/*"] +exclude_patterns = ["packaging/diag/*", "packaging/resources/*"] # Fix excessive margins in mermaid output. # See issue: https://github.com/mermaid-js/mermaid/issues/1800#issuecomment-741617143 diff --git a/doc/source/packaging/build-systems.rst b/doc/source/packaging/build-systems.rst index 4f716743a..f87b81301 100644 --- a/doc/source/packaging/build-systems.rst +++ b/doc/source/packaging/build-systems.rst @@ -31,9 +31,9 @@ PyAnsys project. The interation between the maintainer and the build-system is performed using a build-system tool. This tool provides a frontend and a backend. The maintainers trigger the frontend, which then calls the backend. The backend then reads the -project directory and generates the artifacts, as :numref:`build system diagram`: +project directory and generates the artifacts, as :numref:`build system diag`: -.. include:: diagrams/build_system_diagram.rst +.. include:: diag/build_system_diag.rst PEP 517 and PEP 518 @@ -57,7 +57,7 @@ PEP 517 ------- `PEP 517` allows Python developers to specify the build-backend tool for -generating artifacts. As seen in the :numref:`build system diagram` figure, these +generating artifacts. As seen in the :numref:`build system diag` figure, these are the most popular backends: - `Setuptools`_ , while very popular, lacks build time dependency declaration diff --git a/doc/source/images/diagram.png b/doc/source/packaging/diag/architecture_diag.png similarity index 100% rename from doc/source/images/diagram.png rename to doc/source/packaging/diag/architecture_diag.png diff --git a/doc/source/packaging/diagrams/build_system_diagram.rst b/doc/source/packaging/diag/build_system_diag.rst similarity index 98% rename from doc/source/packaging/diagrams/build_system_diagram.rst rename to doc/source/packaging/diag/build_system_diag.rst index 22bd9694c..e1830c534 100644 --- a/doc/source/packaging/diagrams/build_system_diagram.rst +++ b/doc/source/packaging/diag/build_system_diag.rst @@ -1,4 +1,4 @@ -.. _build system diagram: +.. _build system diag: .. mermaid:: :caption: Maintainers use the build system to create artifacts :alt: Maintainers use the build system to create artifacts diff --git a/doc/source/packaging/diagrams/doc_structure_diagram.rst b/doc/source/packaging/diag/doc_structure_diag.rst similarity index 97% rename from doc/source/packaging/diagrams/doc_structure_diagram.rst rename to doc/source/packaging/diag/doc_structure_diag.rst index c9680f9c2..cc5aae43b 100644 --- a/doc/source/packaging/diagrams/doc_structure_diagram.rst +++ b/doc/source/packaging/diag/doc_structure_diag.rst @@ -1,4 +1,4 @@ -.. _doc structure diagram: +.. _doc structure diag: .. graphviz:: :caption: Generic structure for the ``doc/`` directory :alt: Generic structure for the ``doc/`` directory diff --git a/doc/source/packaging/diagrams/grpc_structure_diagram.rst b/doc/source/packaging/diag/grpc_structure_diag.rst similarity index 97% rename from doc/source/packaging/diagrams/grpc_structure_diagram.rst rename to doc/source/packaging/diag/grpc_structure_diag.rst index e3457f853..5c7ec608b 100644 --- a/doc/source/packaging/diagrams/grpc_structure_diagram.rst +++ b/doc/source/packaging/diag/grpc_structure_diag.rst @@ -1,4 +1,4 @@ -.. _grpc structure diagram: +.. _grpc structure diag: .. graphviz:: :caption: Namespace convention for gRPC interface packages :alt: Namespace convention for gRPC interface packages diff --git a/doc/source/packaging/diagrams/pyansys_namespace_diagram.rst b/doc/source/packaging/diag/pyansys_namespace_diag.rst similarity index 97% rename from doc/source/packaging/diagrams/pyansys_namespace_diagram.rst rename to doc/source/packaging/diag/pyansys_namespace_diag.rst index 6b7bbe09d..8e11b2b55 100644 --- a/doc/source/packaging/diagrams/pyansys_namespace_diagram.rst +++ b/doc/source/packaging/diag/pyansys_namespace_diag.rst @@ -1,4 +1,4 @@ -.. _pyansys_namespace_diagram: +.. _pyansys_namespace_diag: .. graphviz:: :caption: Namespace convention for PyAnsys projects :alt: Namespace convention for PyAnsys projects diff --git a/doc/source/packaging/diagrams/pyproduct_library_structure_diagram.rst b/doc/source/packaging/diag/pyproduct_library_structure_diag.rst similarity index 97% rename from doc/source/packaging/diagrams/pyproduct_library_structure_diagram.rst rename to doc/source/packaging/diag/pyproduct_library_structure_diag.rst index e4a61be20..365716112 100644 --- a/doc/source/packaging/diagrams/pyproduct_library_structure_diagram.rst +++ b/doc/source/packaging/diag/pyproduct_library_structure_diag.rst @@ -1,4 +1,4 @@ -.. _pyproduct library structure diagram: +.. _pyproduct library structure diag: .. graphviz:: :caption: Minimum required PyAnsys project structure :alt: Minimum required PyAnsys project structure diff --git a/doc/source/packaging/diagrams/python_library_diagram.rst b/doc/source/packaging/diag/python_library_diag.rst similarity index 98% rename from doc/source/packaging/diagrams/python_library_diagram.rst rename to doc/source/packaging/diag/python_library_diag.rst index 83a24ce80..c9b4aa324 100644 --- a/doc/source/packaging/diagrams/python_library_diagram.rst +++ b/doc/source/packaging/diag/python_library_diag.rst @@ -1,4 +1,4 @@ -.. _python pkg lib diagram: +.. _python pkg lib diag: .. graphviz:: :caption: A Python library is a collection of packages. :alt: A Python library is a collection of packages. diff --git a/doc/source/packaging/diagrams/src_structure_diagram.rst b/doc/source/packaging/diag/src_structure_diag.rst similarity index 98% rename from doc/source/packaging/diagrams/src_structure_diagram.rst rename to doc/source/packaging/diag/src_structure_diag.rst index 46254bb47..1e9cb32bb 100644 --- a/doc/source/packaging/diagrams/src_structure_diagram.rst +++ b/doc/source/packaging/diag/src_structure_diag.rst @@ -1,4 +1,4 @@ -.. _src structure diagram: +.. _src structure diag: .. graphviz:: :caption: Generic structure for the src/ directory :alt: Generic structure for the src/ directory diff --git a/doc/source/packaging/diagrams/tests_structure_diagram.rst b/doc/source/packaging/diag/tests_structure_diag.rst similarity index 96% rename from doc/source/packaging/diagrams/tests_structure_diagram.rst rename to doc/source/packaging/diag/tests_structure_diag.rst index 72b4d13aa..8363cabdf 100644 --- a/doc/source/packaging/diagrams/tests_structure_diagram.rst +++ b/doc/source/packaging/diag/tests_structure_diag.rst @@ -1,4 +1,4 @@ -.. _tests structure diagram: +.. _tests structure diag: .. graphviz:: :caption: Minimum required PyAnsys project structure :alt: Minimum required PyAnsys project structure diff --git a/doc/source/packaging/index.rst b/doc/source/packaging/index.rst index 7d699c97e..bccdb0ca9 100644 --- a/doc/source/packaging/index.rst +++ b/doc/source/packaging/index.rst @@ -21,7 +21,7 @@ general pattern for a PyAnsys library ensures: This figure shows the general pattern that each PyAnsys library should follow: -.. image:: ../images/diagram.png +.. image:: diag/architecture_diag.png :alt: Overview Diagram The Ansys product or service exposes an interface that is locally diff --git a/doc/source/packaging/structure.rst b/doc/source/packaging/structure.rst index 8f2d0af2f..127777d57 100644 --- a/doc/source/packaging/structure.rst +++ b/doc/source/packaging/structure.rst @@ -30,7 +30,7 @@ PyAnsys Library `_ is the name for the core MAPDL library. -.. include:: diagrams/pyansys_namespace_diagram.rst +.. include:: diag/pyansys_namespace_diag.rst The previous structure leads to the following namespace when executing the import statement: @@ -51,7 +51,7 @@ Lower-level gRPC interface packages like `ansys-api-mapdl`_ should always be named ``ansys-api-`` and may contain an additional level: ``ansys-api--``. -.. include:: diagrams/grpc_structure_diagram.rst +.. include:: diag/grpc_structure_diag.rst The previous structure leads to the following namespace within the ``*.proto`` files: @@ -92,9 +92,9 @@ Differences Between a Python Package and Library Although both terms are used interchangeably, there is a key difference between them: a Python package is a collection of Python modules and sub-packages while a Python Library is a collection of Python packages. Figure :numref:`python pkg -lib diagram` exposes this. +lib diag` exposes this. -.. include:: diagrams/python_library_diagram.rst +.. include:: diag/python_library_diag.rst Required Files for a PyAnsys Project @@ -103,7 +103,7 @@ Required Files for a PyAnsys Project The structure of any PyAnsys library contains the following files and directories: -.. include:: diagrams/pyproduct_library_structure_diagram.rst +.. include:: diag/pyproduct_library_structure_diag.rst Descriptions follow for some of the directories in the structure: @@ -135,10 +135,10 @@ A PyAnsys project should have the following documentation sections: Projects in the PyAnsys ecosystem take advantage of `Sphinx`_, a tool used for building documentation for Python-based projects. A ``doc/`` directory making use of `Sphinx`_ requires the following structure, as shown by figure -:numref:`doc structure diagram`: +:numref:`doc structure diag`: -.. include:: diagrams/doc_structure_diagram.rst +.. include:: diag/doc_structure_diag.rst - ``_build`` contains the rendered documentation in various formats: HTML, PDF... @@ -179,9 +179,9 @@ There are different approaches available for creating a namespace package. For the ansys namespace, we use the `PEP 420`_ `native namespace packages`_ approach. Therefore, the source directory of any PyAnsys library must look like the one -exposed by figure :numref:`src structure diagram`: +exposed by figure :numref:`src structure diag`: -.. include:: diagrams/src_structure_diagram.rst +.. include:: diag/src_structure_diag.rst The ``tests/`` Directory @@ -193,7 +193,7 @@ PyAnsys projects use the `pytest`_ testing framework. A good practice is to emulate the structure of the ``src/ansys/product/library`` directory although it is not always necessary. -.. include:: diagrams/tests_structure_diagram.rst +.. include:: diag/tests_structure_diag.rst Notice the usage of ``tests_*/`` when creating new directories inside the ``tests/`` one. On the other hand, unit testing files are named using the From 371c7ea634c0dd2cda465dea8376d92d15527575 Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Mon, 4 Apr 2022 10:28:19 +0200 Subject: [PATCH 28/37] Fix sphinx-tabs version --- requirements_docs.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements_docs.txt b/requirements_docs.txt index 0b623af83..e533b40c3 100644 --- a/requirements_docs.txt +++ b/requirements_docs.txt @@ -2,5 +2,5 @@ Sphinx==4.5.0 pyansys-sphinx-theme==0.2.3 sphinx-copybutton==0.5.0 sphinx_toolbox==2.18.0 -sphinx-tabs>=3.3.1 +sphinx-tabs>=1.2.1,<=3.2.0 sphinxcontrib-mermaid>=0.7.1 From 854de954d37fde8c1e6996fd9a234fddfe8149bb Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Mon, 4 Apr 2022 10:33:19 +0200 Subject: [PATCH 29/37] Apply style --- doc/source/conf.py | 2 +- doc/source/packaging/build-systems.rst | 2 +- doc/source/packaging/diag/build_system_diag.rst | 2 +- doc/source/packaging/structure.rst | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 4b4fd33f2..57b8beffd 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -104,7 +104,7 @@ # 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'] +mermaid_params = ["--width", "2000"] # Generate section labels up to three levels deep autosectionlabel_maxdepth = 3 diff --git a/doc/source/packaging/build-systems.rst b/doc/source/packaging/build-systems.rst index f87b81301..e187bef7c 100644 --- a/doc/source/packaging/build-systems.rst +++ b/doc/source/packaging/build-systems.rst @@ -28,7 +28,7 @@ PyAnsys project. files. -The interation between the maintainer and the build-system is performed using a +The interaction between the maintainer and the build-system is performed using a build-system tool. This tool provides a frontend and a backend. The maintainers trigger the frontend, which then calls the backend. The backend then reads the project directory and generates the artifacts, as :numref:`build system diag`: diff --git a/doc/source/packaging/diag/build_system_diag.rst b/doc/source/packaging/diag/build_system_diag.rst index e1830c534..6e6147ee0 100644 --- a/doc/source/packaging/diag/build_system_diag.rst +++ b/doc/source/packaging/diag/build_system_diag.rst @@ -51,7 +51,7 @@ classDef NodeStyle stroke:black,color:black,fill:white,stroke-width:2px,font-size:12pt; classDef SubgraphStyle stroke:black,color:black,fill:white,stroke-width:2px,font-size:14pt,font-weight:bold; - %% Asign style to elements + %% Assign style to elements class maintainers,setuptools,flit,poetry,setuptools.build_back,flit_core.api,poetry.masonry.api,pyproject.toml,metadata,sourcefiles,*.whl,*.tar.gz NodeStyle; class build_system,frontend,backend,project,artifacts SubgraphStyle; diff --git a/doc/source/packaging/structure.rst b/doc/source/packaging/structure.rst index 127777d57..6552c4998 100644 --- a/doc/source/packaging/structure.rst +++ b/doc/source/packaging/structure.rst @@ -168,7 +168,7 @@ build system will look when generating the wheel and source distributions. .. warning:: - Folders inside the ``src/`` cannot contain spaces or hypens. Replace these + Folders inside the ``src/`` cannot contain spaces or hyphens. Replace these symbols by using the underscore '_'. The structure of the ``src/`` directory determines the namespace of the PyAnsys From ad59e6d619b1e56943ae6374343d06f4cce314f0 Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Mon, 4 Apr 2022 10:42:35 +0200 Subject: [PATCH 30/37] Rename resources -> code --- doc/source/conf.py | 2 +- .../license_mit_code.rst} | 0 doc/source/packaging/code/pyproject_code.rst | 13 ++++++ .../packaging/code/pyproject_flit_code.rst | 36 +++++++++++++++++ .../packaging/code/pyproject_poetry_code.rst | 29 ++++++++++++++ .../code/pyproject_setuptools_code.rst | 5 +++ .../setup_file_code.rst} | 0 doc/source/packaging/structure.rst | 40 +++---------------- 8 files changed, 90 insertions(+), 35 deletions(-) rename doc/source/packaging/{resources/license_mit.rst => code/license_mit_code.rst} (100%) create mode 100644 doc/source/packaging/code/pyproject_code.rst create mode 100644 doc/source/packaging/code/pyproject_flit_code.rst create mode 100644 doc/source/packaging/code/pyproject_poetry_code.rst create mode 100644 doc/source/packaging/code/pyproject_setuptools_code.rst rename doc/source/packaging/{resources/setup_file_template.rst => code/setup_file_code.rst} (100%) diff --git a/doc/source/conf.py b/doc/source/conf.py index 57b8beffd..456a08d03 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -99,7 +99,7 @@ # 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/resources/*"] +exclude_patterns = ["packaging/diag/*", "packaging/code/*"] # Fix excessive margins in mermaid output. # See issue: https://github.com/mermaid-js/mermaid/issues/1800#issuecomment-741617143 diff --git a/doc/source/packaging/resources/license_mit.rst b/doc/source/packaging/code/license_mit_code.rst similarity index 100% rename from doc/source/packaging/resources/license_mit.rst rename to doc/source/packaging/code/license_mit_code.rst diff --git a/doc/source/packaging/code/pyproject_code.rst b/doc/source/packaging/code/pyproject_code.rst new file mode 100644 index 000000000..de96bc9dc --- /dev/null +++ b/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 diff --git a/doc/source/packaging/code/pyproject_flit_code.rst b/doc/source/packaging/code/pyproject_flit_code.rst new file mode 100644 index 000000000..8ad238d71 --- /dev/null +++ b/doc/source/packaging/code/pyproject_flit_code.rst @@ -0,0 +1,36 @@ +.. code:: toml + + [build-system] + requires = ["flit_core >=3.2,<4"] + build-backend = "flit_core.buildapi" + + [project] + # Check https://flit.readthedocs.io/en/latest/pyproject_toml.html for all available sections + name = "Py " + version = "" + description = "A Python wrapper for Ansys " + readme = "README.rst" + requires-python = ">=3." + license = {file = "LICENSE"} + authors = [ + {name = "ANSYS, Inc.", email = "pyansys.support@ansys.com"}, + ] + maintainers = [ + {name = "PyAnsys developers", email = "pyansys.maintainers@ansys.com"}, + ] + + classifiers = [ + "Development Status :: 4 - Beta", + "Programming Language :: Python :: 3", + "License :: OSI Approved :: MIT License", + "Operating System :: OS Independent", + ] + dependencies = [ + "importlib-metadata >=4.0", + ] + + [tool.flit.module] + name = "ansys.." + + [project.urls] + Source = "https://github.com/pyansys/py-" diff --git a/doc/source/packaging/code/pyproject_poetry_code.rst b/doc/source/packaging/code/pyproject_poetry_code.rst new file mode 100644 index 000000000..0cc417eb9 --- /dev/null +++ b/doc/source/packaging/code/pyproject_poetry_code.rst @@ -0,0 +1,29 @@ +.. code:: toml + + [build-system] + requires = ["poetry-core>=1.0.0"] + build-backend = "poetry.core.masonry.api" + + [tool.poetry] + # Check https://python-poetry.org/docs/pyproject/ for all available sections + name = "Py " + version = "" + description = "A Python wrapper for " + license = "MIT" + authors = ["ANSYS, Inc. "] + maintainers = ["PyAnsys developers "] + readme = "README.rst" + repository = "https://github.com/pyansys/py-" + classifiers = [ + "Development Status :: 4 - Beta", + "Programming Language :: Python :: 3", + "License :: OSI Approved :: MIT License", + "Operating System :: OS Independent", + ] + packages = [ + { include = "ansys", from = "src" }, + ] + + [tool.poetry.dependencies] + python = ">=3." + importlib-metadata = {version = "^4.0", python = "<3.8"} diff --git a/doc/source/packaging/code/pyproject_setuptools_code.rst b/doc/source/packaging/code/pyproject_setuptools_code.rst new file mode 100644 index 000000000..f3b445ddd --- /dev/null +++ b/doc/source/packaging/code/pyproject_setuptools_code.rst @@ -0,0 +1,5 @@ +.. code:: toml + + [build-system] + requires = ["setuptools", "wheel"] + build-backend = "setuptools.build_meta" diff --git a/doc/source/packaging/resources/setup_file_template.rst b/doc/source/packaging/code/setup_file_code.rst similarity index 100% rename from doc/source/packaging/resources/setup_file_template.rst rename to doc/source/packaging/code/setup_file_code.rst diff --git a/doc/source/packaging/structure.rst b/doc/source/packaging/structure.rst index 6552c4998..0273c0aed 100644 --- a/doc/source/packaging/structure.rst +++ b/doc/source/packaging/structure.rst @@ -208,7 +208,7 @@ The ``LICENSE`` file provides the legal framework for the software. The recommended license for `PyAnsys`_ projects is `MIT License`_. A template for this license is provided below: -.. include:: resources/license_mit.rst +.. include:: code/license_mit_code.rst .. note:: @@ -251,35 +251,7 @@ This file is mandatory as it allows ``pip`` to resolve the requirements for building the library. The following tabs expose the ``[build-system]`` section for some of the most popular build-system backend tools in the Python ecosystem: - -.. tabs:: - - .. tab:: setuptools - - .. code:: toml - - [build-system] - requires = ["setuptools", "wheel"] - build-backend = "setuptools.build_meta" - - .. tab:: flit - - .. code:: toml - - # Refer to https://dev.docs.pyansys.com/packaging/build-systems#flit - [build-system] - requires = ["flit_core>=3.2,<4"] - build-backend = "flit_core.buildapi" - - - .. tab:: poetry - - .. code:: toml - - # Refer to https://dev.docs.pyansys.com/packaging/build-systems#poetry - [build-system] - requires = ["poetry"] - build-backend = "poetry.masonry.api" +.. include:: code/pyproject_code.rst The ``setup.py`` File @@ -291,10 +263,10 @@ file, ``setup.py`` is Python script. This means that Python code is interpreted when building the library. This allows to customize the building process but also may introduced security issues. -.. tip:: +.. warning:: - Consider using a ``pyproject.toml`` file instead of a ``setup.py`` when - possible. + The ``setup.py`` is only compatible with `setuptools`_. Consider using a + ``pyproject.toml`` file instead. The ``setup.py`` file is only compatible with `Setuptools`_. A ``setup.cfg`` can @@ -309,7 +281,7 @@ As a minimum configuration for PyAnsys projects, the following ``setup.py`` template can be used: -.. include:: resources/setup_file_template.rst +.. include:: code/setup_file_code.rst .. REFERENCES & LINKS From 14b25603241f0006064ab505f047f75000f18f57 Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Mon, 4 Apr 2022 11:28:09 +0200 Subject: [PATCH 31/37] Fix cross references --- doc/source/guidelines/dev_practices.rst | 4 ++-- doc/source/guidelines/test_practices.rst | 4 +++- doc/source/overview/administration.rst | 4 ++-- 3 files changed, 7 insertions(+), 5 deletions(-) diff --git a/doc/source/guidelines/dev_practices.rst b/doc/source/guidelines/dev_practices.rst index 10a714f58..5fed12f7a 100644 --- a/doc/source/guidelines/dev_practices.rst +++ b/doc/source/guidelines/dev_practices.rst @@ -87,8 +87,8 @@ changes any given branch is introducing before looking at the code. - ``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 diff --git a/doc/source/guidelines/test_practices.rst b/doc/source/guidelines/test_practices.rst index 73a95ec08..e0d2aac3a 100644 --- a/doc/source/guidelines/test_practices.rst +++ b/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,7 +284,7 @@ Testing Framework For consistency, PyAnsys tools and libraries should use either the `unittest `_ or `pytest `_ frameworks for unit testing. As described in -:ref:`repo_dir_struct`, unit tests should be placed into the ``tests`` +:ref:`Required Files for a PyAnsys Project`, unit tests should be placed into the ``tests`` directory in the root directory of the library:: tests/ diff --git a/doc/source/overview/administration.rst b/doc/source/overview/administration.rst index 4d04af46f..0d6cf21f8 100644 --- a/doc/source/overview/administration.rst +++ b/doc/source/overview/administration.rst @@ -44,10 +44,10 @@ 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`. +- CI/CD using GitHub actions or Azure DevOps to enforce coding standards. - Publicly hosted documentation detailing API with 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 `_. See :ref:`Packaging Style`. - Proper license file and author. See :ref:`The \`\`setup.py\`\` File` and :ref:`The \`\`LICENSE\`\` File`. From 8b1e5bac3173db51683b9de2437e25b8f67d357c Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Mon, 4 Apr 2022 11:41:07 +0200 Subject: [PATCH 32/37] Ignore duplicated autosectionlabel references --- doc/source/conf.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/source/conf.py b/doc/source/conf.py index 456a08d03..39ac25a14 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -108,3 +108,7 @@ # 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.*"] From 5757697cfbbcebee2c170425bfbe88d15eb062f8 Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Mon, 4 Apr 2022 12:40:20 +0200 Subject: [PATCH 33/37] Add diagrams dependencies in CI deps --- .github/workflows/ci-build.yml | 7 +++++++ .github/workflows/nightly-build.yml | 7 +++++++ 2 files changed, 14 insertions(+) diff --git a/.github/workflows/ci-build.yml b/.github/workflows/ci-build.yml index 047dd30d2..10288bc01 100644 --- a/.github/workflows/ci-build.yml +++ b/.github/workflows/ci-build.yml @@ -38,6 +38,13 @@ jobs: with: python-version: 3.8 + - name: Install diagrams dependencies + run: | + sudo apt update + sudo apt install graphviz + sudo apt install nodejs npm + npm install -g @mermaid-js/mermaid-cli + - name: Build HTML Documentation run: | pip install -r requirements_docs.txt --disable-pip-version-check diff --git a/.github/workflows/nightly-build.yml b/.github/workflows/nightly-build.yml index 1cfeab2fa..afec154b2 100644 --- a/.github/workflows/nightly-build.yml +++ b/.github/workflows/nightly-build.yml @@ -18,6 +18,13 @@ jobs: with: python-version: 3.8 + - name: Install mermaid-cli + run: | + sudo apt update + sudo apt install graphviz + sudo apt install nodejs npm + npm install -g @mermaid-js/mermaid-cli + - name: Build HTML Documentation run: | pip install -r requirements_docs.txt --disable-pip-version-check From 8155ca8001faccf537fbb279d1cebd74f42490c8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jorge=20Mart=C3=ADnez?= <28702884+jorgepiloto@users.noreply.github.com> Date: Mon, 4 Apr 2022 13:12:12 +0200 Subject: [PATCH 34/37] Apply suggestions from code review Co-authored-by: Alex Kaszynski --- .github/workflows/ci-build.yml | 5 ++--- .github/workflows/nightly-build.yml | 5 ++--- doc/source/packaging/build-systems.rst | 2 +- 3 files changed, 5 insertions(+), 7 deletions(-) diff --git a/.github/workflows/ci-build.yml b/.github/workflows/ci-build.yml index 10288bc01..8883275af 100644 --- a/.github/workflows/ci-build.yml +++ b/.github/workflows/ci-build.yml @@ -40,9 +40,8 @@ jobs: - name: Install diagrams dependencies run: | - sudo apt update - sudo apt install graphviz - sudo apt install nodejs npm + sudo apt-get update + sudo apt-get install nodejs npm graphviz npm install -g @mermaid-js/mermaid-cli - name: Build HTML Documentation diff --git a/.github/workflows/nightly-build.yml b/.github/workflows/nightly-build.yml index afec154b2..4c190bc04 100644 --- a/.github/workflows/nightly-build.yml +++ b/.github/workflows/nightly-build.yml @@ -20,9 +20,8 @@ jobs: - name: Install mermaid-cli run: | - sudo apt update - sudo apt install graphviz - sudo apt install nodejs npm + sudo apt-get update + sudo apt-get install nodejs npm graphviz npm install -g @mermaid-js/mermaid-cli - name: Build HTML Documentation diff --git a/doc/source/packaging/build-systems.rst b/doc/source/packaging/build-systems.rst index e187bef7c..85a4fb48b 100644 --- a/doc/source/packaging/build-systems.rst +++ b/doc/source/packaging/build-systems.rst @@ -10,7 +10,7 @@ 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: From eb4532fae281daa76a346e456b34974bedc15ac7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jorge=20Mart=C3=ADnez?= <28702884+jorgepiloto@users.noreply.github.com> Date: Mon, 4 Apr 2022 14:22:53 +0200 Subject: [PATCH 35/37] Apply suggestions from code review Co-authored-by: Alex Kaszynski --- doc/source/packaging/build-systems.rst | 2 +- doc/source/packaging/structure.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/packaging/build-systems.rst b/doc/source/packaging/build-systems.rst index 85a4fb48b..5f379a864 100644 --- a/doc/source/packaging/build-systems.rst +++ b/doc/source/packaging/build-systems.rst @@ -56,7 +56,7 @@ 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 +`PEP 517`_ allows Python developers to specify the build-backend tool for generating artifacts. As seen in the :numref:`build system diag` figure, these are the most popular backends: diff --git a/doc/source/packaging/structure.rst b/doc/source/packaging/structure.rst index 0273c0aed..d162bc0c3 100644 --- a/doc/source/packaging/structure.rst +++ b/doc/source/packaging/structure.rst @@ -213,7 +213,7 @@ this license is provided below: .. note:: Just because a software does not ship with a LICENSE file, it does not mean - it is free or open source. If you require from using this software, contact + it is free or open source. If you need to use unlicensed software, contact its development team so they can provide you with the right license. From 2b4fafa36ab99df7567eb33441652ff2a8747b60 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jorge=20Mart=C3=ADnez?= <28702884+jorgepiloto@users.noreply.github.com> Date: Mon, 4 Apr 2022 17:46:48 +0200 Subject: [PATCH 36/37] Apply suggestions from code review Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> --- doc/source/guidelines/dev_practices.rst | 4 +- doc/source/guidelines/test_practices.rst | 4 +- doc/source/overview/administration.rst | 4 +- doc/source/packaging/build-systems.rst | 18 ++--- doc/source/packaging/index.rst | 2 +- doc/source/packaging/structure.rst | 98 ++++++++++++------------ doc/source/packaging/templates.rst | 15 ++-- 7 files changed, 70 insertions(+), 75 deletions(-) diff --git a/doc/source/guidelines/dev_practices.rst b/doc/source/guidelines/dev_practices.rst index 5fed12f7a..be30796b1 100644 --- a/doc/source/guidelines/dev_practices.rst +++ b/doc/source/guidelines/dev_practices.rst @@ -84,8 +84,8 @@ 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) Unit Testing ~~~~~~~~~~~~ diff --git a/doc/source/guidelines/test_practices.rst b/doc/source/guidelines/test_practices.rst index e0d2aac3a..378dba6e7 100644 --- a/doc/source/guidelines/test_practices.rst +++ b/doc/source/guidelines/test_practices.rst @@ -284,8 +284,8 @@ Testing Framework For consistency, PyAnsys tools and libraries should use either the `unittest `_ or `pytest `_ frameworks for unit testing. As described in -:ref:`Required Files for a PyAnsys Project`, 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 diff --git a/doc/source/overview/administration.rst b/doc/source/overview/administration.rst index 0d6cf21f8..9371875a3 100644 --- a/doc/source/overview/administration.rst +++ b/doc/source/overview/administration.rst @@ -43,9 +43,9 @@ 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`. +- PEP8 code standards. See :ref:`best_practices`. - CI/CD using GitHub actions or Azure DevOps to enforce coding standards. -- Publicly hosted documentation detailing API with examples. See +- Publicly hosted documentation describing the API and providing examples. See :ref:`api_documentation`. - Unit testing with at least 80% test coverage. - Infrastructure in place to deploy the library as a package on `PyPi diff --git a/doc/source/packaging/build-systems.rst b/doc/source/packaging/build-systems.rst index 5f379a864..4ccbc2b38 100644 --- a/doc/source/packaging/build-systems.rst +++ b/doc/source/packaging/build-systems.rst @@ -12,7 +12,7 @@ users and developers. Artifacts ========= -The build-system allows maintainers to generate artifacts for their Python +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. @@ -28,7 +28,7 @@ PyAnsys project. files. -The interaction between the maintainer and the build-system is performed using a +The interaction between the maintainer and the build system is performed using a build-system tool. This tool provides a frontend and a backend. The maintainers trigger the frontend, which then calls the backend. The backend then reads the project directory and generates the artifacts, as :numref:`build system diag`: @@ -60,7 +60,7 @@ PEP 517 generating artifacts. As seen in the :numref:`build system diag` figure, these are the most popular backends: -- `Setuptools`_ , while very popular, lacks build time dependency declaration +- `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. @@ -72,11 +72,11 @@ are the most popular backends: PEP 518 ------- -In addition to the ``setup.py`` file, a new project file named -``pyproject.toml`` file was specified by the `PEP 518`_. The main goal of this -file was to specify build time dependencies. However, some build system tools -like `flit`_ or `poetry`_ are able to specify all the project metadata inside -the ``pyproject.toml`` file and eliminate the usage of the ``setup.py``. +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 @@ -93,7 +93,7 @@ The combination of `PEP 517`_ and `PEP 518`_ leads to the following syntax in a build-backend = "flit_core.api" # Defined by PEP 517 -Build-backend Tools +Build Backend Tools =================== This section lists some of the most popular build systems in the diff --git a/doc/source/packaging/index.rst b/doc/source/packaging/index.rst index bccdb0ca9..53b55a8c4 100644 --- a/doc/source/packaging/index.rst +++ b/doc/source/packaging/index.rst @@ -19,7 +19,7 @@ general pattern for a PyAnsys library ensures: Ansys products * Unit testing, release packaging, and documentation -This figure shows the general pattern that each PyAnsys library should follow: +This diagram shows the general pattern that each PyAnsys library should follow: .. image:: diag/architecture_diag.png :alt: Overview Diagram diff --git a/doc/source/packaging/structure.rst b/doc/source/packaging/structure.rst index d162bc0c3..924a466d6 100644 --- a/doc/source/packaging/structure.rst +++ b/doc/source/packaging/structure.rst @@ -41,8 +41,8 @@ statement: Using long Python library names provides two primary advantages: -- `Namespace Packages`_ can be used to designate official Ansys packages -- Consistent branding and style can be applied to PyAnsys libraries +- `Namespace Packages`_ can be used to designate official Ansys packages. +- Consistent branding and style can be applied to PyAnsys libraries. gRPC Interface Package @@ -53,7 +53,7 @@ named ``ansys-api-`` and may contain an additional level: .. include:: diag/grpc_structure_diag.rst -The previous structure leads to the following namespace within the ``*.proto`` files: +This structure leads to the following namespace within ``*.proto`` files: .. code:: @@ -64,7 +64,7 @@ Python Libraries ================ A Python library is the formal way of distributing Python source code. It allows -to reuse and specify Python code dependencies. The guide presented in this page +for reuse and for specifying Python code dependencies. The guidance presented in this section is compliant with the `Python Packaging Authority`_ and PyAnsys recommendations. .. note:: @@ -80,19 +80,19 @@ Scripts, Modules, Sub-packages, and Packages To understand the structure of a Python Library, it is important to know the difference between Python scripts, modules, sub-packages, and packages. -* ``Script``: Any Python file with logic source code. -* ``Module``: Any Python script hosted next to an ``__init__.py`` file. -* ``Sub-package``: Any directory containing various Python modules. -* ``Package``: Any directory containing Python modules and sub-packages. +* ``Script``: Any Python file with logic source code +* ``Module``: Any Python script hosted next to an ``__init__.py`` file +* ``Sub-package``: Any directory containing various Python modules +* ``Package``: Any directory containing Python modules and sub-packages Differences Between a Python Package and Library ------------------------------------------------ -Although both terms are used interchangeably, there is a key difference between -them: a Python package is a collection of Python modules and sub-packages while -a Python Library is a collection of Python packages. Figure :numref:`python pkg -lib diag` exposes this. +Although the terms *package* and *library* are often used interchangeably, there is +a key difference between them. A Python package is a collection of Python modules and +sub-packages, while a Python Library is a collection of Python packages. Figure +:numref:`python pkg lib diag` exposes this. .. include:: diag/python_library_diag.rst @@ -100,8 +100,7 @@ lib diag` exposes this. Required Files for a PyAnsys Project ==================================== -The structure of any PyAnsys library contains the following files and -directories: +The structure of any PyAnsys library contains these files and directories: .. include:: diag/pyproduct_library_structure_diag.rst @@ -113,14 +112,14 @@ Descriptions follow for some of the directories in the structure: - ``tests/`` contains all unit tests for checking the integrity of the project. -- ``setup.py`` or ``pyproject.toml`` is known as the project's file. +- ``setup.py`` or ``pyproject.toml`` is the project file. The ``doc/`` Directory ---------------------- -When distributing software it is important to document it. Documenting software -means giving guidelines on how to install and describing all functions, +When distributing software, it is important to document it. Documenting software +means giving guidelines on how to install it and describing all functions, methods, and classes that it ships with. Case scenarios and examples should also be part of the documentation. @@ -133,22 +132,21 @@ A PyAnsys project should have the following documentation sections: - ``Contributing``: Supplies project-specific contribution guides and can link to general PyAnsys contribution guidelines Projects in the PyAnsys ecosystem take advantage of `Sphinx`_, a tool used for -building documentation for Python-based projects. A ``doc/`` directory making -use of `Sphinx`_ requires the following structure, as shown by figure -:numref:`doc structure diag`: +building documentation for Python-based projects. As shown in :numref:`doc structure diag`, +`Sphinx`_ requires a ``doc/`` directory with a specific structure: .. include:: diag/doc_structure_diag.rst -- ``_build`` contains the rendered documentation in various formats: HTML, - PDF... +- ``_build`` contains the rendered documentation in various formats, such as HTML + and PDF. -- ``source`` contains the RST files which will be rendered when building the +- ``source`` contains the RST files that will be rendered when building the documentation. - ``make.bat`` and ``Makefile`` are used to automate cleaning and building - commands. The ``make.bat`` is intended to be used by Windows users while - ``Makefile`` is devised for MacOS/Linux ones. + commands. You use ``make.bat`` when running on Windows and ``Makefile`` + when running on MacOS or Linux. The ``source/`` directory must contain at least these files: @@ -163,23 +161,23 @@ directory. The ``src/`` Directory ---------------------- -All the Python source code must be located in this directory. This is where the +All the Python source code must be located in the ``src/`` directory. This is where the build system will look when generating the wheel and source distributions. .. warning:: - Folders inside the ``src/`` cannot contain spaces or hyphens. Replace these - symbols by using the underscore '_'. + Folders inside the ``src/`` directory cannot contain spaces or hyphens. Replace these + characters with an underscore '_'. The structure of the ``src/`` directory determines the namespace of the PyAnsys -library. Namespace allow you to easily split sub-packages from a package into +library. A namespace allow you to easily split sub-packages from a package into single, independent distributions. There are different approaches available for creating a namespace package. For -the ansys namespace, we use the `PEP 420`_ `native namespace packages`_ approach. +the Ansys namespace, we use the `PEP 420`_ `native namespace packages`_ approach. Therefore, the source directory of any PyAnsys library must look like the one -exposed by figure :numref:`src structure diag`: +shown in diagram :numref:`src structure diag`: .. include:: diag/src_structure_diag.rst @@ -191,14 +189,14 @@ To guarantee the integrity of a PyAnsys project, a good test suite is required. PyAnsys projects use the `pytest`_ testing framework. A good practice is to emulate the structure of the ``src/ansys/product/library`` -directory although it is not always necessary. +directory, although this is not always necessary. .. include:: diag/tests_structure_diag.rst -Notice the usage of ``tests_*/`` when creating new directories inside the -``tests/`` one. On the other hand, unit testing files are named using the -``test_*.py`` prefix. This is the preferred way of naming directories and files -inside the ``tests/`` directory. +Notice the use of ``tests_*/`` when creating new directories inside the +``tests/`` one. For unit testing files, names use the ``test_*.py`` prefix. +This is the preferred way of naming directories and files inside the +``tests/`` directory. The ``LICENSE`` File @@ -214,7 +212,7 @@ this license is provided below: Just because a software does not ship with a LICENSE file, it does not mean it is free or open source. If you need to use unlicensed software, contact - its development team so they can provide you with the right license. + its development team so they can provide you with the correct license. The ``README.rst`` File @@ -222,9 +220,9 @@ The ``README.rst`` File Each PyAnsys library should have a ``README.rst`` file in the root directory. -The preferred format of this file is `reStructuredText Markup Syntax`_ or a +The preferred format of this file is `reStructuredText Markup Syntax`_, although `Markdown Syntax`_ can be used too. While Markdown syntax has better -GitHub support, text in RST files can be reused within Sphinx documentation. +GitHub support, ReStructured Text (RST) files can be reused within Sphinx documentation. This avoids duplication between the ``README.rst`` and the main ``index.rst`` in the ``doc/source/`` directory. @@ -247,8 +245,8 @@ The `PEP 518`_ introduced the usage of a new project file called ``pyproject.toml``. More information about this file can be found in the REF-TO-BUILD-SYSTEMS-TOML section. -This file is mandatory as it allows ``pip`` to resolve the requirements for -building the library. The following tabs expose the ``[build-system]`` section +The ``pyproject.toml`` file is mandatory because it allows ``pip`` to resolve the +requirements for building the library. The following tabs expose the ``[build-system]`` section for some of the most popular build-system backend tools in the Python ecosystem: .. include:: code/pyproject_code.rst @@ -257,11 +255,11 @@ for some of the most popular build-system backend tools in the Python ecosystem: The ``setup.py`` File --------------------- -For a long time, the ``setup.py`` has been the usual way of building and -distributing Python libraries. As opposite to the static ``pyproject.toml`` -file, ``setup.py`` is Python script. This means that Python code is interpreted -when building the library. This allows to customize the building process but -also may introduced security issues. +For a long time, the ``setup.py`` file was generally used to build and +distribute Python libraries. Unlike a static ``pyproject.toml`` file, the +``setup.py`` file is a Python script. This means that Python code is interpreted +when building the library. This approach supports customizing the build +process but can also introduce security issues. .. warning:: @@ -269,15 +267,13 @@ also may introduced security issues. ``pyproject.toml`` file instead. -The ``setup.py`` file is only compatible with `Setuptools`_. A ``setup.cfg`` can -also be used for specifying the metadata and packages, but the ``setup.py`` file -must be present too. More information about its usage can be found in the -following links: +While a ``setup.cfg`` file can be used to specify the metadata and packages, the ``setup.py`` +file must also be present. For more information, see: * `Building and Distributing Packages with Setuptools`_ * `Configuring setuptools using setup.cfg files`_ -As a minimum configuration for PyAnsys projects, the following ``setup.py`` +As a minimum configuration for a PyAnsys project, the following ``setup.py`` template can be used: diff --git a/doc/source/packaging/templates.rst b/doc/source/packaging/templates.rst index e007c8708..2949dd5e6 100644 --- a/doc/source/packaging/templates.rst +++ b/doc/source/packaging/templates.rst @@ -4,18 +4,17 @@ Templates ######### -Starting a new project from scratch is a tedious task. For this reason, the -`ansys-templates`_ tool was created to simplify the starting process and -make it more dynamic. Any rendered project will be compliant with the latest -PyAnsys coding and API style guidelines. +Starting a new project from scratch is a tedious task. To simplify the starting process +and make it more dynamic, the `ansys-templates`_ tool was created . Using this +template ensures that any project rendered will be compliant with the latest PyAnsys +coding and API style guidelines. The ``ansys-templates`` tool ============================ -The `ansys-templates`_ is a command line interface that provides you with a -collection of templates. This tool allows you to create new PyAnsys projects. -from scratch in a dynamic way by asking you several questions before generating -the new project. +The `ansys-templates`_ tool is a command line interface that provides a +collection of templates. When you use this tool to create a new PyAnsys project, your +responses to the several questions that are asked result in dynamic project generation. Please, follow the `ansys-templates installation guide`_ to get the latest stable version installed in your system. From deb681487d6e5afea04a79f280fced4a16bbd492 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jorge=20Mart=C3=ADnez?= <28702884+jorgepiloto@users.noreply.github.com> Date: Mon, 4 Apr 2022 17:55:13 +0200 Subject: [PATCH 37/37] Apply suggestions from code review Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> --- doc/source/packaging/build-systems.rst | 12 ++++++------ doc/source/packaging/diag/build_system_diag.rst | 4 ++-- doc/source/packaging/diag/doc_structure_diag.rst | 4 ++-- doc/source/packaging/diag/grpc_structure_diag.rst | 4 ++-- doc/source/packaging/diag/pyansys_namespace_diag.rst | 4 ++-- .../diag/pyproduct_library_structure_diag.rst | 4 ++-- doc/source/packaging/diag/src_structure_diag.rst | 4 ++-- doc/source/packaging/diag/tests_structure_diag.rst | 4 ++-- doc/source/packaging/structure.rst | 11 +++++------ 9 files changed, 25 insertions(+), 26 deletions(-) diff --git a/doc/source/packaging/build-systems.rst b/doc/source/packaging/build-systems.rst index 4ccbc2b38..6018d39d3 100644 --- a/doc/source/packaging/build-systems.rst +++ b/doc/source/packaging/build-systems.rst @@ -29,9 +29,9 @@ PyAnsys project. The interaction between the maintainer and the build system is performed using a -build-system tool. This tool provides a frontend and a backend. The maintainers -trigger the frontend, which then calls the backend. The backend then reads the -project directory and generates the artifacts, as :numref:`build system diag`: +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 @@ -56,9 +56,9 @@ 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. As seen in the :numref:`build system diag` figure, these -are the most popular backends: +`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. diff --git a/doc/source/packaging/diag/build_system_diag.rst b/doc/source/packaging/diag/build_system_diag.rst index 6e6147ee0..11e7d2e40 100644 --- a/doc/source/packaging/diag/build_system_diag.rst +++ b/doc/source/packaging/diag/build_system_diag.rst @@ -1,7 +1,7 @@ .. _build system diag: .. mermaid:: - :caption: Maintainers use the build system to create artifacts - :alt: Maintainers use the build system to create artifacts + :caption: Maintainers use the build system to create artifacts. + :alt: Maintainers use the build system to create artifacts. :align: center flowchart LR diff --git a/doc/source/packaging/diag/doc_structure_diag.rst b/doc/source/packaging/diag/doc_structure_diag.rst index cc5aae43b..1235cada7 100644 --- a/doc/source/packaging/diag/doc_structure_diag.rst +++ b/doc/source/packaging/diag/doc_structure_diag.rst @@ -1,7 +1,7 @@ .. _doc structure diag: .. graphviz:: - :caption: Generic structure for the ``doc/`` directory - :alt: Generic structure for the ``doc/`` directory + :caption: Generic structure for the ``doc/`` directory. + :alt: Generic structure for the ``doc/`` directory. :align: center digraph "sphinx-ext-graphviz" { diff --git a/doc/source/packaging/diag/grpc_structure_diag.rst b/doc/source/packaging/diag/grpc_structure_diag.rst index 5c7ec608b..65058aa04 100644 --- a/doc/source/packaging/diag/grpc_structure_diag.rst +++ b/doc/source/packaging/diag/grpc_structure_diag.rst @@ -1,7 +1,7 @@ .. _grpc structure diag: .. graphviz:: - :caption: Namespace convention for gRPC interface packages - :alt: Namespace convention for gRPC interface packages + :caption: Namespace convention for gRPC interface packages. + :alt: Namespace convention for gRPC interface packages. :align: center digraph "sphinx-ext-graphviz" { diff --git a/doc/source/packaging/diag/pyansys_namespace_diag.rst b/doc/source/packaging/diag/pyansys_namespace_diag.rst index 8e11b2b55..3c00946e7 100644 --- a/doc/source/packaging/diag/pyansys_namespace_diag.rst +++ b/doc/source/packaging/diag/pyansys_namespace_diag.rst @@ -1,7 +1,7 @@ .. _pyansys_namespace_diag: .. graphviz:: - :caption: Namespace convention for PyAnsys projects - :alt: Namespace convention for PyAnsys projects + :caption: Namespace convention for PyAnsys projects. + :alt: Namespace convention for PyAnsys projects. :align: center digraph "sphinx-ext-graphviz" { diff --git a/doc/source/packaging/diag/pyproduct_library_structure_diag.rst b/doc/source/packaging/diag/pyproduct_library_structure_diag.rst index 365716112..11efeb046 100644 --- a/doc/source/packaging/diag/pyproduct_library_structure_diag.rst +++ b/doc/source/packaging/diag/pyproduct_library_structure_diag.rst @@ -1,7 +1,7 @@ .. _pyproduct library structure diag: .. graphviz:: - :caption: Minimum required PyAnsys project structure - :alt: Minimum required PyAnsys project structure + :caption: Minimum required PyAnsys project structure. + :alt: Minimum required PyAnsys project structure. :align: center digraph "sphinx-ext-graphviz" { diff --git a/doc/source/packaging/diag/src_structure_diag.rst b/doc/source/packaging/diag/src_structure_diag.rst index 1e9cb32bb..41a70b861 100644 --- a/doc/source/packaging/diag/src_structure_diag.rst +++ b/doc/source/packaging/diag/src_structure_diag.rst @@ -1,7 +1,7 @@ .. _src structure diag: .. graphviz:: - :caption: Generic structure for the src/ directory - :alt: Generic structure for the src/ directory + :caption: Generic structure for the src/ directory. + :alt: Generic structure for the src/ directory. :align: center digraph "sphinx-ext-graphviz" { diff --git a/doc/source/packaging/diag/tests_structure_diag.rst b/doc/source/packaging/diag/tests_structure_diag.rst index 8363cabdf..eccfab352 100644 --- a/doc/source/packaging/diag/tests_structure_diag.rst +++ b/doc/source/packaging/diag/tests_structure_diag.rst @@ -1,7 +1,7 @@ .. _tests structure diag: .. graphviz:: - :caption: Minimum required PyAnsys project structure - :alt: Minimum required PyAnsys project structure + :caption: Minimum required PyAnsys project structure. + :alt: Minimum required PyAnsys project structure. :align: center digraph "sphinx-ext-graphviz" { diff --git a/doc/source/packaging/structure.rst b/doc/source/packaging/structure.rst index 924a466d6..d259df5da 100644 --- a/doc/source/packaging/structure.rst +++ b/doc/source/packaging/structure.rst @@ -202,8 +202,8 @@ This is the preferred way of naming directories and files inside the The ``LICENSE`` File -------------------- -The ``LICENSE`` file provides the legal framework for the software. The -recommended license for `PyAnsys`_ projects is `MIT License`_. A template for +The ``LICENSE`` file provides the legal framework for the software. `PyAnsys`_ +projects must use `MIT License`_. A template for this license is provided below: .. include:: code/license_mit_code.rst @@ -241,9 +241,8 @@ usually included in the ``long-description`` field. The ``pyproject.toml`` File --------------------------- -The `PEP 518`_ introduced the usage of a new project file called -``pyproject.toml``. More information about this file can be found in the -REF-TO-BUILD-SYSTEMS-TOML section. +`PEP 518`_ introduced the usage of a project file named +``pyproject.toml``. The ``pyproject.toml`` file is mandatory because it allows ``pip`` to resolve the requirements for building the library. The following tabs expose the ``[build-system]`` section @@ -261,7 +260,7 @@ distribute Python libraries. Unlike a static ``pyproject.toml`` file, the when building the library. This approach supports customizing the build process but can also introduce security issues. -.. warning:: +.. note:: The ``setup.py`` is only compatible with `setuptools`_. Consider using a ``pyproject.toml`` file instead.