diff --git a/doc/source/abstractions/app-interface.rst b/doc/source/abstractions/app-interface.rst index d5a718743..e1ebaa0c7 100644 --- a/doc/source/abstractions/app-interface.rst +++ b/doc/source/abstractions/app-interface.rst @@ -106,8 +106,9 @@ the model setup object. There's no reason why a user needs direct access to ``_omodelsetup``, which is why it's protected in the ``Hfss`` class. Additionally, calling the method is simplified by providing (and documenting) the defaults using keyword arguments and -placing them into the ``vars`` list, all while following the `Style -Guide for Python Code (PEP8)`_. +placing them into the ``vars`` list, all while following the Style +Guide for Python Code, defined in `PEP 8`_. -.. _PyAEDT: https://github.com/pyansys/pyaedt -.. _Style Guide for Python Code (PEP8): https://www.python.org/dev/peps/pep-0008 + +.. LINKS AND REFERENCES +.. include:: ../links.rst diff --git a/doc/source/abstractions/data-transfer.rst b/doc/source/abstractions/data-transfer.rst index 66a15e148..5933ddadf 100644 --- a/doc/source/abstractions/data-transfer.rst +++ b/doc/source/abstractions/data-transfer.rst @@ -3,10 +3,10 @@ Data Transfer Abstracted APIs should attempt to hide the implementation details of the remote or local API in a well organized data model. This data -model should avoid returning raw JSON files, gRPC messages, SWIG objects, +model should avoid returning raw JSON files, gRPC messages, `SWIG`_ objects, or .NET objects. It should preferably return standard Python objects -like lists, strings, dictionaries when useful, and `NumPy `_ -arrays or `pandas `_ dataframes for more complex data. +like lists, strings, dictionaries when useful, and `NumPy`_ +arrays or `pandas`_ dataframes for more complex data. For example, consider a simple mesh in MAPDL: @@ -109,16 +109,5 @@ interface that can efficiently exchange a wide variety of data formats and messages. -.. _gRPC: https://grpc.io/ -.. _pythoncom: http://timgolden.me.uk/pywin32-docs/pythoncom.html -.. _SWIG: http://www.swig.org/ -.. _C extensions: https://docs.python.org/3/extending/extending.html -.. _Anaconda Distribution: https://www.anaconda.com/products/individual -.. _REST: https://en.wikipedia.org/wiki/Representational_state_transfer -.. _PyAEDT: https://github.com/pyansys/PyAEDT -.. _PyMAPDL: https://github.com/pyansys/pymapdl -.. _pymapdl: https://github.com/pyansys/pymapdl -.. _Style Guide for Python Code (PEP8): https://www.python.org/dev/peps/pep-0008 -.. _grpc_chunk_stream_demo: https://github.com/pyansys/grpc_chunk_stream_demo -.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html -.. _Namespace Packages: https://packaging.python.org/guides/packaging-namespace-packages/ +.. LINKS AND REFERENCES +.. include:: ../links.rst diff --git a/doc/source/abstractions/service.rst b/doc/source/abstractions/service.rst index fd250d57a..e82de7a5b 100644 --- a/doc/source/abstractions/service.rst +++ b/doc/source/abstractions/service.rst @@ -10,12 +10,11 @@ the "desktop API". In this case, remote API calls should be identical if the service is local or remote, with the only difference being that local calls are faster to execute. -Consider the following code examples. The left-hand side shows the -amount of work to start, establish a connection to, and submit an -input file to MAPDL using auto-generated gRPC interface files. For -more information, see `pyansys-protos-generator -`_. The -right-hand side shows the same workflow but uses the `PyMAPDL`_ library. +Consider the following code examples. The left-hand side shows the amount of +work to start, establish a connection to, and submit an input file to MAPDL +using auto-generated gRPC interface files. For more information, see +`pyansys-protos-generator`_. The right-hand side shows the same workflow but +uses the `PyMAPDL`_ library. +----------------------------------------------------------+--------------------------------------------+ | Using the gRPC Auto-generated Interface | Using the `PyMAPDL`_ Library | @@ -78,6 +77,5 @@ At this point, because the assumption is that MAPDL is always remote, it's possible to issue commands to MAPDL, including those requiring file transfer like ``Mapdl.input``. -.. _REST: https://en.wikipedia.org/wiki/Representational_state_transfer -.. _gRPC: https://grpc.io/ -.. _PyMAPDL: https://github.com/pyansys/pymapdl +.. LINKS AND REFERENCES +.. include:: ../links.rst diff --git a/doc/source/coding_style/beyond_pep8.rst b/doc/source/coding_style/beyond_pep8.rst index b334d0d92..04ac75931 100644 --- a/doc/source/coding_style/beyond_pep8.rst +++ b/doc/source/coding_style/beyond_pep8.rst @@ -1,15 +1,15 @@ Beyond PEP8 -########### +=========== This topic describes any delineations, clarifications, or additional procedures above and -beyond `PEP8 `__. +beyond `PEP 8`_. -For example, `Stack Overflow Answer `_ -outlines deprecation best practices and a `Deprecation library `_ -already exists. However, there is no official guidance regarding deprecating features -in an API within Python. This page seeks to clarify this issue and others. +For example, `Stack Overflow Answer`_ outlines deprecation best practices and a +`Deprecation`_ library already exists. However, there is no official guidance +regarding deprecating features in an API within Python. This page seeks to +clarify this issue and others. Aside from the following PyAnsys-specific directives, the best coding practice is to -follow established guidelines from `PEP8 `__. +follow established guidelines from `PEP 8`_. Deprecation Best Practice @@ -18,8 +18,7 @@ Whenever a method, class, or function is deprecated, you must provide an old method that both calls the new method and raises a warning. Or, if the method has been removed, you must raise an ``AttributeError``. -In the docstring of the older method, provide a `Sphinx Deprecated Directive -`_ +In the docstring of the older method, provide a `Sphinx Deprecated Directive`_ and a link to the newer method. This way, users are notified that an API change has occurred and are given an opportunity to change their code. Otherwise, stability concerns can cause users to stop upgrading, or worse, stop using @@ -50,7 +49,7 @@ an error after a minor release or two. raise AttributeError('assignmaterial is deprecated. Use assign_material instead.') def assign_material(self, obj, mat): - """Assign a material to one or more objects. + """Assign a material to one or more objects.""" ... @@ -99,7 +98,7 @@ You can then use this custom ``DeprecationError`` in place of an ``Exception``. Semantic Versioning and API Changes ----------------------------------- -According to `Semantic Versioning `_, you should +According to `Semantic Versioning`, you should increment the MAJOR version when you make incompatible changes. However, adding or eliminating methods should not be considered incompatible changes to a code base but rather incremental changes @@ -110,8 +109,7 @@ should be bumped. To avoid constantly bumping the minor version, one approach to source-control branching is to create release branches where only patch fixes are pushed and API changes occur between minor -releases. See `Trunk Based Development -`_. +releases. See `Trunk Based Development`_. In summary, the mainline branch (commonly named ``main`` or ``master``) must always be ready to release, and developers should create @@ -275,7 +273,7 @@ If the output of some operation in an example cannot be verified exactly, an ellipsis (``...``) can be used in the expected output. This allows it to match any substring in the actual output. -.. code :: +.. code:: Examples -------- @@ -286,7 +284,7 @@ to match any substring in the actual output. To support this, ``doctest`` must be run with the option set to allow ellipses. -.. code :: +.. code:: pytest --doctest-modules -o ELLIPSIS file.py @@ -298,9 +296,15 @@ This is useful for examples that cannot run within ``pytest`` or have side effects that will affect the other tests if they are run during the ``doctest`` session. -.. code :: python +.. code:: python Examples -------- >>> desktop = Desktop("2021.1") # doctest: +SKIP + + +.. LINKS AND REFERENCES +.. include:: ../links.rst +.. _Sphinx Deprecated Directive: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-deprecated +.. _Stack Overflow Answer: htps://stackoverflow.com/questions/2536307 diff --git a/doc/source/coding_style/flake8.rst b/doc/source/coding_style/flake8.rst index 1780f642a..203120b3f 100644 --- a/doc/source/coding_style/flake8.rst +++ b/doc/source/coding_style/flake8.rst @@ -1,26 +1,16 @@ -.. _style-guide-enforcement: - Style Guide Enforcement ======================= -This topic describes the use of `Flake8`_ for `PEP8`_ style +This topic describes the use of `flake8`_ for `PEP 8`_ style enforcement and the minimum standards expected. PyAnsys libraries are expected to be consistent with these guidelines. -.. _PEP8: https://www.python.org/dev/peps/pep-0008/ - Flake8 ~~~~~~ -`Flake8`_ is a Python tool for enforcing code styling. It is a wrapper -around the following three tools: `PyFlakes`_, `pycodestyle`_, and -`Ned Batchelder's McCabe script for complexity`_. Flake8 runs all three tools at once, -checking the code against a variety of style rules, such as line length, -code complexity, and whitespace. - -.. _Flake8: https://flake8.pycqa.org/en/latest/index.html -.. _PyFlakes: https://pypi.org/project/pyflakes/ -.. _pycodestyle: https://pypi.org/project/pycodestyle/ -.. _`Ned Batchelder's McCabe script for complexity`: https://github.com/PyCQA/mccabe -.. _configuring-flake8: +`Flake8`_ is a Python tool for enforcing code styling. It is a wrapper around +the following three tools: `PyFlakes`_, `pycodestyle`_, and `Ned Batchelder's +McCabe script for complexity`, also known as `mccabe`_. Flake8 runs all three +tools at once, checking the code against a variety of style rules, such as line +length, code complexity, and whitespace. Configuring Flake8 ------------------ @@ -44,8 +34,7 @@ library: statistics = True Flake8 has many options that can be set within the configuration file. -For a list and descriptions, see this `Flake8 documentation topic -`__. +For a list and descriptions, see this `Flake8 documentation topic`_. The example configuration defines the following options: @@ -59,7 +48,7 @@ The example configuration defines the following options: check for and is not an exhaustive list. For a full list of error codes and their descriptions, see this `Flake8 - documentation topic `__. + documentation topic`_ - ``count`` Total number of errors to print at the end of the check. @@ -70,7 +59,7 @@ The example configuration defines the following options: - ``max-line-length`` Denotes the maximum line length for any one line of code. - The `PEP8`_ standard advises a maximum line length of 79. Because + The `PEP 8`_ standard advises a maximum line length of 79. Because this is a bit limiting in some cases, the maximum line length recommended for a PyAnsys library is 100. @@ -106,25 +95,21 @@ base. Utilizing Black ~~~~~~~~~~~~~~~ Manually checking for code styling can be a tedious task. Luckily, -several Python tools for auto-formatting code to meet PEP8 standards +several Python tools for auto-formatting code to meet `PEP 8`_ standards are available to help with this. The PyAnsys project suggests the use of the the formatting tool `black`_. On completing a code change, and before committing, `black`_ can be -run to reformat the code, following the PEP8 guidelines enforced through -Flake8. This will limit any manual code changes needed to address style +run to reformat the code, following the `PEP 8`_ guidelines enforced through +`flake8`_. This will limit any manual code changes needed to address style rules. -.. _black: https://black.readthedocs.io/en/stable/ Optionally, it is possible to automate the use of `black`_. This can be -done with the tool `pre-commit`_. Setting up a `pre-commit hook -to run black `_ +done with the tool `pre-commit`_. Setting up a `pre-commit hook to run black`_ will automatically format the code before committing. This simple way of incorporating code style checks into the development workflow to maintain -PEP8 guidelines requires minimal manual effort. - -.. _pre-commit: https://pre-commit.com/ +`PEP 8`_ guidelines requires minimal manual effort. Minimum Standards @@ -194,12 +179,11 @@ expected in a PyAnsys library. * `E501`_ - **Line too long.** - All code lines should not exceed 100 characters. The - `PEP8 line length guideline `_ - suggests a maximum line length of 79. Following this limit - is not as necessary today due to modern screen sizes. The suggested maximum - length of 100 can be easier to accommodate and can still support - viewing files side by side in code editors. + All code lines should not exceed 100 characters. The `PEP8 line length + guideline`_ suggests a maximum line length of 79. Following this limit is + not as necessary today due to modern screen sizes. The suggested maximum + length of 100 can be easier to accommodate and can still support viewing + files side by side in code editors. * `F401`_ - **Module imported but unused.** @@ -215,7 +199,7 @@ expected in a PyAnsys library. * **Limit complexity of code to 10.** This is enforced by the ``max-complexity`` option described in - :ref:`configuring-flake8`. Limiting code complexity leads to code that + :ref:`PEP 8 Best Practices`. Limiting code complexity leads to code that is easier to understand and less risky to modify. Write low- complexity code when possible. @@ -233,20 +217,8 @@ Your ``.flake8`` file should be: statistics = True -.. _W191: https://www.flake8rules.com/rules/W191.html -.. _W291: https://www.flake8rules.com/rules/W291.html -.. _W293: https://www.flake8rules.com/rules/W293.html -.. _W391: https://www.flake8rules.com/rules/W391.html -.. _E115: https://www.flake8rules.com/rules/E115.html -.. _E117: https://www.flake8rules.com/rules/E117.html -.. _E122: https://www.flake8rules.com/rules/E122.html -.. _E124: https://www.flake8rules.com/rules/E124.html -.. _E125: https://www.flake8rules.com/rules/E125.html -.. _E225: https://www.flake8rules.com/rules/E225.html -.. _E231: https://www.flake8rules.com/rules/E231.html -.. _E301: https://www.flake8rules.com/rules/E301.html -.. _E303: https://www.flake8rules.com/rules/E303.html -.. _E501: https://www.flake8rules.com/rules/E501.html -.. _F401: https://www.flake8rules.com/rules/F401.html -.. _F403: https://www.flake8rules.com/rules/F403.html - +.. REFERENCES AND LIKNS +.. include:: ../links.rst +.. _Flake8 documentation topic: https://flake8.pycqa.org/en/3.9.2/user/error-codes.html +.. _PEP8 line length guideline: https://www.python.org/dev/peps/pep-0008/#maximum-line-length +.. _pre-commit hook to run black: https://black.readthedocs.io/en/stable/integrations/source_version_control.html diff --git a/doc/source/coding_style/index.rst b/doc/source/coding_style/index.rst index 5a59528fe..cd069d7f8 100644 --- a/doc/source/coding_style/index.rst +++ b/doc/source/coding_style/index.rst @@ -1,17 +1,10 @@ -.. _coding_style: - Coding Style -************ +############ -PyAnsys libraries are expected to follow `PEP8`_ and +PyAnsys libraries are expected to follow `PEP 8`_ and be consistent in style and formatting with the 'big three' data science libraries: `NumPy`_, `SciPy`_, and `pandas`_. -.. _NumPy: https://numpy.org/ -.. _SciPy: https://www.scipy.org/ -.. _pandas: https://pandas.pydata.org/ -.. _PEP8: https://www.python.org/dev/peps/pep-0008/ - .. todo:: @@ -27,3 +20,5 @@ data science libraries: `NumPy`_, `SciPy`_, and `pandas`_. pep8_best_practices beyond_pep8 flake8 + +.. include:: ../links.rst diff --git a/doc/source/coding_style/pep8_best_practices.rst b/doc/source/coding_style/pep8_best_practices.rst index 046ab000b..0a18ff464 100644 --- a/doc/source/coding_style/pep8_best_practices.rst +++ b/doc/source/coding_style/pep8_best_practices.rst @@ -1,17 +1,10 @@ -.. _best_practices: - PEP 8 Best Practices ==================== -This topic summarizes key points from `PEP8`_ and how +This topic summarizes key points from `PEP 8`_ and how they apply to PyAnsys libraries. The goal is for PyAnsys libraries to be consistent in style and formatting with the `big three` data science libraries: `NumPy`_, `SciPy`_, and `pandas`_. -.. _NumPy: https://numpy.org/ -.. _SciPy: https://www.scipy.org/ -.. _pandas: https://pandas.pydata.org/ -.. _PEP8: https://www.python.org/dev/peps/pep-0008/ - Imports ~~~~~~~ @@ -20,8 +13,6 @@ module comments and docstrings and before module globals and constants. This reduces the likelihood of an `ImportError`_ that might only be discovered during runtime. -.. _ImportError: https://docs.python.org/3/library/exceptions.html#ImportError - Instead of: .. code:: python @@ -100,7 +91,7 @@ Use: You should avoid using wild cards in imports because doing so can make it difficult to detect undefined names. For more information, -see `Python Anti-Patterns: using wildcard imports <(https://docs.quantifiedcode.com/python-anti-patterns/maintainability/from_module_import_all_used.html>`_. +see `Python Anti-Patterns: using wildcard imports`_. Instead of: @@ -264,7 +255,7 @@ from PyPi. Class Naming Conventions ~~~~~~~~~~~~~~~~~~~~~~~~ -Use `camel case `_ when naming classes. Do not separate words +Use `camel case`_ when naming classes. Do not separate words with underscores. .. code:: python @@ -438,21 +429,17 @@ same line: For a multi-line docstring, put the ending ``"""`` on a line by itself. -PyAEDT follows the `numpydoc -`_ -docstring style, which is used by `numpy `_, -`scipy `_, `pandas -`_, and a variety of other Python open -source projects. For more information on docstrings for PyAnsys -libraries, see :ref:`api_documentation`. +`PyAEDT`_ follows the `numpydoc`_ docstring style, which is used by `numpy`_ +`scipy`_, `pandas`_, and a variety of other Python open source projects. For +more information on docstrings for PyAnsys libraries, see +:ref:`API Documentation Style`. Programming Recommendations ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The following sections provide some `PEP8 -`_ suggestions for removing -ambiguity and preserving consistency. They address some common pitfalls -when writing Python code. +The following sections provide some `PEP 8`_ suggestions for removing ambiguity +and preserving consistency. They address some common pitfalls when writing +Python code. Booleans and Comparisons @@ -719,6 +706,13 @@ Any library should be secure and implement good practices that avoid or mitigate This is especially relevant in libraries that request user input (such as web services). Because security is a broad topic, we recommend you review this useful Python-specific resource: -* `10 Unknown Security Pitfalls for Python `_ - By Dennis Brinkrolf - Sonar source blog +* `10 Unknown Security Pitfalls for Python`_ - By Dennis Brinkrolf - Sonar source blog + -.. [#] Wikipedia - `Software development security `_. +.. LINKS AND REFERENCES +.. include:: ../links.rst +.. [#] Wikipedia - Software development security https://en.wikipedia.org/wiki/Software_development_security +.. _10 Unknown Security Pitfalls for Python: https://blog.sonarsource.com/10-unknown-security-pitfalls-for-python +.. _camel case: https://en.wikipedia.org/wiki/Camel_case +.. _ImportError: https://docs.python.org/3/library/exceptions.html#ImportError +.. _Python Anti-Patterns\: using wildcard imports: https://docs.quantifiedcode.com/python-anti-patterns/maintainability/from_module_import_all_used.html diff --git a/doc/source/documentation_style/deployment.rst b/doc/source/documentation_style/deployment.rst index 1fdf0372c..4fea7c20a 100644 --- a/doc/source/documentation_style/deployment.rst +++ b/doc/source/documentation_style/deployment.rst @@ -1,14 +1,13 @@ -.. _documentation_deployment: - - Documentation Deployment ------------------------ -Documentation for the PyAnsys project is hosted via `GitHub Pages `_. -Given the open-source nature of the project, documentation built by each PyAnsys library or -project should be public and editable by users and the community at large. -After following the documentation build strategy contained within both -the `pyansys/template `_ and -`pyansys-sphinx-theme -`_ you will end up -with html documentation files in ``doc/build/html``. +Documentation for the PyAnsys project is hosted via `GitHub Pages`_ Given the +open-source nature of the project, documentation built by each PyAnsys library +or project should be public and editable by users and the community at large. + +After following the documentation build strategy contained within both the +`ansys-templates`_ and `pyansys-sphinx-theme`_ you will end up with html +documentation files in ``doc/build/html``. + +.. Links and References +.. include:: ../links.rst diff --git a/doc/source/documentation_style/docstrings.rst b/doc/source/documentation_style/docstrings.rst index 0c875096a..face1b9ef 100644 --- a/doc/source/documentation_style/docstrings.rst +++ b/doc/source/documentation_style/docstrings.rst @@ -1,19 +1,18 @@ -.. _docstrings: - Docstring Standards ################### -When writing docstrings for PyAnsys libraries, use the `numpydoc`_ -style, regardless as to whether you are using this Sphinx extension or the -`napoleon `_ Sphinx extension -to generate your library documentation. + +When writing docstrings for PyAnsys libraries, use the `numpydoc`_ style, +regardless as to whether you are using this Sphinx extension or the `napoleon`_ +Sphinx extension to generate your library documentation. You add the extension to use for documentation generation in your ``conf.py`` file. For example, to use `numpydoc`_, you would add: .. code:: python - extensions = ['numpydoc', - # other extensions + extensions = [ + 'numpydoc', + ... ] For consistency within PyAnsys libraries, always use ``"""`` to introduce and conclude a @@ -23,8 +22,8 @@ will have to resolve. A blank line signifies the start of a new paragraph. To create a bulleted or numbered list, ensure that there is a blank line before the first item and after the last item. Because you -use the same markup in docstrings as you do in RST files, see this `quick reference -`_. +use the same markup in docstrings as you do in RST files, see this `quick reference`_. + Surround any text that you want to set apart as literal text in double back ticks to render it in a monospace gold font. Use double back ticks to surround the names of files, folders, @@ -210,7 +209,7 @@ This will issue the following warning for any object without a docstring:: The ``"GL08"`` code is required at minimum for PyAnsys libraries. Other codes may be enforced at a later date. For a full listing, -see `Validation `_ +see `Docstring Validation`_ in the `numpydoc`_. @@ -222,5 +221,8 @@ that are not covered here. For example, you use the ``note::`` directive to high important information and the ``warning::`` directive to point out an action that might result in data loss. -.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html -.. _googledoc: https://google.github.io/styleguide/ +.. LINKS AND REFERENCES +.. include:: ../links.rst + +.. _quick reference: https://docutils.sourceforge.io/docs/user/rst/quickref.html +.. _Docstring Validation: https://numpydoc.readthedocs.io/en/latest/validation.html#validation diff --git a/doc/source/documentation_style/formatting-tools.rst b/doc/source/documentation_style/formatting-tools.rst index 7b58cf81c..ffde3ee08 100644 --- a/doc/source/documentation_style/formatting-tools.rst +++ b/doc/source/documentation_style/formatting-tools.rst @@ -88,13 +88,4 @@ under the ``[tool.pydocstyle]`` entry: [tool.pydocstyle] # Additional configuration - -.. _interrogate: https://interrogate.readthedocs.io/en/latest/ -.. _docstr-coverage: https://docstr-coverage.readthedocs.io/en/latest/index.html -.. _docstring-coverage: https://bitbucket.org/DataGreed/docstring-coverage/wiki/Home -.. _pytest-cov: https://pytest-cov.readthedocs.io/en/latest/ -.. _doctest: https://docs.python.org/3/library/doctest.html -.. _PEP 257: http://www.python.org/dev/peps/pep-0257/ -.. _docformatter: https://github.com/PyCQA/docformatter -.. _codespell: https://github.com/codespell-project/codespell -.. _pytest-cov: https://pytest-cov.readthedocs.io/en/latest/ +.. include:: ../links.rst diff --git a/doc/source/documentation_style/index.rst b/doc/source/documentation_style/index.rst index 56e24b6b3..cc74f50de 100644 --- a/doc/source/documentation_style/index.rst +++ b/doc/source/documentation_style/index.rst @@ -1,5 +1,3 @@ -.. _api_documentation: - API Documentation Style ####################### Good API documentation drives library adoption and usage and is the @@ -24,15 +22,14 @@ The documentation for a PyAnsys library should contain: * Module, class, method, and function docstrings. See :ref:`docstrings`. -* Full gallery of examples. See `PyMAPDL Examples - `_. +* Full gallery of examples. See `PyMAPDL Examples`_. * Developer's guide for the library. * Link to this developer's guide. Finally, the documentation should be public and hosted via gh-pages, either as a branch named ``gh-pages`` within the library repository or within a ``gh-pages`` branch within ``-docs``. For more information, -see :ref:`documentation_deployment`. +see :ref:`Documentation Deployment`. .. toctree:: :hidden: @@ -42,3 +39,6 @@ see :ref:`documentation_deployment`. class_documentation deployment formatting-tools + +.. Links and References +.. include:: ../links.rst diff --git a/doc/source/guidelines/dev_practices.rst b/doc/source/guidelines/dev_practices.rst index b39d22ac0..1384acb13 100644 --- a/doc/source/guidelines/dev_practices.rst +++ b/doc/source/guidelines/dev_practices.rst @@ -1,20 +1,18 @@ -.. _development_practices: - Development Practices ===================== This page explains how PyAnsys development is conducted. When contributing to a PyAnsys repository, use these general coding paradigms: -#. Follow the `Zen of Python `__. +#. Follow the `Zen of Python`_. As silly as core Python developers are sometimes, there's much to be gained by following the basic guidelines listed in PEP 20. As suggested in these guidelines, focus on making your additions intuitive, novel, and helpful for PyAnsys users. When in doubt, use ``import this``. - For Ansys code quality standards, see :ref:`coding_style`. + For Ansys code quality standards, see :ref:`Coding Style`. #. Document your contributions. Include a docstring for any added - function, method, or class, following `numpydocs docstring `_ + function, method, or class, following `numpydoc` docstring guidelines and PyAnsys documentation standards <#Documentation Standards>. Always provide at least one simple use case for a new feature. @@ -22,30 +20,30 @@ coding paradigms: it's not tested, it's probably broken. At the minimum, include a unit test for each new feature within the ``tests`` directory. Ensure that each new method, class, or function has reasonable (>80%) coverage. - See `Testing <#Testing>`__ for automating testing. + See :ref:`Testing` for automating testing. #. Do not include any datasets for which a license is not available or commercial use is prohibited. -#. Review our `Code of Conduct `_. +#. Review our `Code of Conduct`_. Contributing Through GitHub --------------------------- To submit new code to a PyAnsys repository: -#. `Fork `_ +#. `Fork`_ the respective GitHub repository and then clone the forked repository to your computer. -#. In your local repository, create a branch. See :ref:`branch_naming`. +#. In your local repository, create a branch. See :ref:`Branch Naming Conventions`. Comprehensive information on our model for branching is available in - `Branching Model <#Branching Model>`__. + ref:`Branching Model`. #. Add your new feature and commit it locally. Be sure to commit frequently as the ability to revert to past commits is often helpful, especially if your change is complex. -#. Test often. See `Testing <#Testing>`__ for automating testing. +#. Test often. See ref:`Testing` for automating testing. #. When you are ready to submit your code, create a pull request (PR) by following the steps in the next section. @@ -66,7 +64,6 @@ If your PR branch is a ``fix/`` branch, do not delete it because it may be neces merge your PR branch with the current release branch. The next section explains our branch naming conventions. -.. _branch_naming: Branch Naming Conventions ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -109,12 +106,12 @@ any new issues from your changes. Error Messages ~~~~~~~~~~~~~~ For general information on writing good error messages, see Microsoft's -`Error Message Guidelines `_. +`Error Message Guidelines` `_. For information specific to writing Pythonic error messages, see: -- `Python Exception Handling `_ -- `7 Tips to Improve Your Error Handling in Python `_ +- `Python Exception Handling`_ +- `7 Tips to Improve Your Error Handling in Python`_ Additionally, ensure that you have reviewed this guide's :ref:`logging` topic. @@ -143,7 +140,7 @@ While the source and content for each library's documentation differs, the docum itself is generated from three sources: - Docstrings from the library's classes, functions, and modules using - `sphinx.ext.autodoc `_. + `sphinx.ext.autodoc`. - reStructuredText (RST) files from ``doc/`` - Examples from ``examples/`` @@ -153,7 +150,7 @@ that are meant to be run as individual downloadable scripts are provided in PY f placed in ``examples/``. For comprehensive documentation guidelines, including how to build documentation locally, -see :ref:`doc_practices`. +see :ref:`API Documentation Style`. Continuous Integration and Continuous Delivery (CI/CD) ------------------------------------------------------ @@ -168,13 +165,12 @@ tasks: - Spelling and style verification - Documentation build -.. _branching_model: Branching Model --------------- The branching model for a PyAnsys project enables rapid development of features without sacrificing stability. The model closely follows the -`Trunk Based Development `_ approach: +`Trunk Based Development`_ approach: - The ``main`` branch is the primary development branch. All features, patches, and other branches should be merged here. While all PRs @@ -215,7 +211,7 @@ Create a new branch from the ``main`` branch with the name #. Update the version numbers in ``ansys///_version.py`` to be: ``MAJOR.MINOR.0``. Remove the ``dev0`` suffix. -#. Locally run all tests as outlined in `Testing <#Testing>`_ and +#. Locally run all tests as outlined in :ref:`Testing` and ensure that all are passing. #. Locally test and build the documentation with link checking to @@ -266,9 +262,6 @@ this file. The version must include the ``.dev0`` suffix. Push the branch to GitHub and create a new PR for this release that merges it to ``main``. While effort is focused on the release, development to ``main`` should be limited. -.. _GitHub Releases: https://docs.github.com/en/github/administering-a-repository/releasing-projects-on-github/managing-releases-in-a-repository -.. _GitHub's compare feature: https://github.com/pyansys/pymapdl/compare - Patch Release Steps ~~~~~~~~~~~~~~~~~~~ @@ -294,3 +287,10 @@ should not wait until a minor release. These are the steps for a patch release: #. If deemed necessary, create and add release notes as described in the previous section. + +.. LINKS AND REFERENCES +.. include:: ../links.rst + +.. _Error Message Guidelines: https://docs.microsoft.com/en-us/windows/win32/debug/error-message-guidelines +.. _Python Exception Handling: https://www.codementor.io/sheena/python-exception-handling-ogr0a41t7>`_ +.. _7 Tips to Improve Your Error Handling in Python: https://pybit.es/articles/pythonic-exceptions/>`_ diff --git a/doc/source/guidelines/doc_practices.rst b/doc/source/guidelines/doc_practices.rst index b367023f9..31b5053f5 100644 --- a/doc/source/guidelines/doc_practices.rst +++ b/doc/source/guidelines/doc_practices.rst @@ -1,7 +1,6 @@ -.. _doc_practices: - Documentation Practices ======================= + PyAnsys documentation must not only be written but also maintained. If you are new to writing developer documentation, see the `Google Developer Documentation Style Guide `_. It provides @@ -20,10 +19,8 @@ code: Understanding Documentation Sources ------------------------------------ -The generation of PyAnsys documentation uses `Sphinx -`__ and an Ansys-branded theme -(`pyansys-sphinx-theme `_) to -assemble content in: +The generation of PyAnsys documentation uses `Sphinx`_ and an Ansys-branded +theme (`pyansys-sphinx-theme`_) to assemble content in: - Docstrings - reStructuredText (RST) files @@ -34,13 +31,13 @@ Docstrings Docstrings must be formatted so that Sphinx can parse them. You can use either of these Sphinx extensions: - - `numpydoc `_ - - `napoleon `_ + - `numpydoc`_ + - `napoleon`_ The ``numpydoc`` extension is generally preferred because it supports an API documentation structure with one page per method, providing Python community -members with documentation like that generated by `pandas `_ -and `NumPy `_. If, however, your API is very linear, you +members with documentation like that generated by `pandas`_ +and `NumPy`_. If, however, your API is very linear, you might prefer the ``napoleon`` extension because it supports a documentation structure where everything needed to solve a certain problem can be shown on one page. @@ -48,12 +45,12 @@ The ``numpydoc`` extension provides its own `style guide `_ and a `user guide `_ that explains how to use the extension with Sphinx. The ``napoleon`` extension, which parses both numpy and -Google style docstrings, refers you to the `Google Python Style Guide -`_. +Google style docstrings, refers you to the `Google Python Style Guide`_ + Regardless of the extension that you choose for generating documentation, we recommend the use of numpy-style docstrings so that there is consistency -across PyAnsys libraries. For more information, see :ref:`api_documentation`. +across PyAnsys libraries. For more information, see :ref:`API Documentation Style`. RST Files ~~~~~~~~~ @@ -125,11 +122,12 @@ PEP 8-compliant, are compiled dynamically during the build process. Always ensure that your examples run properly locally because they will be verified through the CI performed via GitHub Actions. -Adding a new standalone example consists of placing it in an applicable subdirectory in the ``examples`` -directory. If none of the existing directories match the category of your example, create -a new subdirectory with a ``README.txt`` file describing the new category. Because these examples -are built using the `Sphinx-Gallery `_ -extension, you must follow its `coding guidelines `_. +Adding a new standalone example consists of placing it in an applicable +subdirectory in the ``examples`` directory. If none of the existing directories +match the category of your example, create a new subdirectory with a +``README.txt`` file describing the new category. Because these examples are +built using the `Sphinx-Gallery`_ extension, you must follow its `coding +guidelines `_. PyMAPDL provides a self-demonstrating example of how to `add an example reference key `_. @@ -172,7 +170,7 @@ up-to-date via GitHub actions. To make documentation changes, you create a branch with a name that begins with a prefix of ``doc/`` that is then followed by a short description of what you are changing. For more -information, see :ref:`branch_naming`. +information, see :ref:`Branch Naming Conventions`. As you are making changes in this branch, you want to periodically generate the documentation locally so that you can test your changes before you create a GitHub pull request. For more @@ -194,7 +192,7 @@ To use Windows PowerShell to clone a GitHub repository: #. In Windows PowerShell, navigate to the directory on your machine where you want to clone GitHub repositories. -#. Go to the `PyAnsys GitHub account `_ and select the +#. Go to the `PyAnsys GitHub Organization`_ and select the repository that you want to clone. Because the list of repositories is quite long, you can use the ``Find @@ -364,22 +362,21 @@ Anaconda provides Python and tools, such as a Python IDE (Interactive Developmen a Python command line editor, and Sphinx dependencies. This gives you what you need to get up and running. -#. Install the `Anaconda individual edition `_. +#. Install the `Anaconda Individual Edition`_. #. If a PyAnsys library already exists, create a directory in which to place a clone of its GitHub repository. -#. Clone the PyAnsys library's GitHub repository. For more information, see :ref:`cloning`. +#. Clone the PyAnsys library's GitHub repository. For more information, see :ref:`Cloning`. -#. If you have not yet cloned the `pyansys-sphinx-theme `_ - repository, clone it. +#. If you have not yet cloned the `pyansys-sphinx-theme`_ repository, clone it. Installing Build Requirements ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can build documentation for the `dev_guide `_ -and `pyansys-sphinx-theme `_ repositories without -installing a PyAnsys library in development mode. However, for many other PyAnsys libraries, when -you push changes that you have made in a local branch to the library's GitHub repository, CI checks -typically require that the full library is installed. +You can build documentation for the `Developer's Guide` and +`pyansys-sphinx-theme`_ repositories without installing a PyAnsys library in +development mode. However, for many other PyAnsys libraries, when you push +changes that you have made in a local branch to the library's GitHub repository, +CI checks typically require that the full library is installed. #. In Anaconda PowerShell, navigate to the base directory in the library's cloned repository. @@ -449,7 +446,7 @@ release notes for a version. On Linux, building this PDF can be done by followin `these directions `_. On Windows, building a PDF is a manual process that you run locally: -#. Install `MiKTeX `_ for Windows, selecting the +#. Install `MiKTeX`_ for Windows, selecting the recommended option for installing it for only your own use. #. From the Windows Start menu, start the MiKTeX Console. @@ -494,7 +491,7 @@ On Windows, building a PDF is a manual process that you run locally: Continuous Documentation Deployment ----------------------------------- PyAnsys libraries deploy their documentation online via `GitHub Actions`_ to -`GitHub Pages`_. For example, this documentation is hosted on the `gh-pages`_ +`GitHub Pages`_. For example, this documentation is hosted on the ``gh-pages`` branch within this repository. This is done by uploading the generated documentation within the ``doc/_build/html/`` directory directly to the ``gh-pages`` branch and then `enabling GitHub pages`_. @@ -731,20 +728,5 @@ GitHub release with:: ./**/*.tar.gz ./**/*.pdf -.. - Links - -.. _GitHub Pages: https://pages.github.com/ -.. _GitHub Actions: https://github.com/features/actions -.. _PyMAPDL Documentation: https://mapdldocs.pyansys.com/ -.. _pyansys/pymapdl-docs: https://github.com/pyansys/pymapdl-docs -.. _gh-pages: https://github.com/pyansys/dev-guide/tree/gh-pages -.. _enabling GitHub pages: https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site#creating-your-site -.. _tox: https://github.com/tox-dev/tox -.. _PyAnsys DNS Zones: https://portal.azure.com/#@ansys.com/resource/subscriptions/2870ae10-53f8-46b1-8971-93761377c38b/resourceGroups/pyansys/providers/Microsoft.Network/dnszones/pyansys.com/overview -.. _Maxime Rey: https://teams.microsoft.com/l/chat/0/0?users=maxime.rey@ansys.com -.. _Roberto Pastor Muela: https://teams.microsoft.com/l/chat/0/0?users=roberto.pastormuela@ansys.com -.. _Alex Kaszynski: https://teams.microsoft.com/l/chat/0/0?users=alexander.kaszynski@ansys.com -.. _PyAnsys Bot: https://github.com/apps/pyansys-bot -.. _PyAnsys Organization: https://github.com/pyansys -.. _ansys-templates: https://github.com/pyansys/ansys-templates +.. Links and References +.. include:: ../links.rst diff --git a/doc/source/guidelines/test_practices.rst b/doc/source/guidelines/test_practices.rst index 378dba6e7..b2fadd8e6 100644 --- a/doc/source/guidelines/test_practices.rst +++ b/doc/source/guidelines/test_practices.rst @@ -57,8 +57,6 @@ from other applications or libraries. For Python tool libraries like `ansys-tools-protoc-helper`_, unit testing is sufficient to get high coverage (> 80%) of your library while actually testing the library. -.. _ansys-tools-protoc-helper: https://github.com/ansys/ansys-tools-protoc-helper - These tests should be written to test a single method in isolation. For example, if you have a method that deserializes chunks: @@ -281,11 +279,10 @@ and integration testing is complete, and they should be run outside the 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 in the ``tests`` -directory in the library's root directory:: +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 in the ``tests`` directory +in the library's root directory:: tests/ test_basic.py @@ -347,7 +344,7 @@ Given that Python is an interpreted language, developers of Python libraries should aim to have high coverage for their libraries as only syntax errors can be caught during the almost trivial compile time. Coverage is defined as parts of the executable and usable source that are tested by unit tests. You can use -the `pytest-cov `_ library to view the +the `pytest-cov`_ library to view the coverage for your library. For example:: $ pytest --cov numpydoc_validation @@ -395,9 +392,8 @@ Code Coverage Enforcement ~~~~~~~~~~~~~~~~~~~~~~~~~ One way of enforcing unit test coverage with a project on GitHub is to use the codecov.io to enforce minimum patch (and optionally project) coverage. As this -application is already available to the `PyAnsys Organization -`_, simply add the following to the root directory -of your repository: +application is already available to the `PyAnsys GitHub Organization`_, simply add the +following to the root directory of your repository: **/codecov.yml** @@ -442,12 +438,10 @@ multiple platforms, or even unit testing in general. However, with the right automated CI/CD, such testing can still occur and be enforced automatically. `GitHub Actions`_ is the preferred automated CI/CD platform for running Python -library unit tests for PyAnsys, and it can be used immediately by cloning the -project `template `_. If you are +library unit tests for PyAnsys, and it ships by default with the +``pyansys-advanced`` template in the project `ansys-templates`_ tool. If you are unfamiliar with GitHub Actions, see `GitHub Actions`_ for an overview. -.. _GitHub Actions: https://github.com/features/actions - The following sections describe the usage of a simple GitHub workflow for a PyAnsys library: @@ -551,6 +545,6 @@ Optionally, though highly recommended, upload your unit test coverage to - uses: codecov/codecov-action@v2 name: 'Upload coverage to Codecov' -.. _Test driven development: https://en.wikipedia.org/wiki/Test-driven_development -.. _codecov.io: https://app.codecov.io/gh/pyansys -.. _poetry: https://python-poetry.org + +.. Links and References +.. include:: ../links.rst diff --git a/doc/source/guidelines/version_support.rst b/doc/source/guidelines/version_support.rst index b9a990f2e..bb9a4a255 100644 --- a/doc/source/guidelines/version_support.rst +++ b/doc/source/guidelines/version_support.rst @@ -19,8 +19,8 @@ of 2022: +---------+-------------+-----------------------+ Expect these to be the most commonly used Python versions. Note that some -libraries like `NumPy `_ drop support for older versions of -Python earlier than their end of life (EOL) as outlined in `NEP 29 +libraries like `NumPy`_ drop support for older versions of +Python earlier than their end of life (EOL) as outlined in `NEP 29`_ `_. Realize that users can still install the older version from PyPI via ``pip`` as @@ -73,3 +73,5 @@ would would start with:: run: | ... +.. Links and References +.. include:: ../links.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index 81b182d26..c5f7229a2 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -13,3 +13,5 @@ coding_style/index documentation_style/index abstractions/index + +.. include:: links.rst diff --git a/doc/source/links.rst b/doc/source/links.rst new file mode 100644 index 000000000..642193217 --- /dev/null +++ b/doc/source/links.rst @@ -0,0 +1,154 @@ +.. ANSYS PROJECTS +.. _ansys-api-mapdl: https://pypi.org/project/ansys-api-mapdl/ +.. _ansys-tools-protoc-helper: https://github.com/ansys/ansys-tools-protoc-helper + +.. PYANSYS PROJECTS +.. _PyAnsys: https://docs.pyansys.com/ +.. _PyAnsys PyPI: https://pkgs.dev.azure.com/pyansys/_packaging/pyansys/pypi +.. _PyAnsys GitHub Organization: https://github.com/pyansys +.. _pyansys.support@ansys.com: mailto:pyansys.support@ansys.com +.. _ansys-templates: https://templates.pyansys.com/index.html +.. _pyansys-protos-generator: https://github.com/pyansys/pyansys-protos-generator +.. _grpc_chunk_stream_demo: https://github.com/pyansys/grpc_chunk_stream_demo +.. _PyAEDT: https://github.com/pyansys/pyaedt +.. _PyMAPDL: https://github.com/pyansys/pymapdl +.. _DPF-Core: https://numpy.org/neps/nep-0029-deprecation_policy.html#support-table +.. _DPF-Post: https://github.com/pyansys/DPF-Post +.. _Legacy PyMAPDL Reader: https://github.com/pyansys/pymapdl-reader +.. _system-reporting-tool: https://github.com/pyansys/system-reporting-tool +.. _example-coverage: https://github.com/pyansys/example-coverage +.. _pyansys project developer's guide: https://github.com/pyansys/about +.. _pyansys-sphinx-theme: https://github.com/pyansys/pyansys-sphinx-theme +.. _PyAnsys Organization: https://github.com/pyansys +.. _PyAnsys Bot: https://github.com/apps/pyansys-bot +.. _PyAnsys DNS Zones: https://portal.azure.com/#@ansys.com/resource/subscriptions/2870ae10-53f8-46b1-8971-93761377c38b/resourceGroups/pyansys/providers/Microsoft.Network/dnszones/pyansys.com/overview + +.. PYANSYS PROJECTS DOCUMENTATION +.. _PyMAPDL Documentation: https://mapdldocs.pyansys.com/ +.. _pyansys/pymapdl-docs: https://github.com/pyansys/pymapdl-docs +.. _CODE OF CONDUCT: https://github.com/pyansys/.github/blob/main/CODE_OF_CONDUCT.md + +.. PYANSYS PROJECTS ISSUES BOARDS +.. _PyAEDT Issues: https://github.com/pyansys/pyaedt/issues +.. _PyDPF-Core Issues: https://github.com/pyansys/pydpf-core/issues +.. _PyDPF-Post Issues: https://github.com/pyansys/pydpf-post/issues +.. _PyMAPDL Discussions: https://github.com/pyansys/pymapdl/discussions +.. _PyMAPDL Issues: https://github.com/pyansys/pymapdl/issues +.. _PyMAPDL Examples: https://mapdldocs.pyansys.com/examples/index.html +.. _PyMAPDL-Reader Issues: https://github.com/pyansys/pymapdl-reader/issues +.. _OpenAPI Common Issues: https://github.com/pyansys/openapi-common/issues +.. _Granta MI BoM Analytics Issues: https://github.com/pyansys/grantami-bomanalytics/issues + +.. BUILD-SYSTEMS +.. _flit: https://flit.readthedocs.io/en/latest/ +.. _poetry: https://python-poetry.org +.. _setuptools: https://setuptools.pypa.io/en/latest/index.html + +.. CODE FORMATTING AND QUALITY TOOLS +.. _black: https://black.readthedocs.io/en/stable/ +.. _flake8: https://flake8.pycqa.org/en/latest/index.html +.. _pre-commit: https://pre-commit.com/ +.. _pycodestyle: https://pypi.org/project/pycodestyle/ +.. _pyflakes: https://pypi.org/project/pyflakes/ + +.. DOCUMENTATION TOOLS +.. _codespell: https://github.com/codespell-project/codespell +.. _docformatter: https://github.com/PyCQA/docformatter +.. _docstr-coverage: https://docstr-coverage.readthedocs.io/en/latest/index.html +.. _docstring-coverage: https://bitbucket.org/DataGreed/docstring-coverage/wiki/Home +.. _doctest: https://docs.python.org/3/library/doctest.html +.. _googledoc: https://google.github.io/styleguide/ +.. _interrogate: https://interrogate.readthedocs.io/en/latest/ +.. _mccabe: https://github.com/PyCQA/mccabe +.. _MiKTeX: https://miktex.org/download +.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html +.. _reStructuredText Markup Syntax: https://docutils.sourceforge.io/rst.html +.. _sphinx: https://www.sphinx-doc.org/en/master/ +.. _sphinx-gallery: https://sphinx-gallery.github.io/ +.. _PyAnsys Sphinx Theme Documentation: https://github.com/pyansys/pyansys-sphinx-theme +.. _gRPC Hello-world Example: https://github.com/pyansys/pyansys-helloworld +.. _Material Example Data: https://github.com/pyansys/example-data +.. _napoleon: https://pypi.org/project/sphinxcontrib-napoleon/ +.. _Google Python Style Guide: https://google.github.io/styleguide/pyguide.html +.. _sphinx.ext.autodoc: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html + +.. FLAKE8 RULE CODES +.. _E115: https://www.flake8rules.com/rules/E115.html +.. _E117: https://www.flake8rules.com/rules/E117.html +.. _E122: https://www.flake8rules.com/rules/E122.html +.. _E124: https://www.flake8rules.com/rules/E124.html +.. _E125: https://www.flake8rules.com/rules/E125.html +.. _E225: https://www.flake8rules.com/rules/E225.html +.. _E231: https://www.flake8rules.com/rules/E231.html +.. _E301: https://www.flake8rules.com/rules/E301.html +.. _E303: https://www.flake8rules.com/rules/E303.html +.. _E501: https://www.flake8rules.com/rules/E501.html +.. _F401: https://www.flake8rules.com/rules/F401.html +.. _F403: https://www.flake8rules.com/rules/F403.html +.. _W191: https://www.flake8rules.com/rules/W191.html +.. _W291: https://www.flake8rules.com/rules/W291.html +.. _W293: https://www.flake8rules.com/rules/W293.html +.. _W391: https://www.flake8rules.com/rules/W391.html + +.. GIT AND GITHUB +.. _enabling GitHub pages: https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site#creating-your-site +.. _fork: https://docs.github.com/en/get-started/quickstart/fork-a-repo +.. _GitHub Actions: https://github.com/features/actions +.. _GitHub's compare feature: https://github.com/pyansys/pymapdl/compare +.. _GitHub Pages: https://pages.github.com/ +.. _GitHub Releases: https://docs.github.com/en/github/administering-a-repository/releasing-projects-on-github/managing-releases-in-a-repository +.. _Semantic Versioning: https://semver.org/ +.. _Trunk Based Development: https://trunkbaseddevelopment.com/ +.. _repository visibility: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility + +.. LICENSES +.. _MIT License: https://opensource.org/licenses/MIT + +.. DEVELOPERS AND MAINTAINERS +.. _Maxime Rey: https://teams.microsoft.com/l/chat/0/0?users=maxime.rey@ansys.com +.. _Roberto Pastor Muela: https://teams.microsoft.com/l/chat/0/0?users=roberto.pastormuela@ansys.com +.. _Alex Kaszynski: https://teams.microsoft.com/l/chat/0/0?users=alexander.kaszynski@ansys.com + +.. PYTHON ECOSYSTEM AND LIBRARIES +.. _Anaconda Individual Edition: https://www.anaconda.com/products/individual +.. _PyPI: https://pypi.org/ +.. _Python Packaging Authority: https://www.pypa.io/en/latest/ +.. _Python Packaging User Guide: https://packaging.python.org/en/latest/ +.. _pip: https://pip.pypa.io/en/latest/ + +.. THIRD PARTY LIBRARIES +.. _deprecation: https://deprecation.readthedocs.io/en/latest/ +.. _matplotlib: https://matplotlib.org/ +.. _numpy: https://numpy.org/ +.. _pandas: https://pandas.pydata.org/ +.. _pyvista: https://docs.pyvista.org/ +.. _scipy: https://scipy.org/ +.. _tensorflow: + +.. PYTHON ENHANCEMENT PROPOSAL (PEP) +.. _PEP 8: https://peps.python.org/pep-0008/ +.. _PEP 20: https://peps.python.org/pep-0020/ +.. _Zen Of Python: https://www.python.org/dev/peps/pep-0020/ +.. _PEP 257: https://peps.python.org/pep-0257/ +.. _PEP 420: https://peps.python.org/pep-0420/ +.. _PEP 517: https://peps.python.org/pep-0517/ +.. _PEP 518: https://peps.python.org/pep-0518/ + +.. NUMPY ENHANCEMENT PROPOSAL (NEP) +.. _NEP 29: https://numpy.org/neps/nep-0029-deprecation_policy.html#support-table + +.. COMMON TECHNOLOGIES +.. _gRPC: https://grpc.io/ +.. _rest: https://en.wikipedia.org/wiki/Representational_state_transfer +.. _SWIG: http://www.swig.org/ + +.. UNIT TESTING AND CI TOOLS +.. _codecov.io: https://app.codecov.io/gh/pyansys +.. _dependabot: https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/about-dependabot-version-updates +.. _GitHub Actions: https://github.com/features/actions +.. _GitHub Releases: https://docs.github.com/en/github/administering-a-repository/releasing-projects-on-github/managing-releases-in-a-repository +.. _pytest: https://docs.pytest.org/en/latest/ +.. _pytest-cov: https://pytest-cov.readthedocs.io/en/latest/ +.. _Test Driven Development: https://en.wikipedia.org/wiki/Test-driven_development +.. _Tox: https://tox.wiki/en/latest/ +.. _unittest: https://docs.python.org/3/library/unittest.html diff --git a/doc/source/overview/administration.rst b/doc/source/overview/administration.rst index 9371875a3..037155566 100644 --- a/doc/source/overview/administration.rst +++ b/doc/source/overview/administration.rst @@ -1,4 +1,3 @@ -###################### Project Administration ###################### @@ -15,15 +14,14 @@ To allow for commercial use, a PyAnsys library must use the MIT license. Because this license falls in the BSD-style license class, PyAnsys libraries can be used as a shared library with no restrictions. This follows the pattern of including PyAnsys as a -dependency in ``install_requires`` in the ``setup.py`` file. +dependency in ``install_requires`` in :ref:`The \`\`setup.py\`\` file`. Should you choose to copy and include any PyAnsys project source uses, to make your library suitable for commercial use, you need only a copy -of the original PyAnsys MIT license in the reused code. +of the original PyAnsys `MIT License`_ in the reused code. -To view this license, see the `LICENSE `_ file in the root directory -of this repository. This file must be included in the root -directory of the repository of every PyAnsys library. +To view this license, see `The \`\`LICENSE\`\` File` section. This file must be +included in the root directory of the repository of every PyAnsys library. Project Approval ================ @@ -31,7 +29,6 @@ Exposing new Ansys technologies through the PyAnsys project is subject to an internal review and decision process. Please reach out to Stephane Marguerin or Alexander Kaszynski for any requests. -.. _repository_management: Repository Management and Standards =================================== @@ -43,13 +40,12 @@ description, or branch protection management. Each repository is expected to follow this minimum set of standards: -- PEP8 code standards. See :ref:`best_practices`. +- PEP8 code standards. See :ref:`PEP 8 Best Practices`. - CI/CD using GitHub actions or Azure DevOps to enforce coding standards. - Publicly hosted documentation describing the API and providing examples. See - :ref:`api_documentation`. + :ref:`API Documentation Style`. - Unit testing with at least 80% test coverage. -- Infrastructure in place to deploy the library as a package on `PyPi - `_. See :ref:`Packaging Style`. +- 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`. @@ -71,12 +67,6 @@ be released with major, globally-breaking API changes. This matches the versioning methodology for the "big three" data science python libraries: `NumPy`_, `SciPy`_, and `pandas`_. -.. _Semantic Versioning: https://semver.org/ -.. _NumPy: https://numpy.org/ -.. _SciPy: https://www.scipy.org/ -.. _pandas: https://pandas.pydata.org/ - - Release Definition ------------------ @@ -108,13 +98,16 @@ Release Management A release may be a major, minor, or patch release depending on the features, changes, or bug fixes to be released. -For more information, see :ref:`release_procedures`. +For more information, see :ref:`Release Procedures`. Product Version Matching ------------------------ PyAnsys libraries should not match product versions. For example, the -PyMAPDL library ``ansys-mapdl-core`` might have the version ``0.59.0`` +`PyMAPDL`_ library ``ansys-mapdl-core`` might have the version ``0.59.0`` whereas the product version is 21.2 (2021 R2). The reason behind this is PyAnsys libraries are expected to be developed outside the product release cycle in a rapid CI/CD manner. + +.. LINKS AND REFERENCES +.. include:: ../links.rst diff --git a/doc/source/overview/basic.rst b/doc/source/overview/basic.rst index 609638eba..d74241c98 100644 --- a/doc/source/overview/basic.rst +++ b/doc/source/overview/basic.rst @@ -2,32 +2,31 @@ PyAnsys Project Organization ############################ -The PyAnsys project is hosted on GitHub at `PyAnsys -`_. It contains several repositories with -Python libraries that interface with Ansys products or services. -To try out a library, visit one of these links: +The PyAnsys project is hosted on GitHub at `PyAnsys`_. It contains several +repositories with Python libraries that interface with Ansys products or +services. To try out a library, visit one of these links: -* `PyAnsys Project `_ +* `PyAnsys`_ Project * `PyMAPDL`_ * `PyAEDT`_ -* `DPF-Core `_ -* `DPF-Post `_ -* `Legacy PyMAPDL Reader `_ +* `DPF-Core`_ +* `DPF-Post`_ +* `Legacy PyMAPDL Reader`_ If you want to create, develop, or contribute to a PyAnsys library, visit these links: -* `PyAnsys Project Developer's Guide `_ -* `PyAnsys Sphinx Theme Documentation `_ -* `gRPC Hello-world Example `_ -* `Material Example Data `_ +* `PyAnsys Project Developer's Guide`_ +* `PyAnsys Sphinx Theme Documentation`_ +* `gRPC Hello-world Example`_ +* `Material Example Data`_ Using the following tools, developers generate library packages from PROTO files, create coverage reports, and report on system coverage: -* `pyansys-protos-generator `_ -* `example-coverage `_ -* `system-reporting-tool `_ +* `pyansys-protos-generator`_ +* `example-coverage`_ +* `system-reporting-tool`_ ################# Quick Start Guide @@ -37,15 +36,16 @@ This is a brief overview on how to get started right away with your own PyAnsys repository on the `PyAnsys GitHub Organization`_. A repository is generally a project for a particular PyAnsys library. -#. **Create the repository:** Create a repository from the - `pyansys/template`_. See `Creating a repository from a template`_. - Be sure that the `repository visibility`_ is initially private. +#. **Create a new project:** take advantage of the `ansys-templates`_ tool for + this task. + +#. **Create the repository:** push previously generated project. Be sure that + the `repository visibility`_ is initially private. -#. **Rename the package:** Rename ``ansys/product/library`` to match - your product or library. For example, the package name for - PyMAPDL is ``ansys/mapdl/core``. Do the - same renaming in ``setup.py``. Do this as a pull request. In fact, only add - code as pull requests. Do not push to ``main``.) +#. **Rename the package:** Rename ``ansys/product/library`` to match your + product or library. For example, the package name for PyMAPDL is + ``ansys/mapdl/core``. Do the same renaming in ``setup.py``. Do this as a pull + request. In fact, only add code as pull requests. Do not push to ``main``.) #. **Add source:** Add your source files to ``ansys//`` or create them. Also add unit tests to @@ -59,10 +59,10 @@ project for a particular PyAnsys library. #. **Update documentation:** The documentation source and content will vary from repository to _repository. In ``doc/``, there are folders for different types of documentation, which can include guides, examples, - and API. Ensure that all documentation is updated. See :ref:`api_documentation`. + and API. Ensure that all documentation is updated. See :ref:`API Documentation Style`. #. **Prepare the package for release:** When you are ready to release - your package publicly, email `pyansys.support@ansys.com `_ + your package publicly, email `pyansys.support@ansys.com`_ to obtain the release checklist for obtaining official Ansys approval. Once you have completed this checklist, change the `repository visibility`_ to public and create a release branch. @@ -80,11 +80,6 @@ project for a particular PyAnsys library. Others like requests, RPC, COM, etc. -.. _PyAEDT: https://github.com/pyansys/PyAEDT -.. _PyMAPDL: https://github.com/pyansys/pymapdl -.. _pytest-cov: https://pytest-cov.readthedocs.io/en/latest/reporting.html -.. _pyansys/template: https://github.com/pyansys/template -.. _Creating a repository from a template: https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template -.. _repository visibility: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility -.. _PyAnsys GitHub Organization: https://github.com/pyansys -.. _pytest: https://pytest.org/ + +.. Links and References +.. include:: ../links.rst diff --git a/doc/source/overview/contributing.rst b/doc/source/overview/contributing.rst index fa630f214..df5e3dc39 100644 --- a/doc/source/overview/contributing.rst +++ b/doc/source/overview/contributing.rst @@ -1,4 +1,3 @@ -############ Contributing ############ @@ -33,19 +32,18 @@ team will use discretion as to whether to close it. Should it turn out that your issue is closed erroneously, perhaps because a bug fix implemented to resolve your issue did not work, you can re-open it with a comment that explains why you have done so. If you need to contact the PyAnsys -project support team directly, email `pyansys.support@ansys.com -`_. +project support team directly, email `pyansys.support@ansys.com`_. For convenience, here are URLs for ``Issues`` pages for the public PyAnsys repositories: -- `PyAEDT Issues `_ -- `PyDPF-Core Issues `_ -- `PyDPF-Post Issues `_ -- `PyMAPDL Issues `_ -- `PyMAPDL-Reader Issues `_ -- `OpenAPI Common Issues `_ -- `Granta MI BoM Analytics Issues `_ +- `PyAEDT Issues`_ +- `PyDPF-Core Issues`_ +- `PyDPF-Post Issues`_ +- `PyMAPDL Issues`_ +- `PyMAPDL-Reader Issues`_ +- `OpenAPI Common Issues`_ +- `Granta MI BoM Analytics Issues`_ Submitting Questions -------------------- @@ -80,9 +78,9 @@ Contributing New Code ===================== When you are ready to start contributing code, see: -- :ref:`development_practices` for information on how PyAnsys development is +- :ref:`Development Practices` for information on how PyAnsys development is conducted -- :ref:`best_practices` for information on how to style and format your +- :ref:`PEP 8 Best Practices` for information on how to style and format your code to adhere to PyAnsys standards @@ -93,7 +91,7 @@ Starting Discussions For general questions about development practices, you should create discussions rather than issues. Each PyAnsys repository has its own ``Discussions`` page. For example, to ask a question about a PyMAPDL development practice, you would -create a discussion on the `PyMAPDL Discussions `_ +create a discussion on the `PyMAPDL Discussions`_ page. It is possible for discussions to lead to the creation of issues. .. note:: @@ -128,10 +126,8 @@ you would run the following: If you want to eventually push a contribution to a PyAnsys repository, consider creating a `fork`_ of the repository. For information on how to contribute -through GitHub, see :ref:`development_practices`, paying particular attention -to :ref:`branch_naming` when you are ready to create a pull request. - -.. _fork: https://docs.github.com/en/get-started/quickstart/fork-a-repo +through GitHub, see :ref:`Development Practices`, paying particular attention +to :ref:`Branch Naming Conventions` when you are ready to create a pull request. Licensing ========= @@ -143,3 +139,6 @@ If you did not write the code that you are contributing yourself, it is your responsibility to ensure that the existing license for this code is compatible and included in the contributed files. You must obtain permission from the original author to relicense the code. + +.. LINKS AND REFERENCES +.. include:: ../links.rst diff --git a/doc/source/overview/index.rst b/doc/source/overview/index.rst index 4acb9bc35..02ed1a6ad 100644 --- a/doc/source/overview/index.rst +++ b/doc/source/overview/index.rst @@ -22,12 +22,12 @@ These libraries play a vital role in: The libraries also include plugins and interfaces to the vast Python ecosystem. Examples include: -- Arrays using `NumPy `_ -- Data structures and tables with `pandas `_ -- 2D visualization using `Matplotlib `_ -- 3D visualization using `PyVista `_ -- Advanced scientific computing using `SciPy `_ -- Machine learning using `TensorFlow `_ +- Arrays using `NumPy`_ +- Data structures and tables with `pandas`_ +- 2D visualization using `Matplotlib`_ +- 3D visualization using `PyVista`_ +- Advanced scientific computing using `SciPy`_ +- Machine learning using `TensorFlow`_ .. note:: If you are new to GitHub, we suggest that you visit `The ReadMe Project @@ -43,17 +43,14 @@ ecosystem. Examples include: administration contributing -.. _PyAEDT: https://github.com/pyansys/PyAEDT -.. _PyMAPDL: https://github.com/pyansys/pymapdl - Contributing to this Guide ~~~~~~~~~~~~~~~~~~~~~~~~~~ If you would like to contribute to this development guide, we will gladly review all pull requests. Please feel free to submit them and follow the -:ref:`doc_practices`. +:ref:`API Documentation Style`. -This repository uses the `pre-commit `_ library to +This repository uses the `pre-commit`_ library to automate style checking. To use it, enter your Python environment and install it with:: @@ -73,3 +70,6 @@ installing a pre-commit as a git hook with:: Now, each time you run ``git commit``, your commit will only be created if it passes the minimum style checks that will also be run on the GitHub CI/CD. + +.. LINKS AND REFERENCES +.. include:: ../links.rst diff --git a/doc/source/packaging/structure.rst b/doc/source/packaging/structure.rst index d259df5da..eded7a95f 100644 --- a/doc/source/packaging/structure.rst +++ b/doc/source/packaging/structure.rst @@ -1,6 +1,3 @@ -.. _ref_project_structure: - -################# Project Structure ################# @@ -280,22 +277,11 @@ template can be used: .. REFERENCES & LINKS +.. include:: ../links.rst -.. _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/ -.. _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 -.. _setuptools: https://setuptools.pypa.io/en/latest/index.html +.. _Markdown Syntax: https://www.markdownguide.org/basic-syntax/ +.. _Namespace Packages: https://packaging.python.org/guides/packaging-namespace-packages/ +.. _native namespace packages: https://packaging.python.org/en/latest/guides/packaging-namespace-packages/#native-namespace-packages +.. _reStructuredText Markup Syntax: https://docutils.sourceforge.io/rst.html