diff --git a/doc/source/coding-style/index.rst b/doc/source/coding-style/index.rst index d967e8504..ceef5944b 100644 --- a/doc/source/coding-style/index.rst +++ b/doc/source/coding-style/index.rst @@ -25,7 +25,7 @@ formatting with the libraries for the "big three" data science packages: `NumPy` The purpose of this section is not to repeat coding style documentation but rather to describe coding best practices applicable to the `PyAnsys`_ project when there are any delineations, clarifications, or additional procedures above and -beyond `PEP 8`_. For example, this section provides a topic on deprecation +beyond PEP 8. For example, this section provides a topic on deprecation best practices because there is no official guidance on deprecating features within Python. diff --git a/doc/source/coding-style/pep8.rst b/doc/source/coding-style/pep8.rst index 2a377a7fe..627f847be 100644 --- a/doc/source/coding-style/pep8.rst +++ b/doc/source/coding-style/pep8.rst @@ -2,9 +2,9 @@ PEP 8 ===== This section summarizes important coding style guidelines from `PEP 8`_ -and how they apply to PyAnsys libraries. The Python community devised `PEP 8`_ +and how they apply to PyAnsys libraries. The Python community devised PEP 8 to increase the readability of Python code. Some of the most popular -packages within the Python ecosystem have adopted `PEP 8`_, +packages within the Python ecosystem have adopted PEP 8, including `NumPy`_, `SciPy`_, and `pandas`_. Imports @@ -177,7 +177,7 @@ global rules to determine the correct names: Variables ~~~~~~~~~ -Do not use the characters ``"l"`, ``"O"``, or ``"I"`` as single-character +Do not use the characters ``"l"``, ``"O"``, or ``"I"`` as single-character variable names. In some fonts, these characters are indistinguishable from the numerals one and zero. @@ -424,7 +424,7 @@ letter. Here are general guidelines for writing comments: - Always try to explain yourself in code by making it - self-documenting with clear variable names. + self-documenting with clear variable names. - Don't be redundant. - Don't add obvious noise. - Don't use closing brace comments. diff --git a/doc/source/conf.py b/doc/source/conf.py index 08d7206c0..a4f57d539 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -16,7 +16,7 @@ from sphinx_gallery.sorting import FileNameSortKey # Project information -project = "PyAnsys Developer's Guide" +project = "PyAnsys developer's guide" copyright = f"(c) {datetime.now().year} ANSYS, Inc. All rights reserved" author = "Ansys Inc." release = version = datetime.now().strftime("%Y-%m-%d") diff --git a/doc/source/content-writing/_static/collapsible_sections.png b/doc/source/content-writing/_static/collapsible_sections.png new file mode 100644 index 000000000..93355edb2 Binary files /dev/null and b/doc/source/content-writing/_static/collapsible_sections.png differ diff --git a/doc/source/content-writing/content-how-tos/add-sphinx-extensions.rst b/doc/source/content-writing/content-how-tos/add-sphinx-extensions.rst index bfc5e6459..e63000005 100644 --- a/doc/source/content-writing/content-how-tos/add-sphinx-extensions.rst +++ b/doc/source/content-writing/content-how-tos/add-sphinx-extensions.rst @@ -23,8 +23,9 @@ template, the ``extensions`` variable lists these extensions by default: Extensions with names beginning with ``sphinx_ext`` are native (built-in) and are available for Sphinx's use without any additional installation. Extensions with names that do not begin with ``sphinx_ext`` are external extensions and require installation. -If an extension is not configured properly, attempts to build the documentation fail -because Sphinx cannot find the needed extension. +If a non-native extension is not installed but added to the :file:`conf.py` file in the +``doc/source`` directory, attempts to build the documentation fail because Sphinx cannot +find the needed extension. .. _links_to_objects_in_other_doc: @@ -131,9 +132,16 @@ the external `sphinx-design `_ extension for use: python -m pip install - For example, to install the external ``sphinx-design`` extension, run this command:: + Examples follow for some of the external extensions mentioned in this + documentation. + + - To install the external ``sphinx-design`` extension, run this command:: + + python -m pip install sphinx-design - python -m pip install sphinx-design + - To install the external ``sphinx_toolbox.collapse`` extension, run this command:: + + python -m pip install sphinx_toolbox.collapse #. Add the external extension to the ``extensions`` variable in your project's :file:`conf.py` file. @@ -151,8 +159,8 @@ building the documentation. Depending on the project's configuration, you list t packages in either the :file:`pyproject.toml` file or the :file:`requirements_doc_txt` file. -``pyproject.toml`` file -~~~~~~~~~~~~~~~~~~~~~~~ +The ``pyproject.toml`` file +~~~~~~~~~~~~~~~~~~~~~~~~~~~ Most projects specify documentation requirements in a :file:`pyproject.toml` file, which resides in the root folder. In this file, the ``doc`` variable defines the required ``pip`` @@ -183,8 +191,8 @@ packages and their versions like this. "vtk==9.2.6", ] -``requirements_doc_txt`` file -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The ``requirements_doc_txt`` file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Some projects specify documentation requirements in a :file:`requirements_doc_txt` file. The root folder of such a project typically has a ``requirements`` directory @@ -213,7 +221,8 @@ Learn more about extensions --------------------------- As you can see, PyAnsys projects add many extensions to their :file:`conf.py` files -and documentation requirements. Here are some additional extensions that you might see: +and documentation requirements. Here are some other native and non-native extensions +that you might see: - ``sphinx.ext.coverage`` - ``sphinx.ext.doctest`` @@ -221,6 +230,7 @@ and documentation requirements. Here are some additional extensions that you mig - ``sphinx.ext.graphviz`` - ``sphinx.ext.napoleon`` - ``sphinx.ext.viewcode`` +- ``sphinx_toolbox.collapse`` For more information on extensions, see `Extensions `_ in the Sphinx documentation. In addition to the external (third-party) extensions collected diff --git a/doc/source/content-writing/content-how-tos/resolve-issues-causing-check-failures.rst b/doc/source/content-writing/content-how-tos/resolve-issues-causing-check-failures.rst index 6fa399e93..e8dda48b5 100644 --- a/doc/source/content-writing/content-how-tos/resolve-issues-causing-check-failures.rst +++ b/doc/source/content-writing/content-how-tos/resolve-issues-causing-check-failures.rst @@ -28,7 +28,7 @@ and lines where you must resolve them. Your objective should always be to eliminate or mitigate issues before creating or pushing changes to a PR. For example, running ``pre-commit`` and Vale locally -allows you to proactively resolve typos and trailing whitespaces. However, +lets you proactively resolve typos and trailing whitespaces. However, oftentimes, you must resolve issues that cause the checks run by the CI/CD process to fail. diff --git a/doc/source/content-writing/content-how-tos/view-revision-history.rst b/doc/source/content-writing/content-how-tos/view-revision-history.rst index d66016cbb..3624cc07d 100644 --- a/doc/source/content-writing/content-how-tos/view-revision-history.rst +++ b/doc/source/content-writing/content-how-tos/view-revision-history.rst @@ -3,7 +3,7 @@ View revision history on GitHub =============================== -GitHub *blame* is a feature that allows you to view the revision history of a +GitHub *blame* is a feature that lets you view the revision history of a file in a repository to see who made changes and when these changes were made. You can use the GitHub blame feature for a variety of use cases, including these: diff --git a/doc/source/content-writing/content-how-tos/work-around-Vale.rst b/doc/source/content-writing/content-how-tos/work-around-Vale.rst index d9300cf13..2caab4dc4 100644 --- a/doc/source/content-writing/content-how-tos/work-around-Vale.rst +++ b/doc/source/content-writing/content-how-tos/work-around-Vale.rst @@ -6,7 +6,7 @@ Work around Vale issues Some issues that Vale raises may not be considered problematic in PyAnsys projects. This page describes some common workarounds. -Turn Vale on and off +Turn Vale off and on -------------------- If Vale flags content as an issue but you know that this content is @@ -19,10 +19,10 @@ before the flagged content and then back on again after it:: .. vale on -As shown in the preceding example , you must insert blank lines to separate the -directives for tuning Vale off and off from your documentation content. +As shown in the preceding example, you must insert blank lines to separate the +directives for tuning Vale off and on from your documentation content. -In an MD file, the syntax for these two Vale directives looks like this:: +In an Markdown (MD) file, the syntax for these two Vale directives looks like this:: diff --git a/doc/source/content-writing/examples-writers/index.rst b/doc/source/content-writing/examples-writers/index.rst index 4cb874696..9a4609b4e 100644 --- a/doc/source/content-writing/examples-writers/index.rst +++ b/doc/source/content-writing/examples-writers/index.rst @@ -3,8 +3,8 @@ Content in examples =================== -Many PyAnsys libraries have an "Example" section. The `sphinx_gallery `_ -extension (Sphinx-Gallery) are typically used to generate standalone, downloadable Python scripts +Many PyAnsys libraries have an "Example" section. The `Sphinx-Gallery `_ +extension (``sphinx_gallery``) is typically used to generate standalone, downloadable Python scripts (PY files) or Jupyter notebooks (IPYNB files) that you can run. However, some PyAnsys libraries use the `nbsphinx `_ extension, which is specifically designed for working with and integrating Jupyter notebooks diff --git a/doc/source/content-writing/py-files-writers/docstring-format-rules.rst b/doc/source/content-writing/py-files-writers/docstring-format-rules.rst index 7ad6d6721..ba6b8d84e 100644 --- a/doc/source/content-writing/py-files-writers/docstring-format-rules.rst +++ b/doc/source/content-writing/py-files-writers/docstring-format-rules.rst @@ -446,7 +446,7 @@ back to them as needed: - Enclose all code entities in double backticks. If you surround a code entity in only a single backtick (:code:`\``), it is incorrectly rendered in italics in the documentation. -- Use the present tense for verbs. Occurrences of ``will`` cause `Vale `_ to +- Use the present tense for verbs. Occurrences of ``will`` cause `Vale`_ to raise warnings about not using phrases expressing future actions. - When documenting variable length positional or keyword arguments, leave the leading single diff --git a/doc/source/content-writing/rst-files-writers/cards.rst b/doc/source/content-writing/rst-files-writers/cards.rst index c7ad23146..55f488620 100644 --- a/doc/source/content-writing/rst-files-writers/cards.rst +++ b/doc/source/content-writing/rst-files-writers/cards.rst @@ -11,8 +11,10 @@ custom cards. .. note:: To use custom cards in your PyAnsys documentation, you must install - and configure the `sphinx-design `_ - extension. For more information, see :ref:`add_sphinx_extensions`. + the `sphinx-design `_ extension and then + add it to the ``conf.py`` file in the ``doc/source`` directory and to + your list of documentation requirements. For more information, see + :ref:`add_sphinx_extensions`. To see and use the cards that are shown only as images on this page, click the links to their respective documentation pages. To see how these diff --git a/doc/source/content-writing/rst-files-writers/collapsible-sections.rst b/doc/source/content-writing/rst-files-writers/collapsible-sections.rst new file mode 100644 index 000000000..3c8106921 --- /dev/null +++ b/doc/source/content-writing/rst-files-writers/collapsible-sections.rst @@ -0,0 +1,28 @@ +.. _collapsible_sections: + +Collapsible sections +==================== + +When information is applicable only to a subset of your users or provides +more comprehensive information than most users need, you can use collapsible +sections. Then, only users who either need or want to view this information +can expand these sections. + +.. note:: + To use collapsible sections in your PyAnsys documentation, you must install + the ``sphinx_toolbox.collapse`` extension and then add it to the ``conf.py`` + file in the ``doc/source`` directory and to your list of documentation requirements. + For more information, see :ref:`add_sphinx_extensions`. + + To see and use the collapsible sections that are shown only as an image on this page, + see :ref:`artifact_download`. To see how the collapsible sections on this + page are formatted, click the **Show Source** link in the page's right pane. + As described in :ref:`rst_file_formatting`, you can copy content from the + TXT version of this file and then paste it directly into one of your RST files + for reuse, modifying it as needed. + +Here is an image of the three collapsible sections. Clicking a collapsible section expands it +so that additional information is shown. + +.. image:: ..//_static/collapsible_sections.png + :alt: Collapsible sections for downloading artifacts diff --git a/doc/source/content-writing/rst-files-writers/doc-links.rst b/doc/source/content-writing/rst-files-writers/doc-links.rst index 3d05725c8..b4fa9ad67 100644 --- a/doc/source/content-writing/rst-files-writers/doc-links.rst +++ b/doc/source/content-writing/rst-files-writers/doc-links.rst @@ -241,23 +241,29 @@ To link to Python objects in your API reference documentation, you use Python-sp For a list of these roles, see `Cross-referencing Python objects `_ in the Sphinx documentation. For descriptions of fundamental Python objects, see :ref:`py_file_format`. -If the role links to a Python object in the same module, you can use only the object name +If the role links to a Python object in the same module, you only need to use the object name in the role (as shown in the first of the following three examples). If the role links to a Python object in a different module, you must use the module name and object name in the role (as shown in the second and third of the following three examples). Python uses a period (``.``) to denote submodules. If you need to see where a Python object is -defined in your documentation, use the GitHub search function. For example, to see where the -``class Primitives3DLayout`` class is defined in PyAEDT, search its repository for this string: +defined in your API, use the GitHub search function. For example, to see where the +``Primitives3DLayout`` class is defined in the PyAEDT API, search its repository for this string: ``class Primitives3DLayout`` -Search results indicate that this class is defined in ``pyaedt.modeler.Primitives3DLayout.Primitives3DLayout``. +Search results indicate that this class is defined here: ``pyaedt.modeler.Primitives3DLayout.Primitives3DLayout``. + +.. tip:: + Because using the full module name and object name in the role always works, when you perform a + search to see where a Python object is defined, consider collecting the result in a TXT file. When + you next need to link to this object, you can easily search this text file for the object name + and then copy its full module name and object name into your RST file. Examples of Python object links ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Here are some examples of how you use Python-specific roles to link to Python objects. +Here are some examples of using Python-specific roles to link to Python objects. **Example 1** @@ -273,7 +279,7 @@ Assuming that your project is PyMAPDL, you can use the ``func`` role to link to ``run_batch()`` function in the PyMAPDL API reference documentation:: You can use the pool to run a set of pre-generated input files using the - :func:`run_batch ` method. + :func:`run_batch ` function. **Example 3** @@ -282,7 +288,7 @@ Also assuming that your project is PyMAPDL, you can use both the ``func`` and ``selected_nodes`` attribute in the PyMAPDL API reference documentation:: If you have subselected a certain component and want to also limit the result of a certain output - (:func:`nodal_displacement() `), use the + (:func:`nodal_displacement `), use the :attr:`selected_nodes ` attribute to get a mask of the currently selected nodes. diff --git a/doc/source/content-writing/rst-files-writers/index.rst b/doc/source/content-writing/rst-files-writers/index.rst index 2a59bc8a6..4de4f8fee 100644 --- a/doc/source/content-writing/rst-files-writers/index.rst +++ b/doc/source/content-writing/rst-files-writers/index.rst @@ -55,6 +55,7 @@ this **Content in RST files** section:: tables cards tab-sets + collapsible-sections The ``maxdepth`` attribute of the ``toctree`` directive specifies the maximum number of heading levels to show in the documentation's right pane, labeled **On this page**. In this @@ -145,3 +146,4 @@ file. However, the GitHub renderer is unaware of the ``links.rst`` file. For mor tables cards tab-sets + collapsible-sections diff --git a/doc/source/content-writing/rst-files-writers/rst-format-rules.rst b/doc/source/content-writing/rst-files-writers/rst-format-rules.rst index 87dd431d1..c2194ecd7 100644 --- a/doc/source/content-writing/rst-files-writers/rst-format-rules.rst +++ b/doc/source/content-writing/rst-files-writers/rst-format-rules.rst @@ -83,20 +83,23 @@ page in the *Goggle developer documentation style guide*. * List item 4 * List item 5 -- Indicate a code entity within a paragraph by surrounding it in double backticks - (:code:`\`\``). Always follow a code entity with a noun that indicates the object type. In the - documentation, a code entity is rendered in a monospaced font within a gray block. - (While the `numpydoc Style guide `_ says to - surround a code entity in a single backtick, this renders it incorrectly in - italics in PyAnsys documentation.) Code entities include the names of Python - objects, such as packages, modules, functions, classes, instances, methods, and - attributes. In PyAnsys documentation, also surround the following objects - in double backticks: +- Indicate a code entity within text by surrounding it in double backticks + (:code:`\`\``). While the `numpydoc Style guide `_ + says to surround a code entity in a single backtick, this renders it incorrectly + as italics in PyAnsys documentation. Surrounding it in double backticks + correctly renders it in a monospaced font within a gray block. + + Always follow a code entity with a noun that indicates the object type. For general + guidelines, see `Code in text `_ in the *Google developer + documentation style guide*. + + Code entities include the names of Python objects, such as packages, modules, functions, + classes, methods, and attributes. Code entities also include the following objects: - File paths - Names of directories, files, and environment variables - Text to type in a command line or in a GUI component - + .. note:: Some PyAnsys projects use the ``file`` and ``envvar`` interpretive text roles for names of files and environment variables: diff --git a/doc/source/content-writing/rst-files-writers/tab-sets.rst b/doc/source/content-writing/rst-files-writers/tab-sets.rst index da062cfe1..beb15cb7c 100644 --- a/doc/source/content-writing/rst-files-writers/tab-sets.rst +++ b/doc/source/content-writing/rst-files-writers/tab-sets.rst @@ -10,8 +10,10 @@ for different operating systems. .. note:: To use tab sets in your PyAnsys documentation, you must install - and configure the `sphinx-design `_ - extension. For more information, see :ref:`add_sphinx_extensions`. + the `sphinx-design `_ extension and then add + it to the ``conf.py`` file in the ``doc/source`` directory and to your + list of documentation requirements. For more information, see + :ref:`add_sphinx_extensions`. To see and use the tab sets that are shown only as images on this page, see :ref:`setting_up_dev_environment`. To see how the tab sets on this diff --git a/doc/source/doc-style/docstrings.rst b/doc/source/doc-style/docstrings.rst index 2d1c2ce8c..15cda7ca4 100644 --- a/doc/source/doc-style/docstrings.rst +++ b/doc/source/doc-style/docstrings.rst @@ -3,8 +3,8 @@ Numpydoc docstrings =================== -When writing docstrings for PyAnsys libraries, use the `numpydoc`_ -style. +When writing docstrings for PyAnsys libraries, follow the syntax and best practices +described in `Style guide `_ in the *numpydoc Manual*. 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 @@ -13,20 +13,23 @@ must then 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 `Quick reStructuredText +`_ for a markup summary. -Surround any text that you want to set apart as literal text in double back ticks to render -it in a gold monospaced font. Use double back ticks to surround the names of files, folders, -classes, methods, and variables. For example:: +Surround any text that you want to set apart as literal text (code entities) in double backticks +to render it in a monospaced font within a gray box. Use double backticks 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 backticks to surround the names of classes, methods, and - variables, not the single backtick that is recommended by the numpydoc - style. + While the numpydoc style guide says to surround the names of classes, methods, and + variables in a single backtick, you must use double backticks. Surrounding text in + a single backtick in a PyAnsys library formats it in italic type rather than as a + code entity. Required docstring sections --------------------------- @@ -53,7 +56,7 @@ raises 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 ``"GL01"`` checking must be +see :ref:`Numpydoc validation` because ``"GL01"`` checking must be turned off. The guidelines for documenting short summaries differ for classes versus @@ -63,7 +66,7 @@ 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 +always start the brief description for a class with a verb ending in "s" followed by an extended summary in a new line if additional information is needed:: class FieldAnalysis3D(Analysis): @@ -81,7 +84,7 @@ 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 +libraries, always start the brief description for a method with a verb not ending in "s" followed 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): @@ -96,17 +99,17 @@ written descriptions for private methods are 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 +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. You should include examples to demonstrate usage. +only the GET method. You should include examples to demonstrate usage. Parameters ---------- Functions may have parameters in their signatures. All these parameters should be documented in -the ``Parameters`` section. +the "Parameters" section. -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 @@ -129,7 +132,7 @@ Here is an example of a ``Parameters`` section for a class in PyAEDT: 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. + nothing is used if no setup is active. 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. @@ -148,19 +151,39 @@ Here is an example of a ``Parameters`` section for a class in PyAEDT: 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 displays a default -in the function signature. For an optional parameter, the data type is followed by a -comma and ``optional``. +in the function, class, or method signature. For an optional parameter, the +data type is followed by a comma and ``optional`` or ``default:`` followed by a +space and then the value (if supported). + +For example, if the library in the preceding example supported specifying the default +after the data type, the description for the ``close_on_exit`` parameter would look +like this: + +.. code-block:: rst -The brief description for a parameter is generally a sentence fragment. However, + close_on_exit : bool, default: False + Whether to release AEDT on exit. + +The brief description for a parameter is a sentence fragment. However, all 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. +parameter, if the behavior that occurs when the default is used is unclear, +the behavior should be described. The preceding "Parameters" section provides +many examples. However, here is how you would format the description for the +``setup_name`` parameter if the default is specified after the data type: + +.. code-block:: rst + + setup_name : str, default: None + Name of the setup to use as the nominal. If ``None``, + the active setup is used or nothing is used if no + setup is active. Returns ------- -The ``Returns`` section contains only the return data type and a brief description -that concludes with a period: +A class does not have a "Returns" section. However functions and methods +generally do a "Returns" section. This section contains the return data type +and a brief description of what is returned, which is followed by a period: .. code-block:: rst @@ -170,8 +193,7 @@ that concludes with a period: 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: +If a Boolean is returned, format the "Returns" section like this: .. code-block:: rst @@ -180,7 +202,7 @@ A class does not have a ``Returns`` section. If a ``Boolean`` is returned, forma bool ``True`` when successful, ``False`` when failed. -It is possible for the ``Returns`` section to look like the ``Parameters`` section +It is possible for the "Returns" section to look like the "Parameters" section if variable names are provided: .. code-block:: rst @@ -190,7 +212,7 @@ if variable names are provided: has_succeeded : bool ``True`` when successful, ``False`` when failed. -It is possible for more than one item to be returned: +It is also possible for more than one item to be returned: .. code-block:: rst @@ -203,16 +225,16 @@ It is possible for more than one item to be returned: 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. Examples -------- -The ``Examples`` section provides one or more small code samples that make usage +The "Examples" section provides one or more small code samples that make usage of a method or function clear. They provide an easy place to start when trying out the API. -Here is a sample ``Examples`` section from a Python file for PyAEDT. +Here is a sample "Examples" section from a Python file for PyAEDT. .. code-block:: rst @@ -227,12 +249,12 @@ Here is a sample ``Examples`` section from a Python file for PyAEDT. pyaedt info: Active design is set to... -Code supplied in an ``Examples`` section must be compliant with the +Code supplied in an "Examples" section must be compliant with the `doctest `_ format. This allows the code to be used through `pytest`_ to perform regression testing to verify that the code is executing as expected. -If the definition of a method or function is updated, the code in the ``Examples`` section +If the definition of a method or function is updated, the code in the "Examples" section must be updated. Any change within the API without a corresponding change in the example code triggers a ``doctest`` failure. @@ -243,13 +265,17 @@ feature of maintainable documentation. Type hints ---------- -By default, Sphinx renders `type hints `_ as part -of the function signature. This can become difficult to read because the signature -becomes very long. +.. vale off + +By default, Sphinx renders type hints as part of the function signature per +`PEP 484 – Type Hints `_. This can become difficult +to read because the signature becomes very long. + +.. vale off Instead, you should render type hints as part of each parameter's description. To accomplish this, you must combine the ``sphinx.ext.autodoc.typehints``, ``sphinx.ext.napoleon``, -and ``numpydoc`` extensions in the ``conf.py`` file: +and ``numpydoc`` extensions in the ``conf.py`` file in this order: .. code:: python @@ -262,30 +288,22 @@ and ``numpydoc`` extensions in the ``conf.py`` file: ] autodoc_typehints = "description" -.. note:: - - The order in which you include these extensions matters. - -When using type hints in this way, the type information in the ``Parameters`` -and ``Returns`` sections can be omitted. +When using type hints in this way, you can omit the type information in the "Parameters" +and "Returns" sections. Additional directives --------------------- -Because Python docstrings are written using RST syntax, it is possible to take -advantage of some directives available in this Markup language. Commonly used -directives follow. - -- ``note``: Highlights important information in the rendered documentation. - -- ``warning``: Typically points out an action that might result in data loss. - -- ``deprecated``: ``X.Y.Z`` informs the user about the deprecated status of - the object or feature. +Because Python docstrings are written using reStructuredText syntax, you can take +advantage of some of the directives available in this plaintext markup language. +Here are some Sphinx directives that can be used in docstrings, although they +should be used sparingly as they do not look very good in text terminals. -You can find additional information and examples in the numpy doc. Reference -this documentation as the primary source regarding docstring styles for directives -that are not covered here. +- ``note``: Highlights important information to be aware of. +- ``warning``: Points out an action that might result in data loss or cause + some other issue, such as performance degradation. +- ``deprecated``: ``X.Y.Z`` Indicates the deprecation status of an object or + feature. Example ------- diff --git a/doc/source/doc-style/formatting-tools.rst b/doc/source/doc-style/formatting-tools.rst index b445b8caa..32646ea10 100644 --- a/doc/source/doc-style/formatting-tools.rst +++ b/doc/source/doc-style/formatting-tools.rst @@ -18,7 +18,7 @@ The ``blacken-docs`` tool When writing documentation, code blocks are frequently used to provide examples. However, these code snippets cannot be verified with the usual code formatting tools. This is where `blacken-docs`_ comes into play. You can execute -this tool by running: +this tool by running this command: .. code:: bash @@ -31,7 +31,7 @@ The `codespell`_ tool checks for common misspellings in text files. This implies is not limited to Python files but can run checks on any human-readable file. It is possible to ignore words that are flagged as misspelled. You can specify these words in a -file that can then be passed to ``codespell`` by running: +file that can then be passed to ``codespell`` by running this command: .. code:: bash @@ -90,7 +90,7 @@ 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 +``conf.py`` file. For more information, see :ref:`The \`\`doc\`\` directory`. Start by adding it to the list of extensions: .. code-block:: python @@ -137,7 +137,7 @@ For PyAnsys libraries, ``Vale`` is configured to apply the guidelines in the along with any custom Ansys rules and terminology lists, to reStructuredText (RST) and Markdown (MD) files. -After a PyAnsys team member implements ``Vale`` in your PyAnsys library, you can check +When ``Vale`` is implemented in your PyAnsys library, you can check any content changes that you make in supported files locally. In the library's ``doc`` folder, download the package with this command: @@ -146,23 +146,22 @@ In the library's ``doc`` folder, download the package with this command: vale sync -Check all files in the ``doc`` folder with this command: +Check all files in the ``doc`` folder by running this command: .. code-block:: bash vale . -Check all files in the repository by going to the ``root`` directory and running +To check all files in the repository, go to the ``root`` directory and run this command: .. code-block:: bash vale --config=doc/.vale.ini . -Check all files in only a particular folder by typing ``vale`` followed by the +To check all files in only a particular folder, type ``vale`` followed by the name of the folder. Address any warnings and issues that display by either editing the -file to fix or adding a term to the ``accept.txt`` file under the -``doc`` folder in ``styles\config\vocabularies\ANSYS``. - +file to fix or adding a term to the ``accept.txt`` file in +``doc\styles\config\vocabularies\ANSYS``. diff --git a/doc/source/getting-started/index.rst b/doc/source/getting-started/index.rst index 620cd305f..8b734824f 100644 --- a/doc/source/getting-started/index.rst +++ b/doc/source/getting-started/index.rst @@ -34,7 +34,7 @@ ecosystem. Here are some examples: - Machine learning using `TensorFlow `_ .. note:: - If you are new to GitHub, see `The ReadMe Project + If you are new to GitHub and open source projects, see `The ReadMe Project `_. This monthly newsletter highlights the best from the open source software community, providing links to feature articles, developer stories, guides, and podcasts. diff --git a/doc/source/how-to/code/pyansys_logging.py b/doc/source/how-to/code/pyansys_logging.py index 96faa9180..1178ac8e6 100644 --- a/doc/source/how-to/code/pyansys_logging.py +++ b/doc/source/how-to/code/pyansys_logging.py @@ -162,7 +162,7 @@ def filter(self, record): class Logger: """Logger used for each PyProject session. - This class allows you to add a handler to a file or standard output. + This class lets you add a handler to a file or standard output. Parameters ---------- diff --git a/doc/source/how-to/contributing.rst b/doc/source/how-to/contributing.rst index 0e93c7df4..b519c7b79 100644 --- a/doc/source/how-to/contributing.rst +++ b/doc/source/how-to/contributing.rst @@ -149,7 +149,7 @@ Install a library in editable mode ---------------------------------- You can install a Python library in *editable mode*, which -allows you to modify the source code and have these new changes +lets you modify the source code and have these new changes reflected in your Python environment. To install a Python library in editable mode: @@ -269,6 +269,6 @@ Use GitHub CLI Because developers do not like leaving their terminals when working in projects, GitHub offers a `command-line interface (CLI) `_. -This program allows you to interact with most of the features available in the +This program lets you interact with most of the features available in the web version of GitHub. For available commands, see the `GitHub CLI `_ documentation. diff --git a/doc/source/how-to/dns-configuration.rst b/doc/source/how-to/dns-configuration.rst index b9660aae1..43d7fbb26 100644 --- a/doc/source/how-to/dns-configuration.rst +++ b/doc/source/how-to/dns-configuration.rst @@ -81,7 +81,7 @@ CNAME takeover prevention CNAME values have been taken over in the past by external users, typically due to these reasons: -* Ansys GitHub organizations had no domain verification set up. +* The Ansys GitHub organizations had no domain verification set up. * A CNAME created did not follow the recommended CNAME guidelines. * More than one level of subdomain depth under the verified domain had been requested. * Long time lapses occurred between CNAME creation and assignment to GitHub pages. diff --git a/doc/source/how-to/documenting.rst b/doc/source/how-to/documenting.rst index a0d61f0fb..3a7f6ad4d 100644 --- a/doc/source/how-to/documenting.rst +++ b/doc/source/how-to/documenting.rst @@ -49,7 +49,7 @@ these extensions for docstring formatting: Using the ``numpydoc`` extension is preferred because it supports an API documentation structure with one page per method, providing Python community members with documentation like that generated for the -`numpy`_ and `pandas`_ packages. If your API is very linear, you +`NumPy`_ and `pandas`_ packages. If your API is very linear, you can use the ``napoleon`` extension because it supports a documentation structure where everything needed to solve a certain problem can be shown on one page. @@ -64,11 +64,11 @@ For more information, see :ref:`Documentation style`. .. _rst_files_developers: -RST files -~~~~~~~~~ +reStructuredText files +~~~~~~~~~~~~~~~~~~~~~~ To provide general usage information in your documentation, use your favorite -editor to create RST (ReStructuredText) files that you then place in +editor to create reStructuredText (RST) files that you then place in :ref:`The \`\`doc\`\` directory`. The ``index.rst`` file in the ``doc/source`` directory defines the first level of your documentation hierarchy. The ``toctree`` directive (which stands for "table of contents tree") indicates the maximum @@ -179,6 +179,8 @@ sections in your library's documentation: - ``Contributing``: Refers to the *PyAnsys developer's guide* for overall guidance and then provides library-specific contribution information. +For comprehensive information on writing content, see :ref:`content_writing`. + Examples ~~~~~~~~ @@ -246,7 +248,7 @@ Document Python code -------------------- You can use the native ``sphinx.ext.autodoc`` extension to generate documentation from your Python -code. When using this extension, you can include these directives in your :ref:`RST files`: +code. When using this extension, you can include these directives in your RST files: * ``automodule``: For documenting modules * ``autoclass``: For documenting classes @@ -484,37 +486,37 @@ maturity. Follow these steps to enable multi-version documentation in your library: -- Use `ansys-sphinx-theme `_ 0.8 or later for building - your library's documentation. -- Include the following lines in :ref:`The \`\`conf.py\`\` file`: +#. Use `ansys-sphinx-theme `_ 0.8 or later for building + your library's documentation. +#. Include the following lines in :ref:`The \`\`conf.py\`\` file`: - .. code-block:: python + .. code-block:: python - import os + import os - from ansys_sphinx_theme import get_version_match + from ansys_sphinx_theme import get_version_match - cname = os.getenv("DOCUMENTATION_CNAME", "") - """The canonical name of the webpage hosting the documentation.""" + cname = os.getenv("DOCUMENTATION_CNAME", "") + """The canonical name of the webpage hosting the documentation.""" - html_theme_options = { - "switcher": { - "json_url": f"https://{cname}/versions.json", - "version_match": get_version_match(__version__), - }, - ... - } - - .. admonition:: About the ``DCOUMENTATION_CNAME`` environment variable + html_theme_options = { + "switcher": { + "json_url": f"https://{cname}/versions.json", + "version_match": get_version_match(__version__), + }, + ... + } + + .. admonition:: About the ``DOCUMENTATION_CNAME`` environment variable - The ``DOCUMENTATION_CNAME`` environment variable is expected to be - declared in the YML file controlling the deployment of the documentation. - The idea is that the canonical name (CNAME) is only defined in a single - place, so it can be easily changed if required. + The ``DOCUMENTATION_CNAME`` environment variable is expected to be + declared in the YML file controlling the deployment of the documentation. + The idea is that the canonical name (CNAME) is only defined in a single + place, so it can be easily changed if required. -- Enable documentation deployment for development and stable versions. For more - information, see :ref:`Deploy documentation`. +#. Enable documentation deployment for development and stable versions. For more + information, see :ref:`Deploy documentation`. With all the previous configuration, your library is ready to use multi-version documentation in an automated way. This means that every time you release a @@ -522,8 +524,7 @@ new version, a link to the documentation for this version is added to the drop-down button in the upper right corner of the documentation's title bar. You use this drop-down button to switch from viewing the documentation for the latest stable release to viewing the documentation for the development version -or previously -released versions. +or previously released versions. .. admonition:: Controlling the number of versions shown in the drop-down button @@ -656,15 +657,15 @@ not compatible with older `ansys/actions` versions. To perform the migration, follow these steps: -* Update all the continuous integration ``YML`` files to use - ``ansys/actions@v4`` or higher. +#. Update all the continuous integration ``YML`` files to use + ``ansys/actions@v4`` or higher. -* Make sure that the ``"json_url"`` key points to - ``f"https://{cname}/versions.json"``. Note that the ``release/`` substring is - dropped. +#. Make sure that the ``"json_url"`` key points to + ``f"https://{cname}/versions.json"``. Note that the ``release/`` substring is + dropped. -* Apply previous steps as fix patches in all the desired versions to be included - in the multi-version documentation. +#. Apply previous steps as fix patches in all the desired versions to be included + in the multi-version documentation. Access online documentation --------------------------- @@ -737,39 +738,39 @@ a search engine for multi-version documentation in your project. ... } - #. In these lines, replace ** with the desired name for your MeiliSearch index. +#. In these lines, replace ** with the desired name for your MeiliSearch index. - The ``convert_version_to_pymeilisearch`` function converts your package's version into - a format suitable for MeiliSearch indexing. + The ``convert_version_to_pymeilisearch`` function converts your package's version into + a format suitable for MeiliSearch indexing. - #. Enable documentation index deployment for development and stable versions using GitHub Actions: +#. Enable documentation index deployment for development and stable versions using GitHub Actions: - .. code-block:: yaml - - jobs: - doc-deploy-index: - name: "Index the documentation and scrap using PyMeilisearch" - runs-on: ubuntu-latest - needs: doc-deploy - if: github.event_name == 'push' - steps: - - name: Scrape the stable documentation to PyMeilisearch - run: | - VERSION=$(python -c "from import __version__; print('.'.join(__version__.split('.')[:2]))") - VERSION_MEILI=$(python -c "from import __version__; print('-'.join(__version__.split('.')[:2]))") - echo "Calculated VERSION: $VERSION" - echo "Calculated VERSION_MEILI: $VERSION_MEILI" - - - name: "Deploy the latest documentation index" - uses: ansys/actions/doc-deploy-index@v4.1 - with: - cname: ".docs.pyansys.com/version/$VERSION" - index-name: "v$VERSION_MEILI" - host-url: "" - api-key: ${{ secrets.MEILISEARCH_API_KEY }} + .. code-block:: yaml + + jobs: + doc-deploy-index: + name: "Index the documentation and scrap using PyMeilisearch" + runs-on: ubuntu-latest + needs: doc-deploy + if: github.event_name == 'push' + steps: + - name: Scrape the stable documentation to PyMeilisearch + run: | + VERSION=$(python -c "from import __version__; print('.'.join(__version__.split('.')[:2]))") + VERSION_MEILI=$(python -c "from import __version__; print('-'.join(__version__.split('.')[:2]))") + echo "Calculated VERSION: $VERSION" + echo "Calculated VERSION_MEILI: $VERSION_MEILI" + + - name: "Deploy the latest documentation index" + uses: ansys/actions/doc-deploy-index@v4.1 + with: + cname: ".docs.pyansys.com/version/$VERSION" + index-name: "v$VERSION_MEILI" + host-url: "" + api-key: ${{ secrets.MEILISEARCH_API_KEY }} #. Replace **, **, and ** with appropriate values for your project. - The version of your package is automatically calculated and used for indexing, ensuring that your documentation - remains up to date. For more information, see the `PyMeilisearch`_ and `ansys-sphinx-theme-doc`_ documentation. +The version of your package is automatically calculated and used for indexing, ensuring that your documentation +remains up to date. For more information, see the `PyMeilisearch`_ and `ansys-sphinx-theme-doc`_ documentation. diff --git a/doc/source/how-to/grpc-api-packages.rst b/doc/source/how-to/grpc-api-packages.rst index 1c8d543cd..78973f4ce 100644 --- a/doc/source/how-to/grpc-api-packages.rst +++ b/doc/source/how-to/grpc-api-packages.rst @@ -40,7 +40,7 @@ The Ansys GitHub organization has a dedicated template repository for creating PROTO file repositories and the needed files to generate the Python API packages to be consumed by the PyAnsys clients. -To set up an API repository like the ```ansys-api-mapdl`` one, +To set up an API repository like the ``ansys-api-mapdl`` one, select the `ansys-api-template `_ repository when creating a repository within the Ansys GitHub organization. diff --git a/doc/source/how-to/logging.rst b/doc/source/how-to/logging.rst index 03752d739..046447056 100644 --- a/doc/source/how-to/logging.rst +++ b/doc/source/how-to/logging.rst @@ -5,7 +5,7 @@ The following logging guidelines are best practices discovered through implement logging services and modules within PyAnsys libraries. Suggestions and improvements are welcomed. -For logging techniques, see the `Logging HOWTO +For logging techniques, see `Logging HOWTO `_ in the Python documentation. These tutorials are particularly helpful: @@ -131,6 +131,9 @@ errors occur, they are reported as logging errors and do not halt code. logger.info("Project %s has been opened.", project.GetName()) + +.. _app_and_services_logging: + App and service logging modules ------------------------------- diff --git a/doc/source/how-to/packaging.rst b/doc/source/how-to/packaging.rst index 5ef738bf5..da222afec 100644 --- a/doc/source/how-to/packaging.rst +++ b/doc/source/how-to/packaging.rst @@ -424,7 +424,7 @@ Dependabot allows for two different types of updates: a best practice for *run-time* dependencies (that is, the usage of a package should support the oldest available version if possible). Thus, it is only recommended to fully pin **documentation** and **testing** requirements (that is, using ``==``). Having the latest - dependencies available in your requirements testing files allows you to test the + dependencies available in your requirements testing files lets you test the *latest* packages against your library. Dependabot version updates diff --git a/doc/source/how-to/releasing.rst b/doc/source/how-to/releasing.rst index 0779bfc49..5a413f019 100644 --- a/doc/source/how-to/releasing.rst +++ b/doc/source/how-to/releasing.rst @@ -12,7 +12,7 @@ to create a successful release. .. attention:: A project must be authorized to be publicly released. For an explanation - of the process, see:ref:`Project approval and public release`. + of the process, see :ref:`Project approval and public release`. Semantic versioning ------------------- @@ -29,7 +29,7 @@ notation can also be understand as ``MAJOR.MINOR.PATCH``: * A ``PATCH`` version is when you make backwards-compatible bug fixes. To match the versioning methodology used by the "big three" data science Python -packages, `numpy`_, `scipy`_, and `pandas`_, ``MAJOR`` versions of PyAnsys +packages, `NumPy`_, `SciPy`_, and `pandas`_, ``MAJOR`` versions of PyAnsys packages are not released when any incompatible API change is made but rather when major, globally breaking API changes are made. @@ -279,7 +279,7 @@ Replace ```` with the private PyPI token. .. dropdown:: Use GitHub Actions - The following code allows you to publish Python :ref:`Artifacts` in + The following code lets you publish Python :ref:`Artifacts` in the ``dist`` directory to the private PyPI. This code is expected to be included when you :ref:`Use GitHub Actions`: @@ -354,13 +354,13 @@ Public PyPI Publishing :ref:`Artifacts` to `PyPI`_ is the way of distributing :ref:`Python libraries`. Publishing to `PyPI`_ requires a username and a password: -+-------------------------------------------+----------------+ -| Credentials for publishing to public PyPI | Value | -+===========================================+================+ -| Username | ``__token__`` | -+-------------------------------------------+----------------+ -| Password | ``PYPI_TOKEN`` | -+-------------------------------------------+----------------+ ++-----------------------------------------------+----------------+ +| **Credentials for publishing to public PyPI** | **Value** | ++===============================================+================+ +| Username | ``__token__`` | ++-----------------------------------------------+----------------+ +| Password | ``PYPI_TOKEN`` | ++-----------------------------------------------+----------------+ The ``PYPI_TOKEN`` is a password in the form of a GitHub secret. This secret is unique to each project. It can only be obtained after the first release to the @@ -382,7 +382,7 @@ Replace ```` and ```` with the package name and pr .. dropdown:: Use GitHub Actions - The following code allows you to publish any Python :ref:`Artifacts` contained in + The following code lets you publish any Python :ref:`Artifacts` contained in the ``dist`` directory to the public PyPI. It is expected to be included when you :ref:`Use GitHub Actions`. @@ -414,7 +414,7 @@ For enabling public visibility of a repository, follow the process explained in .. dropdown:: Use GitHub Actions - The following code allows you to publish any Python :ref:`Artifacts` contained in + The following code lets you publish any Python :ref:`Artifacts` contained in the ``dist`` directory to the GitHub release created. It is expected to be included when you :ref:`Use GitHub Actions`: @@ -429,6 +429,8 @@ For enabling public visibility of a repository, follow the process explained in with: library-name: "ansys--" +.. _artifact_download: + Artifact download ----------------- diff --git a/doc/source/how-to/setting-up.rst b/doc/source/how-to/setting-up.rst index 40b6b9927..ff1e7c33e 100644 --- a/doc/source/how-to/setting-up.rst +++ b/doc/source/how-to/setting-up.rst @@ -306,7 +306,7 @@ Dynamic It is possible to configure Git such that it selects between multiple configuration profiles according to whether your project is located on your system. -This allows you to define common configurations for working under +This lets you define common configurations for working under ``Ansys`` or other open source projects from which Ansys benefits. As an example, consider the following scenario for setting up two Git diff --git a/doc/source/how-to/supporting-python-versions.rst b/doc/source/how-to/supporting-python-versions.rst index a8b2858c0..9f48927c3 100644 --- a/doc/source/how-to/supporting-python-versions.rst +++ b/doc/source/how-to/supporting-python-versions.rst @@ -7,17 +7,17 @@ more information, see `Status of Python versions `_ in the *Python Developer's Guide*. -+---------+------------+-------------+-----------------------+--------+ -| Version | PEP | Released | Security Support Ends | Status | -+---------+------------+-------------+-----------------------+--------+ -| 3.12 | `PEP 693`_ | 02 Oct 2023 | Oct 2028 | Stable | -+---------+------------+-------------+-----------------------+--------+ -| 3.11 | `PEP 664`_ | 03 Oct 2022 | Oct 2027 | Stable | -+---------+------------+-------------+-----------------------+--------+ -| 3.10 | `PEP 619`_ | 04 Oct 2021 | Oct 2026 | Stable | -+---------+------------+-------------+-----------------------+--------+ -| 3.9 | `PEP 596`_ | 05 Oct 2020 | Oct 2025 | Stable | -+---------+------------+-------------+-----------------------+--------+ ++-------------+----------------+-----------------+---------------------------+------------+ +| **Version** | **PEP** | **Released** | **Security support ends** | **Status** | ++-------------+----------------+-----------------+---------------------------+------------+ +| 3.12 | `PEP 693`_ | 02 Oct 2023 | Oct 2028 | Stable | ++-------------+----------------+-----------------+---------------------------+------------+ +| 3.11 | `PEP 664`_ | 03 Oct 2022 | Oct 2027 | Stable | ++-------------+----------------+-----------------+---------------------------+------------+ +| 3.10 | `PEP 619`_ | 04 Oct 2021 | Oct 2026 | Stable | ++-------------+----------------+-----------------+---------------------------+------------+ +| 3.9 | `PEP 596`_ | 05 Oct 2020 | Oct 2025 | Stable | ++-------------+----------------+-----------------+---------------------------+------------+ .. _PEP 693: https://peps.python.org/pep-0693/ .. _PEP 664: https://peps.python.org/pep-0664/ diff --git a/doc/source/how-to/testing.rst b/doc/source/how-to/testing.rst index a9d0f4841..c8add8569 100644 --- a/doc/source/how-to/testing.rst +++ b/doc/source/how-to/testing.rst @@ -173,7 +173,7 @@ integration, and functional. Each PyAnsys project should have all three levels of testing implemented in its testing framework. Consider implementing functional tests as examples within -your project's documentation examples. This allows you to write helpful +your project's documentation examples. This lets you write helpful user-facing tests while accomplishing functional testing. Unit testing @@ -437,7 +437,7 @@ If you do not configure code coverage properly, the resulting report does not show the real scope covered by the test suite. Assuming that a ``PyAnsys`` project follows :ref:`The \`\`src\`\` directory` layout, -you must pass the following flag when :ref:`Test execution`: +you must pass the following flag when :ref:`executing tests `: .. code-block:: text diff --git a/doc/source/links.rst b/doc/source/links.rst index 255670533..370348fb9 100644 --- a/doc/source/links.rst +++ b/doc/source/links.rst @@ -129,6 +129,7 @@ .. #Google dev doc guide links: .. _Google_dev_doc_style_guide: https://developers.google.com/style .. _Google_dev_doc_articles: https://developers.google.com/style/articles +.. _Google_dev_doc_code_in_text: https://developers.google.com/style/code-in-text .. _Google_dev_doc_headings: https://developers.google.com/style/headings .. _Google_dev_doc_highlights: https://developers.google.com/style/highlights .. _Google_dev_doc_link_text: https://developers.google.com/style/link-text diff --git a/doc/source/packaging/build-systems.rst b/doc/source/packaging/build-systems.rst index 4bddeac10..08a713b81 100644 --- a/doc/source/packaging/build-systems.rst +++ b/doc/source/packaging/build-systems.rst @@ -29,7 +29,7 @@ PyAnsys project. The interaction between the maintainer and the build system is performed using a build system tool. This tool provides both a frontend and a backend. The maintainers trigger the frontend, which then calls the backend to read the -project directory and generate the artifacts, as :numref:`build system diag` shows. +project directory and generate the artifacts. .. include:: diag/build_system_diag.rst @@ -53,8 +53,7 @@ PEP 517 ------- PEP 517 allows Python developers to specify the build-backend tool for -generating artifacts. :numref:`build system diag` shows the -most popular backends: +generating artifacts. The earlier image shows the most popular backends: - Setuptools, while very popular, lacks the ability to declare build-time dependencies and is difficult to extend. @@ -123,9 +122,9 @@ to manage virtual environments on their own. Developers must: Flit is the default tool for creating a new PyAnsys project when using the `Ansys templates `_. -The ``[project]`` section specifies the project's metadata and required -dependencies. For more information, see `flit pyproject.toml -guidelines`_. +The ``[project]`` section specifies the project's metadata and required dependencies. +For more information, see `The pyproject.toml config file `_ +in the Flit documentation. Poetry ------ diff --git a/doc/source/packaging/structure.rst b/doc/source/packaging/structure.rst index 8f62cb656..88fcc43a0 100644 --- a/doc/source/packaging/structure.rst +++ b/doc/source/packaging/structure.rst @@ -84,9 +84,9 @@ Differences between a Python package and library ------------------------------------------------ Although the terms *package* and *library* are often used interchangeably, there is -a key difference between them. A Python package is a collection of Python modules and -subpackages, while a Python library is a collection of Python packages. -:numref:`python pkg lib diag` exposes this. +a key difference between them. As shown in the following image, a Python package is +a collection of Python modules and subpackages, while a Python library is a collection +of Python packages. .. include:: diag/python_library_diag.rst @@ -124,8 +124,8 @@ A PyAnsys project typically has these documentation sections: project-specific contribution information Projects in the PyAnsys ecosystem take advantage of `Sphinx`_, a tool for -building documentation for Python-based projects. As shown in :numref:`doc structure diag`, -Sphinx requires a ``doc`` directory with a specific structure: +building documentation for Python-based projects. Sphinx requires a ``doc`` +directory with a specific structure: .. include:: diag/doc_structure_diag.rst @@ -143,7 +143,7 @@ Sphinx requires a ``doc`` directory with a specific structure: The ``source`` directory must contain at least these files: -- ``conf.py``: Python script that declares the configuration of `Sphinx`_. +- ``conf.py``: Python script that declares the `Sphinx`_ configuration. The minimum required configuration is explained in :ref:`The \`\`conf.py\`\` file`. - ``index.rst``: Main index (landing) page for the overall documentation. Some @@ -173,8 +173,7 @@ There are different approaches available for creating a namespace. Ansys namespaces use the `native namespace packages`_ from `PEP 420`_. -Therefore, the source directory of any PyAnsys library must look like the one -in :numref:`src structure diag`: +Therefore, the source directory of any PyAnsys library must look like this: .. include:: diag/src_structure_diag.rst @@ -229,7 +228,7 @@ Covenant Code of Conduct*, which is very popular across open source projects. The ``CONTRIBUTING.md`` file ---------------------------- -You use the `CONTRIBUTING.md`` file to provide a quick entry-point for developers +You use the ``CONTRIBUTING.md`` file to provide a quick entry-point for developers who are willing to contribute to the project. It usually provides references to this information: @@ -293,7 +292,7 @@ The ``README`` file should at the minimum contain these elements: their ""README`` files. In the main ``index.rst`` files for their documentation, they then use a grid of cards to visually explain and link to documentation sections. This keeps the ``README`` file focused on why you might want to explore the - library and allows you to quickly view documentation sections of interest. + library and lets you quickly view documentation sections of interest. The ``README.rst`` file is also reused within the project file metadata. It is usually included in the ``long-description`` field. diff --git a/doc/source/packaging/templates.rst b/doc/source/packaging/templates.rst index ad2015c71..b591a519e 100644 --- a/doc/source/packaging/templates.rst +++ b/doc/source/packaging/templates.rst @@ -66,7 +66,7 @@ PyAnsys advanced template The ``pyansys-advanced`` template is an enhanced version of the ``pyansys`` template. It ships with the same directories and files and supports additional features: -- Allows you to select the project file (``setup.py`` or ``pyproject.toml``) +- lets you select the project file (``setup.py`` or ``pyproject.toml``) - Uses `tox`_ for testing and task automation - Includes `GitHub Actions`_ for CI purposes - Uses `pre-commit`_ for checking coding style diff --git a/doc/styles/config/vocabularies/ANSYS/accept.txt b/doc/styles/config/vocabularies/ANSYS/accept.txt index b3899eada..76fcda396 100644 --- a/doc/styles/config/vocabularies/ANSYS/accept.txt +++ b/doc/styles/config/vocabularies/ANSYS/accept.txt @@ -9,6 +9,7 @@ Brinkrolf CI/CD CLI CNAME +config CSV Codespell [Cc]omponentization @@ -85,6 +86,7 @@ rebasing recurse reusability Rey +reStructuredText REST RPC RST