diff --git a/doc/source/documentation_style/docstrings.rst b/doc/source/documentation_style/docstrings.rst index a148efaae..bcc20c600 100644 --- a/doc/source/documentation_style/docstrings.rst +++ b/doc/source/documentation_style/docstrings.rst @@ -4,7 +4,7 @@ Docstring Standards ################### When writing docstrings for PyAnsys libraries, use the `numpydoc`_ documentation style. To use `numpydoc`_, add the following to your -``conf.py``: +``conf.py`` file: .. code:: python @@ -12,11 +12,32 @@ documentation style. To use `numpydoc`_, add the following to your # other extensions ] +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 +no blank spaces at the end of a line because they will cause errors in build checks that you +will then have to resolve. -Minimum Requirements --------------------- -PyAnsys library docstrings contain at a minimum the following -`numpydoc`_ sections: +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 your 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, +classes, methods, and variables. For example:: + + """Initialize the ``Desktop`` class with the version of AEDT to use.`` + + +.. note:: + The PyAnsys style uses two back ticks to surround the names of classes, methods, and + variables, not the single back tick that is recommended by the `numpydoc`_ documentation + style. + + +Minimum Section Requirements +---------------------------- +PyAnsys library docstrings contain these `numpydoc`_ sections as a minimum: * `Short description `_. * `Extended Summary `_ if applicable @@ -24,43 +45,139 @@ PyAnsys library docstrings contain at a minimum the following * `Returns `_ if applicable * `Examples `_ -These sections should follow the numpydoc standards. To avoid -inconsistencies between PyAnsys libraries, adhere to the additional -standards that follow. +These sections should follow numpydoc standards. To avoid inconsistencies between +PyAnsys libraries, adhere to the additional standards that follow. + +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:: + + class FieldAnalysis3D(Analysis): + """Manages 3D field analysis setup in HFSS, Maxwell 3D, and Q3D. + + This class is automatically initialized by an application call from one of + the 3D tools. For parameter definitions, see the application function. + + ... + """ + + +Ensure that there is a line break between the end of a class docstring and the subsequent methods. + +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:: + + def export_mesh_stats(self, setup_name, variation_string="", mesh_path=None): + """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, clearing +documenting private methods is still important. + +If a method has the decorator ``@property``, it is turned into a property, which is described as a +'noun' rather than a 'verb'. Because the resulting property cannot have parameters, you remove +the 'Parameters' section for this method. If a setter follows the decorator ``@property``, do not +add a docstring for the setter. A setter simply exposes both the GET and SET methods rather +just the GET method. Examples should be included to demonstrate usage. Parameters ~~~~~~~~~~ -Always specify the type, and whenever necessary, provide the full class name:: +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. + +Here is an example of a 'Parameters' section for a class in PyAEDT:: Parameters ---------- - my_obj : :class:`ansys...FooClass` - Description of FooClass. - some_int : int - Some integer value. - -.. note:: - Parameter descriptions have punctuation. While the brief description itself - need not be a sentence, any text following it should a clear, complete - sentence. - - + application : str + 3D application that is to initialize the call. + projectname : str, optional + Name of the project to select or the full path to the project + or AEDTZ archive to open. The default is ``None``, in which + case an attempt is made to get an active project. If no + projects are present, an empty project is created. + designname : str, optional + Name of the design to select. The default is ``None``, in + which case an attempt is made to get an active design. If no + designs are present, an empty design is created. + solution_type : str, optional + Solution type to apply to the design. The default is + ``None``, in which case the default type is applied. + setup_name : str, optional + Name of the setup to use as the nominal. The default is + ``None``, in which case the active setup is used or + nothing is used. + specified_version : str, optional + Version of AEDT to use. The default is ``None``, in which case + the active version or latest installed version is used. + non_graphical : bool, optional + Whether to run AEDT in the non-graphical mode. The default + is ``False``, in which case AEDT is launched in the graphical mode. + new_desktop_session : bool, optional + Whether to launch an instance of AEDT in a new thread, even if + another instance of the ``specified_version`` is active on the + machine. The default is ``True``. + close_on_exit : bool, optional + Whether to release AEDT on exit. The default is ``False``. + student_version : bool, optional + Whether to enable the student version of AEDT. The default + is ``False``. + +The name of each parameter is followed by a space, a colon, a space, and then +the data type. A parameter is optional if its keyword argument has a default shown +in the function signature. For an optional parameter, the data type is followed by a +comma and ``optional``. + +The brief description for a parameter is generally a sentence fragment. However, +additional information is provided in clear, complete sentences. For an optional +parameter, the description specifies the default along with any information that might +be needed about the behavior that occurs when the default is used. + Returns ~~~~~~~ -The Returns section contains only the return type and (not the name and type) -and a brief description:: +The 'Returns' section contains only the return data type and a brief description +that concludes with a period:: Returns ------- - int - Description of some return value. + 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:: + + Returns + -------- + bool + ``True`` when successful, ``False`` when failed. + + +It is possible for more than one item to be returned:: + + Returns + -------- + type + Ground object. + str + Ground name. + + +If a method does not have a decorator, the basic implementation of Python +methods is used. In this case, ``None`` is returned but you do not document it. +Consequently, such a method does not have a 'Returns' section. Example Docstrings ------------------ Methods and functions should generally be documented within the -``Examples`` docstring section to make the usage of the method or -function clear. Here is a sample function: +'Examples' section to make the usage of the method or function clear. +Here is a sample function: .. literalinclude:: sample_func.py @@ -79,25 +196,28 @@ This directive renders the sample function as: Validation ---------- Enable validation of docstrings during the Sphinx build by adding the -following line to ``conf.py``:: +following line to the ``conf.py`` file:: numpydoc_validation_checks = {"GL08"} -This will issue the following warning for any objects without a docstring:: +This will issue the following warning for any object without a docstring:: "The object does not have 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 -`numpydoc Validation Check -`_. +Other codes may be enforced at a later date. For a full listing, in the `numpydoc`_, +see the `Validation `_ +topic. Additional Information ---------------------- Additional examples and notes can be found at `numpydoc`_. Reference this documentation as the primary source of information regarding -docstring styles for directives not covered here. +docstring styles for directives that are not covered here. For example, +you would use the ``note::`` directive to highlight 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/ diff --git a/doc/source/documentation_style/index.rst b/doc/source/documentation_style/index.rst index d4f29f399..fabd7d50b 100644 --- a/doc/source/documentation_style/index.rst +++ b/doc/source/documentation_style/index.rst @@ -26,7 +26,7 @@ The documentation for a PyAnsys library should contain: :ref:`docstrings`. * Full gallery of examples. See `PyMAPDL Examples `_ -* User guide for the library. +* Developer's guide for the library. * Link to this developer's guide. .. toctree:: diff --git a/doc/source/guidelines/doc_practices.rst b/doc/source/guidelines/doc_practices.rst index a4251e0c2..ee4252268 100644 --- a/doc/source/guidelines/doc_practices.rst +++ b/doc/source/guidelines/doc_practices.rst @@ -2,9 +2,23 @@ Documentation Practices ======================= -The generation of documentation uses `Sphinx `__ -and an Ansys-branded theme. Documentation is built from docstrings, reStructuredText -(RST) files, and Python (PY) example files. +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 editorial guidelines +for writing clear and consistent developer documentation, allowing this guide to supply +guidance specific to PyAnsys library documentation. + +When writing developer documentation, the relationship between code and documenation is +key. To keep documentation up to date with rapdily evolving code: + +- Minimize the content footprint +- Write `timeless documentation `_ +- Support contributions from both inside and outside of the development team +- Perform periodic reviews + +The generation of PyAnsys documentation uses `Sphinx `__ +and an Ansys-branded theme (pyansys-sphinx-theme) to assemble content comes from docstrings, +reStructuredText (RST) files, and Python (PY) example files. Docstrings ---------- @@ -28,7 +42,10 @@ style docstrings, refers you to the `Google Python Style Guide `_ -documentation. +in the header of the documentation's generated HTML output. For more information on defining +a documentation structure, see the `Sphinx Getting Started `_ +guide. + +Within RST files, heading titles are followed by a line having a string of characters that is +the same length as the heading title. If the length of the characters +under the heading title do not match the length of the heading title, Sphinx will generate a warning. + +For consistency within PyAnsys libraries, the use of these special characters is recommended for +headings but are not enforced: + +- For first-level headings, use ====. +- For second-level headings, use ---. +- For third-level headings, use ~~~. + +For comprehensive syntax information, see the `reStrucutredText Markup Specification +`_. + +Because you need to be familiar with the content in the *PyAnsys Developer's Guide*, page through +its HTML pages and then explore the RST files in its repository. This will help you to understand +the syntax and see how RST files are nested to create this guide. Examples -------- diff --git a/doc/source/overview/index.rst b/doc/source/overview/index.rst index ed8dc0e86..d2339f110 100644 --- a/doc/source/overview/index.rst +++ b/doc/source/overview/index.rst @@ -18,7 +18,7 @@ These libraries play a vital role in: - Workflow orchestration - Data manipulation and export -The libraries also include plugins and interfaces to the vast python +The libraries also include plugins and interfaces to the vast Python ecosystem. Examples include: - Arrays using `NumPy `_ @@ -28,10 +28,13 @@ ecosystem. Examples include: - Advanced scientific computing using `SciPy `_ - Machine learning using `TensorFlow `_ +.. note:: + If you are new to GitHub, we suggest that you visit `The ReadMe Project `_. + It is a dedicated platform for highlighting the best from the open source software community. + Monthly newletters provide feature articles, developer stories, guides, and podcasts. 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. @@ -48,7 +51,7 @@ If you want to create, develop, or contribute to a PyAnsys library, visit these links: * `PyAnsys Project Developer's Guide `_ -* `PyAnsys Documentation Theme `_ +* `PyAnsys Sphinx Theme Documentation `_ * `gRPC Hello-world Example `_ * `Material Example Data `_