diff --git a/.gitignore b/.gitignore index 4d888c596..d6bbe5596 100644 --- a/.gitignore +++ b/.gitignore @@ -18,4 +18,4 @@ doc/build/ venv/ # sphinx autogen -doc/source/documentation_style/api/* \ No newline at end of file +doc/source/guidelines/api/* diff --git a/doc/source/coding_style/pep8_best_practices.rst b/doc/source/coding_style/pep8_best_practices.rst index 046ab000b..2d8b25247 100644 --- a/doc/source/coding_style/pep8_best_practices.rst +++ b/doc/source/coding_style/pep8_best_practices.rst @@ -444,7 +444,7 @@ 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`. +libraries, see :ref:`Documentation Style`. Programming Recommendations diff --git a/doc/source/documentation_style/sample_func.py b/doc/source/doc-style/code/sample_func.py similarity index 100% rename from doc/source/documentation_style/sample_func.py rename to doc/source/doc-style/code/sample_func.py diff --git a/doc/source/documentation_style/docstrings.rst b/doc/source/doc-style/docstrings.rst similarity index 64% rename from doc/source/documentation_style/docstrings.rst rename to doc/source/doc-style/docstrings.rst index 0c875096a..dbe60c86d 100644 --- a/doc/source/documentation_style/docstrings.rst +++ b/doc/source/doc-style/docstrings.rst @@ -1,20 +1,8 @@ -.. _docstrings: - -Docstring Standards +Numpydoc Docstrings ################### -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 - ] +When writing docstrings for PyAnsys libraries, use the `numpydoc`_ +style. For consistency within PyAnsys libraries, always use ``"""`` to introduce and conclude a docstring, keeping the line length shorter than 70 characters. Ensure that there are @@ -39,11 +27,12 @@ classes, methods, and variables. For example:: style. -Minimum Section Requirements ----------------------------- +Required Docstring Sections +=========================== + PyAnsys library docstrings contain these `numpydoc`_ sections as a minimum: -* `Short description `_ +* `Short Summary `_ * `Extended Summary `_ if applicable * `Parameters `_ if applicable * `Returns `_ if applicable @@ -52,11 +41,29 @@ PyAnsys library docstrings contain these `numpydoc`_ sections as a minimum: These sections should follow numpydoc style. To avoid inconsistencies between PyAnsys libraries, adhere to the additional style guidelines that follow. -Classes -~~~~~~~ + +Short Summary +------------- +This is a single line that goes immediately after the declaration of the class +or function to briefly describe what the class or function does. The +`short summary` is mandatory. If it is not present, :ref:`Doc Style Tools` will +raise an error. + +The short summary can be declared on the same line as the opening quotes or on +the next line. While `PEP 257 +`_ accepts both ways, you must be consistent across your +project. If you decide to declare the short summary on the same line, +refer to :ref:`Numpydoc Validation` because the ``"GL01"`` check must be +disabled. + +The guidelines for documenting short summaries differ for classes versus +functions. + +Short Summaries for Classes +~~~~~~~~~~~~~~~~~~~~~~~~~~~ A class is a 'noun' representing a collection of methods. For consistency within PyAnsys libraries, always start the brief description for a class with a verb ending in 's', followed by an extended -summary if applicable:: +summary in a new line if additional information is needed:: class FieldAnalysis3D(Analysis): """Manages 3D field analysis setup in HFSS, Maxwell 3D, and Q3D. @@ -67,19 +74,20 @@ summary if applicable:: ... """ - Ensure that there is a line break between the end of a class docstring and the subsequent methods. -Methods -~~~~~~~ +Short Summaries for Methods +~~~~~~~~~~~~~~~~~~~~~~~~~~~ A method is a 'verb' representing an action that can be performed. For consistency within PyAnsys libraries, always start the brief description for a method with a verb not ending in 's', followed -by an extended summary if applicable:: +by an extended summary in a new line if additional information is needed:: def export_mesh_stats(self, setup_name, variation_string="", mesh_path=None): - """Export mesh statistics to a file.""" + """Export mesh statistics to a file. + + ... + """ - Methods with a leading underscore (_) are 'protected' methods, meaning that they are not rendered in the documentation unless an explicit request is made to add them using Sphinx directives. However, clearly written descriptions for private methods are still important. @@ -91,11 +99,14 @@ add a docstring for the setter. A setter simply exposes both the GET and SET met just the GET method. Examples should be included to demonstrate usage. Parameters -~~~~~~~~~~ -Both classes and methods have parameters in their function signatures. All parameters in a function -signature should appear in the 'Parameters' section for the class or method. +---------- +Functions and class methods may have parameters in their signatures. All these +parameters should be documented in the ``Parameters`` section. +signature should appear in the ``Parameters`` section for the class or method. + +Here is an example of a ``Parameters`` section for a class in PyAEDT: -Here is an example of a 'Parameters' section for a class in PyAEDT:: +.. code-block:: rst Parameters ---------- @@ -144,83 +155,116 @@ parameter, the description specifies the default along with any information that be needed about the behavior that occurs when the default is used. Returns -~~~~~~~ -The 'Returns' section contains only the return data type and a brief description -that concludes with a period:: +------- +The ``Returns`` section contains only the return data type and a brief description +that concludes with a period: + +.. code-block:: rst Returns ------- - dict + dict Dictionary of components with their absolute paths. -A class does not have a 'Returns' section. If a Boolean is returned, format the -'Returns` section like this:: +A class does not have a ``Returns`` section. If a ``Boolean`` is returned, format the +``Returns`` section like this: + +.. code-block:: rst Returns - -------- - bool + ------- + bool + ``True`` when successful, ``False`` when failed. + +It is possible for the ``Returns`` section to look like the ``Parameters`` section +if variable names are provided: + +.. code-block:: rst + + Returns + ------- + has_succeeded : bool ``True`` when successful, ``False`` when failed. +It is possible for more than one item to be returned: -It is possible for more than one item to be returned:: +.. code-block:: rst Returns - -------- - type + ------- + type Ground object. - str + str Ground name. - If a method does not have a decorator, the basic implementation of Python methods is used. In this case, while ``None`` is returned, you do not document it. -Consequently, such a method does not have a 'Returns' section. +Consequently, such a method does not have a ``Returns`` section. -Example Docstrings ------------------- -Methods and functions should generally be documented within the -'Examples' section to make the usage of the method or function clear. -Here is a sample function: +Examples +-------- -.. literalinclude:: sample_func.py +The ``Examples`` section provides a quick reference on how to use a method or +a function. This section must be compliant with the `doctest +`_ format and is not supposed to +replace your test suite but complement it. As an example, +consider the following function: -To include the docstring of a function within Sphinx, you use the -``autofunction::`` directive: +.. code-block:: rst -.. code:: + Examples + -------- + Create an instance of HFSS and connect to an existing HFSS + design or create a new HFSS design if one does not exist. - .. autofunction:: pyansys_sphinx_theme.sample_func.func + >>> from pyaedt import Hfss + >>> hfss = Hfss() + pyaedt info: No project is defined... + pyaedt info: Active design is set to... -This directive renders the sample function as: -.. autofunction:: pyansys_sphinx_theme.sample_func.func - - -Validation ----------- -Enable validation of docstrings during the Sphinx build by adding the -following line to the ``conf.py`` file:: +If the definition of the function is updated, this +section must be updated too. - numpydoc_validation_checks = {"GL08"} -This will issue the following warning for any object without a docstring:: +Additional Directives +===================== +Since Python docstrings are written using RST syntax, it is possible to take +advantage of some directives available in this Markup language. Among those, it +is possible to find: - "The object does not have a docstring" +- ``.. note::`` directive is useful for highlighting important + information once the documentation gets rendered. -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 `_ -in the `numpydoc`_. +- ``.. warning::`` is usually used to point out an action that might result in + data loss. +- ``.. deprecated:: X.Y.Z`` to inform the user about the deprecated status of + the object or functionality. -Additional Information ----------------------- You can find additional information and examples at `numpydoc`_. Reference this documentation as the primary source regarding docstring styles for directives -that are not covered here. For example, you use the ``note::`` directive to highlight -important information and the ``warning::`` directive to point out an action that -might result in data loss. +that are not covered here. + + +Example +======= + +A generic docstring example compliant with PyAnsys guidelines is shown below: + +.. literalinclude:: code/sample_func.py + +To include the docstring of a function within Sphinx, you use the +``autofunction::`` directive: + +.. code:: + + .. autofunction:: pyansys_sphinx_theme.sample_func.func + +This directive renders the sample function as: + +.. autofunction:: pyansys_sphinx_theme.sample_func.func .. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html .. _googledoc: https://google.github.io/styleguide/ diff --git a/doc/source/documentation_style/formatting-tools.rst b/doc/source/doc-style/formatting-tools.rst similarity index 64% rename from doc/source/documentation_style/formatting-tools.rst rename to doc/source/doc-style/formatting-tools.rst index 7b58cf81c..87f29edbb 100644 --- a/doc/source/documentation_style/formatting-tools.rst +++ b/doc/source/doc-style/formatting-tools.rst @@ -1,6 +1,5 @@ -Formatting Tools -================ - +Doc Style Tools +=============== There are plenty of tools for documentation style and coverage. This section presents some of the most popular ones in the Python ecosystem. A minimum configuration is provided for each one so you can easily include them in your @@ -11,6 +10,19 @@ Most of the tools presented can be configured using :ref:`the cleaner root project directory. +Blacken-Docs +------------ + +When writing documentation, it is frequent to include code-blocks which are used +as examples. However, these code snippets style cannot be verified with the usual code +formatting tools. This is where `blacken-docs`_ comes into play. You can execute +this tool by running: + +.. code:: bash + + blacken-docs -l doc/**/*.rst + + Codespell --------- @@ -72,6 +84,41 @@ Alternate tools to `interrogate`_ are `docstr-coverage`_ and output resembling that of `pytest-cov`_, which is the the equivalent tool for source code coverage. +Numpydoc Validation +------------------- +To validate the style of :ref:`Numpydoc Docstrings`, it is possible to +take advantage of the `numpydoc`_ Sphinx extension. Note that this extension +checks only for those objects whose docstrings must be rendered. It is not a +command line tool that checks the style of all docstrings in your source code. + +Because `numpydoc`_ is a Sphinx extension, it must be configured in the +``conf.py`` file. See :ref:`The \`\`doc/\`\` directory`. Start by adding it to the +list of extensions: + +.. code-block:: python + + extensions = [ + 'numpydoc', + ... + ] + +Once the `numpydoc`_ extension is added, you can select which `validation checks +`_ +must be addressed by using the ``numpydoc_validation_checks`` dictionary: + +.. code-block:: python + + numpydoc_validation_checks = {"GL08"} + +This will issue the following warning for any object without a docstring: + +.. code-block:: python + + "The object does not have a docstring" + +For a complete list of available checks, see the `full mapping of +validation checks +`_. Pydocstyle ---------- @@ -86,9 +133,10 @@ under the ``[tool.pydocstyle]`` entry: .. code:: toml [tool.pydocstyle] - # Additional configuration + convention = "numpy" +.. _blacken-docs: https://github.com/asottile/blacken-docs .. _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 @@ -98,3 +146,4 @@ under the ``[tool.pydocstyle]`` entry: .. _docformatter: https://github.com/PyCQA/docformatter .. _codespell: https://github.com/codespell-project/codespell .. _pytest-cov: https://pytest-cov.readthedocs.io/en/latest/ +.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html diff --git a/doc/source/documentation_style/index.rst b/doc/source/doc-style/index.rst similarity index 91% rename from doc/source/documentation_style/index.rst rename to doc/source/doc-style/index.rst index 56e24b6b3..a7c7c7e4d 100644 --- a/doc/source/documentation_style/index.rst +++ b/doc/source/doc-style/index.rst @@ -1,7 +1,6 @@ -.. _api_documentation: +Documentation Style +################### -API Documentation Style -####################### Good API documentation drives library adoption and usage and is the foundation for a good developer experience. Even with the best interfaces and the most functional product, no one will adopt the API @@ -32,13 +31,11 @@ The documentation for a PyAnsys library should contain: 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:`Continuous Documentation Deployment`. .. toctree:: :hidden: :maxdepth: 3 docstrings - class_documentation - deployment formatting-tools diff --git a/doc/source/documentation_style/class_documentation.rst b/doc/source/documentation_style/class_documentation.rst deleted file mode 100644 index afd193e92..000000000 --- a/doc/source/documentation_style/class_documentation.rst +++ /dev/null @@ -1,109 +0,0 @@ -Class Documentation -################### - -There are two main ways of using Sphinx to document a class: - -* Manually describe 'how' and 'why' to use a class in either - a "User Guide" or an example within the library's documentation -* Automatically generate documentation for classes using the - ``autoclass`` or ``autosummary`` directive - -Manual Documentation --------------------- - -To manually describe 'how' and 'why' to exercise a class, use the -``.. code:: python`` directive:: - - Initialize ``my_module.MyClass`` with initial parameters. These - parameters are automatically assigned to the class. - - .. code:: python - - >>> from my_module import MyClass - >>> my_obj = MyClass(parm1='apple', parm2='orange') - >>> my_obj.parm1 - 'apple' - -In the documentation, this is rendered as: - -Initialize ``my_module.MyClass`` with initial parameters. These -parameters are automatically assigned to the class. - -.. code:: python - - >>> from my_module import MyClass - >>> my_obj = MyClass(parm1='apple', parm2='orange') - >>> my_obj.parm1 - 'apple' - - -Auto-generated Documentation ----------------------------- - -To automatically generate class descriptions, use either the ``autoclass`` -or ``autosummary`` directive. - -For simple classes, use the ``autoclass`` directive:: - - .. autoclass:: pyansys_sphinx_theme.samples.ExampleClass - :members: - -In the documentation, this is rendered as: - -.. autoclass:: pyansys_sphinx_theme.samples.ExampleClass - :members: - -For complex classes with many methods, use the -``autosummary`` directive:: - - .. autoclass:: pyansys_sphinx_theme.samples.Complex - - .. autosummary:: - :toctree: api/ - - pyansys_sphinx_theme.samples.Complex.real - pyansys_sphinx_theme.samples.Complex.imag - pyansys_sphinx_theme.samples.Complex.abs - - -The above code generates the following documentation, with each -method or attribute on its own page. - -.. autoclass:: pyansys_sphinx_theme.samples.Complex - - -.. autosummary:: - :toctree: api/ - - pyansys_sphinx_theme.samples.Complex.real - pyansys_sphinx_theme.samples.Complex.imag - pyansys_sphinx_theme.samples.Complex.abs - - -Documenting Multiple Classes Together -------------------------------------- - -To document a set of small but highly cohesive classes, an option -is to combine the two approaches described above. This is done by -including multiple ``autoclass`` directives on the same page with -headings and text blocks as necessary to describe the -relationships between the classes. - -For example, the Granta MI BoM Analytics -:external+grantami-bomanalytics:doc:`Part Compliance page ` -first describes the -:external+grantami-bomanalytics:class:`~ansys.grantami.bomanalytics.queries.PartComplianceQuery` -class, and then describes the -:external+grantami-bomanalytics:class:`~ansys.grantami.bomanalytics._query_results.PartComplianceQueryResult`, -and -:external+grantami-bomanalytics:class:`~ansys.grantami.bomanalytics._item_results.PartWithComplianceResult` -classes returned by the query. The classes are only ever -encountered together in this context, so they are documented on a -single page. - -In contrast, the -:external+grantami-bomanalytics:class:`~ansys.grantami.bomanalytics.indicators.RoHSIndicator` -and -:external+grantami-bomanalytics:class:`~ansys.grantami.bomanalytics.indicators.WatchListIndicator` -classes are shared across multiple queries, and so they are -documented separately. diff --git a/doc/source/documentation_style/deployment.rst b/doc/source/documentation_style/deployment.rst deleted file mode 100644 index 1fdf0372c..000000000 --- a/doc/source/documentation_style/deployment.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. _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``. diff --git a/doc/source/guidelines/doc_practices.rst b/doc/source/guidelines/doc_practices.rst index b367023f9..d57b89394 100644 --- a/doc/source/guidelines/doc_practices.rst +++ b/doc/source/guidelines/doc_practices.rst @@ -53,7 +53,7 @@ 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`. +within PyAnsys libraries. For more information, see :ref:`Documentation Style`. RST Files ~~~~~~~~~ @@ -155,6 +155,115 @@ Once the URL name has been decided, it must be specified in the "Settings -> Pag Then, the URL has to be registered using Microsoft Azure to set the DNS properly and link it to the ANSYS organization. This action will be performed by one of the Ansys administrator of Microsoft Azure account. +Class Documentation +------------------- + +There are two main ways of using Sphinx to document a class: + +* Manually describe 'how' and 'why' to use a class in either + a "User Guide" or an example within the library's documentation +* Automatically generate documentation for classes using the + ``autoclass`` or ``autosummary`` directive + +Manual Documentation +~~~~~~~~~~~~~~~~~~~~ + +To manually describe 'how' and 'why' to exercise a class, use the +``.. code:: python`` directive:: + + Initialize ``my_module.MyClass`` with initial parameters. These + parameters are automatically assigned to the class. + + .. code-block:: python + + >>> from my_module import MyClass + >>> my_obj = MyClass(parm1='apple', parm2='orange') + >>> my_obj.parm1 + 'apple' + +In the documentation, this is rendered as: + +Initialize ``my_module.MyClass`` with initial parameters. These +parameters are automatically assigned to the class. + +.. code-block:: python + + >>> from my_module import MyClass + >>> my_obj = MyClass(parm1='apple', parm2='orange') + >>> my_obj.parm1 + 'apple' + +Auto-generated Documentation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To automatically generate class descriptions, use either the ``autoclass`` +or ``autosummary`` directive. + +For simple classes, use the ``autoclass`` directive:: + + .. autoclass:: pyansys_sphinx_theme.samples.ExampleClass + :members: + +In the documentation, this is rendered as: + +.. autoclass:: pyansys_sphinx_theme.samples.ExampleClass + :members: + +For complex classes with many methods, use the +``autosummary`` directive:: + + .. autoclass:: pyansys_sphinx_theme.samples.Complex + + .. autosummary:: + :toctree: api/ + + pyansys_sphinx_theme.samples.Complex.real + pyansys_sphinx_theme.samples.Complex.imag + pyansys_sphinx_theme.samples.Complex.abs + + +The above code generates the following documentation, with each +method or attribute on its own page. + +.. autoclass:: pyansys_sphinx_theme.samples.Complex + + +.. autosummary:: + :toctree: api/ + + pyansys_sphinx_theme.samples.Complex.real + pyansys_sphinx_theme.samples.Complex.imag + pyansys_sphinx_theme.samples.Complex.abs + + +Documenting Multiple Classes Together +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To document a set of small but highly cohesive classes, an option +is to combine the two approaches described above. This is done by +including multiple ``autoclass`` directives on the same page with +headings and text blocks as necessary to describe the +relationships between the classes. + +For example, the Granta MI BoM Analytics +:external+grantami-bomanalytics:doc:`Part Compliance page ` +first describes the +:external+grantami-bomanalytics:class:`~ansys.grantami.bomanalytics.queries.PartComplianceQuery` +class, and then it describes the +:external+grantami-bomanalytics:class:`~ansys.grantami.bomanalytics._query_results.PartComplianceQueryResult`, +and +:external+grantami-bomanalytics:class:`~ansys.grantami.bomanalytics._item_results.PartWithComplianceResult` +classes returned by the query. The classes are only ever +encountered together in this context, so they are documented on a +single page. + +In contrast, the +:external+grantami-bomanalytics:class:`~ansys.grantami.bomanalytics.indicators.RoHSIndicator` +and +:external+grantami-bomanalytics:class:`~ansys.grantami.bomanalytics.indicators.WatchListIndicator` +classes are shared across multiple queries, and so they are +documented separately. + Accessing a Library's Documentation ----------------------------------- Documentation for the latest stable release of a PyAnsys library is accessible diff --git a/doc/source/index.rst b/doc/source/index.rst index 81b182d26..ab347b9f8 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -11,5 +11,5 @@ guidelines/index packaging/index coding_style/index - documentation_style/index + doc-style/index abstractions/index diff --git a/doc/source/overview/administration.rst b/doc/source/overview/administration.rst index 9371875a3..feb7fae83 100644 --- a/doc/source/overview/administration.rst +++ b/doc/source/overview/administration.rst @@ -46,7 +46,7 @@ Each repository is expected to follow this minimum set of standards: - PEP8 code standards. See :ref:`best_practices`. - CI/CD using GitHub actions or Azure DevOps to enforce coding standards. - Publicly hosted documentation describing the API and providing examples. See - :ref:`api_documentation`. + :ref:`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`. diff --git a/doc/source/overview/basic.rst b/doc/source/overview/basic.rst index 609638eba..a23422749 100644 --- a/doc/source/overview/basic.rst +++ b/doc/source/overview/basic.rst @@ -59,7 +59,8 @@ 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:`Documentation + Style`. #. **Prepare the package for release:** When you are ready to release your package publicly, email `pyansys.support@ansys.com `_