diff --git a/.gitignore b/.gitignore index 8a3c8ff71..d74d9965e 100644 --- a/.gitignore +++ b/.gitignore @@ -165,3 +165,7 @@ cython_debug/ # Sphinx autogen doc/source/how-to/api/* +doc/source/sg_execution_times.rst + +# rstcheck +.rstcheck.cfg \ No newline at end of file diff --git a/README.rst b/README.rst index d7db227b9..e28f6b2b9 100644 --- a/README.rst +++ b/README.rst @@ -1,8 +1,8 @@ -######################### -PyAnsys Developer's Guide -######################### -The `PyAnsys Developer's Guide `_ is the central +PyAnsys developer's guide +========================= + +The `PyAnsys developer's guide `_ is the central document for: - Ansys developers who want to create and "own" PyAnsys libraries diff --git a/doc/source/abstractions/data-transfer.rst b/doc/source/abstractions/data-transfer.rst index 600af1ca7..dca4780d9 100644 --- a/doc/source/abstractions/data-transfer.rst +++ b/doc/source/abstractions/data-transfer.rst @@ -69,15 +69,16 @@ within the MAPDL database. REST versus RPC data and model abstraction ------------------------------------------ + Because of the nature of most Ansys products, apps and services can either fit into the Remote Procedure Call (RPC) interface, where the API is centered around operations and commands, or the REST model, where the API is centered around resources. Regardless of the interface style, there are several items to consider. - API chattiness ~~~~~~~~~~~~~~ + APIs must be efficient to avoid creating chatty input and output. Because many Ansys products fit well with the RPC API implementation, there is a temptation to design APIs that require constant communication @@ -93,6 +94,7 @@ expose only a limited number of RPC methods in the front-facing API. Compatibility and efficiency ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + APIs should be designed to be compatible with as many languages and platforms as possible. `gRPC`_ for RPC-like interfaces should be one of the first choices due to its compatibility with nearly all popular diff --git a/doc/source/abstractions/index.rst b/doc/source/abstractions/index.rst index e425d6616..87a1526e9 100644 --- a/doc/source/abstractions/index.rst +++ b/doc/source/abstractions/index.rst @@ -1,5 +1,5 @@ Abstractions -############ +============ Abstraction in Python is the process of hiding the real implementation of an app from the user and emphasizing only usage. diff --git a/doc/source/coding-style/code/tox-flit.rst b/doc/source/coding-style/code/tox-flit.rst index ef8bf4544..a2880d51e 100644 --- a/doc/source/coding-style/code/tox-flit.rst +++ b/doc/source/coding-style/code/tox-flit.rst @@ -3,7 +3,7 @@ [tox] description = Default tox environments list envlist = - style,{py37,py38,py39,py310}{,-coverage},doc + style,{py39,py310,py311,py312}{,-coverage},doc skip_missing_interpreters = true isolated_build = true isolated_build_env = build @@ -11,10 +11,10 @@ [testenv] description = Checks for project unit tests and coverage (if desired) basepython = - py37: python3.7 - py38: python3.8 py39: python3.9 py310: python3.10 + py311: python3.11 + py312: python3.12 py: python3 {style,reformat,doc,build}: python3 setenv = diff --git a/doc/source/coding-style/code/tox-poetry.rst b/doc/source/coding-style/code/tox-poetry.rst index c44d4e654..123d4d9d5 100644 --- a/doc/source/coding-style/code/tox-poetry.rst +++ b/doc/source/coding-style/code/tox-poetry.rst @@ -3,17 +3,17 @@ [tox] description = Default tox environments list envlist = - style,{py37,py38,py39,py310}{,-coverage},doc + style,{py39,py310,py311,py312}{,-coverage},doc skip_missing_interpreters = true isolated_build = true [testenv] description = Checks for project unit tests and coverage (if desired) basepython = - py37: python3.7 - py38: python3.8 py39: python3.9 py310: python3.10 + py311: python3.11 + py312: python3.12 py: python3 {style,reformat,doc,build}: python3 skip_install = true diff --git a/doc/source/coding-style/deprecation.rst b/doc/source/coding-style/deprecation.rst index 4cf651883..e6f2041dc 100644 --- a/doc/source/coding-style/deprecation.rst +++ b/doc/source/coding-style/deprecation.rst @@ -1,5 +1,6 @@ Deprecation best practices ========================== + While deprecation best practices are outlined in a `Stack Overflow Answer `_ and in this `Deprecation library `_ , diff --git a/doc/source/coding-style/formatting-tools.rst b/doc/source/coding-style/formatting-tools.rst index 003b75fa3..711d63a80 100644 --- a/doc/source/coding-style/formatting-tools.rst +++ b/doc/source/coding-style/formatting-tools.rst @@ -9,9 +9,9 @@ Most of the tools presented can be configured using :ref:`the \`\`pyproject.toml\`\` file`. Avoiding dotfiles leads to a much cleaner root project directory. - Black ----- + `Black`_ is the most popular code formatter in the Python community because it is maintained by the Python Software Foundation. It allows for a minimum configuration to ensure that the Python code format looks almost the same across @@ -28,8 +28,9 @@ The minimum `black`_ configuration for a PyAnsys project should look like this: line-length = "" -Isort ------ +The ``isort`` +------------- + The goal of `isort`_ is to properly format ``import`` statements by making sure that they follow the standard order: @@ -37,8 +38,7 @@ that they follow the standard order: #. third-party libraries #. custom libraries - -When using `isort`_ with `black`_, it is important to properly configure both +When using `isort`_ with `Black`_, it is important to properly configure both tools so that no conflicts arise. To accomplish this, use the ``--profile black`` flag in `isort`_. @@ -51,11 +51,11 @@ tools so that no conflicts arise. To accomplish this, use the default_section = "THIRDPARTY" src_paths = ["doc", "src", "tests"] - Flake8 ------ -The goal of `flake8` is to act as a `PEP 8`_ compliance checker. Again, if -this tool is being used with `black`_, it is important to make sure that no + +The goal of `Flake8` is to act as a `PEP 8`_ compliance checker. Again, if +this tool is being used with `Black`_, it is important to make sure that no conflicts arise. The following configuration is the minimum one to set up `flake8`_ together with @@ -100,6 +100,7 @@ The example configuration defines these options: Add-license-headers ------------------- + The goal of the ``add-license-headers`` pre-commit hook is to add and update license headers for files with `REUSE `_. By default, the hook runs on PROTO files in any directory and on Python files in the ``src``, ``examples``, and ``tests`` directories. @@ -110,9 +111,9 @@ You can find the MIT license that is added to the files in For information on customizing the hook, see the `README ` file. - Code coverage ------------- + Code coverage indicates the percentage of the codebase tested by the test suite. Code coverage should be as high as possible to guarantee that every piece of code has been tested. @@ -132,8 +133,9 @@ project: [tool.coverage.report] show_missing = true -Pre-commit ----------- +The ``pre-commit`` +------------------ + To ensure that every commit you make is compliant with the code style guidelines for PyAnsys, you can take advantage of `pre-commit`_ in your project. Every time you stage some changes and try to commit them, `pre-commit`_ only @@ -144,7 +146,6 @@ The configuration for `pre-commit`_ must be defined in a `pre-commit`_ configuration that includes both code and documentation formatting tools. - .. code-block:: yaml repos: @@ -183,6 +184,7 @@ formatting tools. Installing ``pre-commit`` ~~~~~~~~~~~~~~~~~~~~~~~~~ + You can install ``pre-commit`` by running: .. code-block:: bash @@ -197,6 +199,7 @@ Then, ensure that you install it as a ``Git hook`` by running: Using ``pre-commit`` ~~~~~~~~~~~~~~~~~~~~ + One installed as described, ``pre-commit`` automatically triggers every time that you try to commit a change. If any hook defined in `.pre-commit-config.yaml` fails, you must fix the failing files, stage the new changes, and try to commit @@ -213,6 +216,7 @@ the hooks fail. Tox --- + You might consider using `tox`_ in your project. While this automation tool is similar to `Make`_, it supports testing of your package in a temporary virtual environment. Being able to test your package in isolation rather than in @@ -221,7 +225,6 @@ virtual environment. Being able to test your package in isolation rather than in Configuration for `tox`_ is stored in a ``tox.ini`` file. The minimum configuration for a PyAnsys ``py-`` project should be: - .. tab-set:: .. tab-item:: Tox with Flit @@ -232,21 +235,20 @@ configuration for a PyAnsys ``py-`` project should be: .. include:: code/tox-poetry.rst - -This minimum configuration assumes that you have a ``requirements/`` directory that -contains ``requirements_tests.txt`` and ``requirements_doc.txt``. In +This minimum configuration assumes that you have a ``requirements`` directory that +contains ``requirements_tests.txt`` and ``requirements_doc.txt`` files. In addition, the ``style`` environment must execute ``pre-commit``, which guarantees the usage of this tool in your project. Installing ``tox`` ~~~~~~~~~~~~~~~~~~ + You can install ``tox`` like any other Python package: .. code-block:: bash python -m pip install tox - Using ``tox`` ~~~~~~~~~~~~~ @@ -262,10 +264,9 @@ It is possible to run multiple environments by separating them with commas ``tox -e ,,...```. To run all available environments, simply run ``tox``. - .. LINKS AND REFERENCES -.. _black: https://black.readthedocs.io/en/latest/ +.. _Black: https://black.readthedocs.io/en/latest/ .. _isort: https://pycqa.github.io/isort/ .. _flake8: https://flake8.pycqa.org/en/latest/ .. _pre-commit: https://pre-commit.com/ diff --git a/doc/source/coding-style/index.rst b/doc/source/coding-style/index.rst index 85870a74e..b278c2a1b 100644 --- a/doc/source/coding-style/index.rst +++ b/doc/source/coding-style/index.rst @@ -1,5 +1,6 @@ Coding style -############ +============ + Coding style refers to the different rules defined in a software project that must be followed when writing source code. These rules ensure that all the source code looks the same across different files of the diff --git a/doc/source/coding-style/pep8.rst b/doc/source/coding-style/pep8.rst index 6ab144e10..ba3755801 100644 --- a/doc/source/coding-style/pep8.rst +++ b/doc/source/coding-style/pep8.rst @@ -1,5 +1,6 @@ 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`_ to increase the readability of Python code. Some of the most popular @@ -11,13 +12,14 @@ including `numpy`_, `scipy`_, and `pandas`_. .. _scipy: https://www.scipy.org/ .. _pandas: https://pandas.pydata.org/ - Imports ------- + Code style guidelines follow for ``import`` statements. Import location ~~~~~~~~~~~~~~~ + Imports should always be placed at the top of the file, just after any module comments and docstrings and before module global variables and constants. This reduces the likelihood of an `ImportError`_ that @@ -46,11 +48,9 @@ might only be discovered during runtime. return math.log(8, x) - - - Import order ~~~~~~~~~~~~ + For better readability, group imports in this order: #. Standard library imports @@ -62,7 +62,6 @@ so that they are easily searchable. .. tab-set:: - .. tab-item:: Use .. code-block:: python @@ -90,9 +89,9 @@ so that they are easily searchable. def compute_logbase8(x): return math.log(8, x) - Multiple imports ~~~~~~~~~~~~~~~~ + You should place imports in separate lines unless they are modules from the same package. @@ -127,12 +126,12 @@ package. Absolute versus relative imports ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + You should use absolute imports over relative imports because they are more readable and reliable. . tab-set:: - .. tab-item:: Use .. code-block:: python @@ -144,9 +143,9 @@ more readable and reliable. from .core.plotting import general_plotter - Import namespaces ~~~~~~~~~~~~~~~~~ + You should avoid using wildcards in imports because doing so can make it difficult to detect undefined names. For more information, see `Python Anti-Patterns: using wildcard imports @@ -154,7 +153,6 @@ Anti-Patterns: using wildcard imports .. tab-set:: - .. tab-item:: Use .. code-block:: python @@ -169,6 +167,7 @@ Anti-Patterns: using wildcard imports Naming conventions ------------------ + To achieve readable and maintainable code, use concise and descriptive names for classes, methods, functions, and constants. Regardless of the programming language, you must follow these global rules to determine the correct names: @@ -180,16 +179,16 @@ global rules to determine the correct names: #. Replace magic numbers with named constants. #. Avoid encodings. Do not append prefixes or type information. - Variables ~~~~~~~~~ + 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. - Packages and modules ~~~~~~~~~~~~~~~~~~~~ + Use a short, lowercase word or words for module names. Separate words with underscores to improve readability. For example, use ``module.py`` or ``my_module.py``. @@ -202,9 +201,9 @@ from PyPI. python -m pip install package - Classes ~~~~~~~ + Use `camel case `_ when naming classes. Do not separate words with underscores. @@ -215,9 +214,9 @@ classes. Do not separate words with underscores. ... - Functions and methods ~~~~~~~~~~~~~~~~~~~~~ + Use a lowercase word or words when naming Python functions or methods. To improve readability, separate words with underscores. @@ -271,6 +270,7 @@ When naming methods, follow these conventions: Variables ~~~~~~~~~ + Use a lowercase single letter, word, or words when naming variables. To improve readability, separate words with underscores. @@ -291,6 +291,7 @@ To improve readability, separate words with underscores. Indentation and line breaks --------------------------- + Proper and consistent indentation is important to producing easy-to-read and maintainable code. In Python, use four spaces per indentation level and avoid tabs. @@ -378,6 +379,7 @@ Instead of: Maximum line length ------------------- + For source code, best practice is to keep the line length at or below 100 characters. For docstrings and comments, best practice is to keep the length at or below 72 characters. @@ -386,7 +388,6 @@ Lines longer than these recommended limits might not display properly on some terminals and tools or might be difficult to follow. For example, this line is difficult to follow: - .. tab-set:: .. tab-item:: Use @@ -417,6 +418,7 @@ desired value without breaking the syntax rules. Comments -------- + Because a PyAnsys library generally involves multiple physics domains, people reading its source code do not have the same background as the developers who wrote it. This is why it is important for a library @@ -458,9 +460,9 @@ Otherwise, future developers might remove code that they see as unnecessary. obj.update_cache() obj.write(filename) - Inline comments ~~~~~~~~~~~~~~~ + Use inline comments sparingly. An inline comment is a comment on the same line as a statement. @@ -495,9 +497,9 @@ descriptive variable names. x = "John Smith" # Student Name - Docstrings ~~~~~~~~~~ + A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition. A docstring becomes the doc special attribute of the object. @@ -521,17 +523,17 @@ For a multi-line docstring, put the ending ``"""`` on a line by itself. For more information on docstrings for PyAnsys libraries, see :ref:`Documentation style`. - Programming recommendations --------------------------- -The following sections provide some `PEP8 + +The following sections provide some `PEP 8 `_ recommendations for removing ambiguity and preserving consistency. Additionally, they address some common pitfalls that occur when writing Python code. - Booleans and comparisons ~~~~~~~~~~~~~~~~~~~~~~~~ + Don't compare Boolean values to ``True`` or ``False`` using the equivalence operator. @@ -596,11 +598,10 @@ In ``if`` statements, use ``is not`` rather than ``not ...``. Also, avoid ``if x:`` when you mean ``if x is not None:``. This is especially important when parsing arguments. - Handling strings ~~~~~~~~~~~~~~~~ -Use ``.startswith()`` and ``.endswith()`` instead of slicing. +Use ``.startswith()`` and ``.endswith()`` instead of slicing. .. tab-set:: @@ -624,9 +625,9 @@ Use ``.startswith()`` and ``.endswith()`` instead of slicing. if file_name[-4:] == ".jpg": print("The file is a JPEG.") - Reading the Windows registry ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Never read the Windows registry or write to it because this is dangerous and makes it difficult to deploy libraries on different environments or operating systems. @@ -645,9 +646,9 @@ systems. "", ) - Duplicated code -~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~' + Follow the DRY principle, which states that "Every piece of knowledge must have a single, unambiguous, authoritative representation within a system." Follow this principle unless it overly complicates @@ -655,7 +656,6 @@ the code. For instance, the following example converts Fahrenheit to Kelvin twice, which now requires the developer to maintain two separate lines that do the same thing. - .. tab-set:: .. tab-item:: Use @@ -692,7 +692,6 @@ that do the same thing. temp2 = 46 new_temp_k = ((temp2 - 32) * (5 / 9)) + 273.15 - This is a trivial example, but you can apply this approach for a variety of both simple and complex algorithms and workflows. Another advantage of this approach is that you can implement unit testing @@ -710,9 +709,9 @@ Now, you have only one line of code to verify. You can also use a testing framework such as ``pytest`` to test that the method is correct. - Nested blocks ~~~~~~~~~~~~~ + Avoid deeply nested block structures (such as conditional blocks and loops) within one single code block. @@ -733,7 +732,6 @@ within one single code block. # recursive e = self.validate_something(a, b, d) - Aside from the lack of comments, this complex method is difficult to debug and validate with unit testing. It would be far better to implement more validation methods and join conditional @@ -743,9 +741,9 @@ For a conditional block, the maximum depth recommended is four. If you think you need more for the algorithm, create small functions that are reusable and unit-testable. - Loops ~~~~~ + While there is nothing inherently wrong with nested loops, to avoid certain pitfalls, steer clear of having loops with more than two levels. In some cases, you can rely on coding mechanisms like list comprehensions @@ -778,7 +776,6 @@ to circumvent nested loops. >>> print(f"{squares = }") squares = [0, 1, 4, 9, 16, 25, 36, 49, 64, 81] - If the loop is too complicated for creating a list comprehension, consider creating small functions and calling these instead. For example, to extract all consonants in a sentence: @@ -822,7 +819,6 @@ example, to extract all consonants in a sentence: The second approach is more readable and better documented. Additionally, you could implement a unit test for ``is_consonant``. - Security considerations ----------------------- diff --git a/doc/source/coding-style/required-standard.rst b/doc/source/coding-style/required-standard.rst index ec0b678ec..c93ac5c0e 100644 --- a/doc/source/coding-style/required-standard.rst +++ b/doc/source/coding-style/required-standard.rst @@ -8,7 +8,6 @@ individual configurations for the tools presented in :ref:`Code style tools` and The following lines should be included in :ref:`The \`\`pyproject.toml\`\` file` to indicate the configuration of the different code and documentation style tools. - Required ``pyproject.toml`` configuration ----------------------------------------- @@ -36,9 +35,9 @@ Required ``pyproject.toml`` configuration [tool.pydocstyle] convention = "numpy" +Required ``flake8`` configuration +--------------------------------- -Required ``.flake8`` configuration ----------------------------------- The following ``.flake8`` file is also required: .. code-block:: toml @@ -47,13 +46,11 @@ The following ``.flake8`` file is also required: max-line-length = 88 extend-ignore = 'E203' - Required ``pre-commit`` configuration ------------------------------------- -You can take advantage of :ref:`Pre-commit` by including a +You can take advantage of :ref:`the \`\`pre-commit\`\`` by including a ``.pre-commit-config.yaml`` file like this one in your project: - .. code-block:: yaml repos: @@ -85,9 +82,9 @@ You can take advantage of :ref:`Pre-commit` by including a additional_dependencies: [toml] exclude: "tests/" - GitHub CI/CD integration ------------------------ + Finally, you can :ref:`Test using GitHub actions` and create a ``style.yml`` workflow file in ``.github/workflows/``: diff --git a/doc/source/conf.py b/doc/source/conf.py index d23c3a09d..5d1230b63 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -36,6 +36,7 @@ "show_prev_next": False, "show_breadcrumbs": True, "use_edit_page_button": True, + "header_links_before_dropdown": 6, # number of links before the dropdown menu "additional_breadcrumbs": [ ("PyAnsys", "https://docs.pyansys.com/"), ], diff --git a/doc/source/doc-style/doc-configuration.rst b/doc/source/doc-style/doc-configuration.rst index 3ec562601..0d5aa56bc 100644 --- a/doc/source/doc-style/doc-configuration.rst +++ b/doc/source/doc-style/doc-configuration.rst @@ -1,6 +1,7 @@ Required Sphinx configuration ============================= -The following page explains the minimum required `Sphinx`_ configuration for + +This page explains the minimum required `Sphinx`_ configuration for building the documentation of a PyAnsys library. When installing `Sphinx`_, a program named ``sphinx-build`` also gets installed. @@ -12,9 +13,9 @@ a ``Makefile`` (for POSIX systems) or a ``make.bat`` file (for Windows systems). Once the ``sphinx-build`` command is triggered, the configuration declared in the ``conf.py`` file is applied when rendering the documentation pages. - The ``conf.py`` file -------------------- + The following ``conf.py`` file provides the minimum required configuration for a PyAnsys library. To guarantee consistency across PyAnsys libraries, you should only make custom additions on top of this configuration. @@ -23,9 +24,10 @@ only make custom additions on top of this configuration. Automation files ---------------- -As indicated earlier in this topic, the ``sphinx-build`` program and + +As indicated earlier on this page, the ``sphinx-build`` program and all its options and arguments can be automated by using a -``Makefile`` file or a `make.bat`` file. These files should be placed at the +``Makefile`` file or a ``make.bat`` file. These files should be placed at the first level of :ref:`The \`\`doc/\`\` directory`, next to the ``source/`` directory. @@ -46,9 +48,9 @@ Notice that both files contain a ``SPHINXOPTS`` variable with these flags: ``-j` A special rule named ``pdf`` is also included. This rule is in charge of generating a PDF file for the library's documentation. - Example for ``Makefile`` ^^^^^^^^^^^^^^^^^^^^^^^^ + The following code collects the required options and automation rules for the ``Makefile`` program to use when building documentation for a PyAnsys library: @@ -56,6 +58,7 @@ The following code collects the required options and automation rules for the Example for ``make.bat`` ^^^^^^^^^^^^^^^^^^^^^^^^ + The following code collects the required options and automation rules for the ``make.bat`` program to use when building documentation for a PyAnsys project: diff --git a/doc/source/doc-style/docstrings.rst b/doc/source/doc-style/docstrings.rst index 6e8df797d..8e6e9e965 100644 --- a/doc/source/doc-style/docstrings.rst +++ b/doc/source/doc-style/docstrings.rst @@ -1,5 +1,5 @@ Numpydoc docstrings -################### +=================== When writing docstrings for PyAnsys libraries, use the `numpydoc`_ style. @@ -20,15 +20,13 @@ 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 `numpydoc`_ + The PyAnsys style uses two backticks to surround the names of classes, methods, and + variables, not the single backtick that is recommended by `numpydoc`_ style. - Required docstring sections -=========================== +--------------------------- PyAnsys library docstrings contain these `numpydoc`_ sections as a minimum: @@ -41,9 +39,9 @@ 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. - 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:`Documentation style tools` @@ -61,6 +59,7 @@ 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 in a new line if additional information is needed:: @@ -78,6 +77,7 @@ Ensure that there is a line break between the end of a class docstring and the s 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 in a new line if additional information is needed:: @@ -100,6 +100,7 @@ just 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. @@ -155,6 +156,7 @@ 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: @@ -237,7 +239,7 @@ examples must always match the API that they are documenting, they are an import 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 @@ -247,8 +249,6 @@ Instead, you should render type hints as part of each parameter's description. T accomplish this, you must combine the ``sphinx.ext.autodoc.typehints``, ``sphinx.ext.napoleon``, and ``numpydoc`` extensions in the ``conf.py`` file: - - .. code:: python extensions = [ @@ -268,7 +268,8 @@ When using type hints in this way, the type information in the ``Parameters`` and ``Returns`` sections can be omitted. 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 include: @@ -284,9 +285,8 @@ 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. - Example -======= +------- Here is a generic docstring example compliant with PyAnsys guidelines: diff --git a/doc/source/doc-style/formatting-tools.rst b/doc/source/doc-style/formatting-tools.rst index 033efd6e5..11e4bb252 100644 --- a/doc/source/doc-style/formatting-tools.rst +++ b/doc/source/doc-style/formatting-tools.rst @@ -1,5 +1,6 @@ Documentation 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 @@ -9,22 +10,22 @@ Most of the tools presented can be configured using :ref:`the \`\`pyproject.toml\`\` file`, avoiding dotfiles and thus leading to a much cleaner root project directory. +The ``blacken-docs`` +-------------------- -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 +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 the `blacken-docs`_ comes into play. You can execute this tool by running: .. code:: bash blacken-docs -l doc/**/*.rst +The ``codespell`` +----------------- -Codespell ---------- -`Codespell`_ checks for common misspellings in text files. This implies that it +The `codespell`_ checks for common misspellings in text files. This implies that it 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 @@ -34,25 +35,24 @@ file that can then be passed to `Codespell` by running: codespell --write-changes --ignore-words= +The ``docformatter`` +-------------------- -Docformatter ------------- -`Docformatter`_ automatically formats Python docstrings according -to `PEP 257`_. To make sure `Docformatter`_ wraps your docstrings at a given +The `docformatter`_ automatically formats Python docstrings according +to `PEP 257`_. To make sure `docformatter`_ wraps your docstrings at a given number of characters, use the following configuration: - .. code:: bash docformatter -r -i --wrap-summaries --wrap-descriptions src +The ``doctest`` +--------------- -Doctest -------- -`Doctest`_ is a module from the Python standard library, which means it is +The `doctest`_ is a module from the Python standard library, which means it is included by default with your Python installation. It is used for checking the examples provided inside docstrings to make sure that they reflect the current usage -of the source code. `Doctest`_ can be integrated with ``pytest`` in :ref:`The +of the source code. The `doctest`_ can be integrated with ``pytest`` in :ref:`The \`\`pyproject.toml\`\` file`: .. code:: toml @@ -60,10 +60,10 @@ of the source code. `Doctest`_ can be integrated with ``pytest`` in :ref:`The [tool.pytest.ini_options] addopts = "--doctest-modules" +The ``interrogate`` +------------------- -Interrogate ------------ -`Interrogate`_ is a tool for checking docstring coverage. Similar to source code +The `interrogate`_ is a tool for checking docstring coverage. Similar to source code coverage tools, this tool tests how many functions, classes, and modules in a Python library hold a docstring. @@ -81,6 +81,7 @@ for source code coverage. Numpydoc validation ------------------- + To validate the style of :ref:`Numpydoc docstrings`, you can 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 @@ -112,11 +113,13 @@ For a complete list of available checks, see the `full mapping of validation checks `_. -Pydocstyle ----------- -`Pydocstyle`_ is a tool for checking the compliance of Python docstrings with `PEP -257`_. Its configuration can be defined in the :ref:`The \`\`pyproject.toml\`\` -file`. By default, `Pydocstyle`_ matches all ``*.py`` files except those starting with +The ``pydocstyle`` +------------------ + +The `pydocstyle`_ is a tool for checking the compliance of Python docstrings with `PEP +257`_. Its configuration can be defined in the +:ref:`the \`\`pyproject.toml\`\` file`. +By default, `pydocstyle`_ matches all ``*.py`` files except those starting with ``test_*.py``. The default configuration should be enough for a PyAnsys project. However, if additional configuration is needed, it must be included it under the ``[tool.pydocstyle]`` entry: @@ -126,9 +129,9 @@ it under the ``[tool.pydocstyle]`` entry: [tool.pydocstyle] convention = "numpy" - Vale ---- + `Vale`_ is a tool for maintaining a consistent style and voice in your documentation. Its configuration is defined in a ``.vale.ini`` file in the library's ``doc`` folder. For PyAnsys libraries, ``Vale`` is configured to apply the guidelines in the @@ -177,3 +180,4 @@ file to fix or adding a term to the ``accept.txt`` file under the .. _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 +.. _pydocstyle: https://www.pydocstyle.org/en/stable/ diff --git a/doc/source/doc-style/index.rst b/doc/source/doc-style/index.rst index cb878a43e..fe8571112 100644 --- a/doc/source/doc-style/index.rst +++ b/doc/source/doc-style/index.rst @@ -1,5 +1,5 @@ Documentation style -################### +=================== Good API documentation drives library adoption and usage and is the foundation for a good developer experience. Even with the best diff --git a/doc/source/getting-started/administration.rst b/doc/source/getting-started/administration.rst index a6180b2ec..ad87d2525 100644 --- a/doc/source/getting-started/administration.rst +++ b/doc/source/getting-started/administration.rst @@ -1,11 +1,13 @@ Project approval and public release =================================== + Most of the projects in PyAnsys expose the functionality of Ansys products. Due to intellectual property reasons, the public release of a PyAnsys library must go through a project approval process. First steps ----------- + To trigger the public release process, project leads must fill in this form: * `Release request workflow initiation form `_ @@ -16,6 +18,7 @@ Source project, then continue to the next section. Approval process ---------------- + The approval process is divided into three parts: .. grid:: 3 @@ -54,7 +57,6 @@ When releasing a project to the public, you should: * Maintain the project by means of fixing bugs and providing support for new releases. * Uphold Ansys' reputation in the open source community. - Once all three approvals have been awarded, project leads must complete the next form: @@ -66,6 +68,7 @@ asked questions in :ref:`Questions asked in the OSS approval request form`. Managerial ^^^^^^^^^^ + The managerial part of the approval process ensures that the direct manager, general managers, vice presidents, or the chief technology officer are aware of the project's existence and status. @@ -92,9 +95,9 @@ number of administrative reviews and approvals needed: approval from the direct manager, product line, and the chief technology officer. No product source code is allowed. - Legal ^^^^^ + Legal review approval ensures that the entire project complies with Ansys' legal policies. @@ -128,9 +131,9 @@ Open source dependencies not distributed as part of the project do not need their licenses included in the Ansys repository. Examples include dependent Node Package Manager (``npm``) modules or Python packages from PyPI. - Technical ^^^^^^^^^ + Technical approval ensures that the project follows the best and latest software development practices. Request a technical review by sending an email to `pyansys.core@ansys.com `_. diff --git a/doc/source/getting-started/basic.rst b/doc/source/getting-started/basic.rst index 347c08579..7ecd5be12 100644 --- a/doc/source/getting-started/basic.rst +++ b/doc/source/getting-started/basic.rst @@ -66,7 +66,6 @@ particular PyAnsys library. Once you have completed this checklist, change the `repository visibility`_ to public and create a release branch. - .. todo:: gRPC - Starting Guide diff --git a/doc/source/getting-started/index.rst b/doc/source/getting-started/index.rst index 46db4156d..f7e9aabe3 100644 --- a/doc/source/getting-started/index.rst +++ b/doc/source/getting-started/index.rst @@ -1,6 +1,6 @@ -############### + Getting started -############### +=============== The PyAnsys project exposes Ansys technologies via libraries in the Python ecosystem. Each library provides clear, concise, and @@ -50,9 +50,9 @@ ecosystem. Examples include: .. _PyAEDT: https://github.com/ansys/PyAEDT .. _PyMAPDL: https://github.com/ansys/pymapdl - Contributing to this guide ~~~~~~~~~~~~~~~~~~~~~~~~~~ + If you would like to contribute to this development guide, maintainers gladly review all pull requests. For more information, see :ref:`Documentation style`. diff --git a/doc/source/how-to/code/build.yml b/doc/source/how-to/code/build.yml index cdb50c920..2e044b269 100644 --- a/doc/source/how-to/code/build.yml +++ b/doc/source/how-to/code/build.yml @@ -4,7 +4,7 @@ build-wheelhouse: strategy: matrix: os: [ubuntu-latest, windows-latest] - python-version: ['3.7', '3.8', '3.9', '3.10'] + python-version: ['3.9', '3.10', '3.11', '3.12'] steps: - name: "Build a wheelhouse of the Python library" uses: ansys/actions/build-wheelhouse@v4 diff --git a/doc/source/how-to/code/tests.yml b/doc/source/how-to/code/tests.yml index 162d3fb98..0f7de96bc 100644 --- a/doc/source/how-to/code/tests.yml +++ b/doc/source/how-to/code/tests.yml @@ -4,7 +4,7 @@ tests: strategy: matrix: os: [ubuntu-latest, windows-latest] - python-version: ['3.7', '3.8', '3.9', '3.10'] + python-version: ['3.9', '3.10', '3.11', '3.12'] steps: - name: "Run pytest" uses: ansys/actions/tests-pytest@v4 diff --git a/doc/source/how-to/compatibility.rst b/doc/source/how-to/compatibility.rst index 0f28113fc..1ea484ac2 100644 --- a/doc/source/how-to/compatibility.rst +++ b/doc/source/how-to/compatibility.rst @@ -1,5 +1,6 @@ Ansys product compatibility -============================ +=========================== + As the different PyAnsys libraries evolve, backward and forward compatibility issues can occur. Some of the most common cases are: @@ -17,6 +18,7 @@ following their approach is recommended. ``check_version.py`` module approach ------------------------------------ + A *version checking* module determines whether the Ansys product server you are connecting to provides support for certain operations. For implementation examples, see the ``check_version.py`` files for the following PyAnsys libraries: @@ -40,11 +42,11 @@ in the same way as the minimum version mechanism works. ``version_requires`` decorator ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + The ``@version_requires`` decorator applies version logic to the different functionalities and methods available in the client. You can see how this decorator is used in `ansys/dpf/core/check_version.py`_. Here is a generalized example: - .. code:: python class Client: diff --git a/doc/source/how-to/continuous-integration.rst b/doc/source/how-to/continuous-integration.rst index 80f647ce7..c404f5726 100644 --- a/doc/source/how-to/continuous-integration.rst +++ b/doc/source/how-to/continuous-integration.rst @@ -1,5 +1,6 @@ Using continuous integration ============================ + Continuous Integration (CI) is the process of merging new changes into the main code base while ensuring that these changes are functional and do not break the existing logic. @@ -10,18 +11,20 @@ and ensure a quick development workflow. Because ``PyAnsys`` projects are hosted in `GitHub `_, the `GitHub Actions `_ framework is used. - Enable GitHub actions --------------------- + By default, ``Actions`` are enabled in new repositories and can be accessed using the associated :ref:`GitHub repository sections`. If ``Actions`` are not enabled, you can enable them by changing ``Actions -Permissions`` in ``Settings -> Actions -> General``. +Permissions`` in +``Settings -> Actions -> General``. Use GitHub actions ------------------ + Actions to be executed in the CI process must be declared in a ``YML`` and stored in the ``.github/workflows/`` directory. Although each action is different, they all have a common structure: @@ -46,7 +49,6 @@ different, they all have a common structure: jobs: - Disable concurrent workflows ---------------------------- @@ -78,6 +80,7 @@ automatically cancel pre-existing workflows for a certain branch/PR. To do so, p Required workflows ------------------ + These workflows are required for any ``PyAnsys`` project: - :ref:`Coding style` workflow @@ -88,9 +91,9 @@ These workflows are required for any ``PyAnsys`` project: You should collect all workflows under a common ``ci.yml`` file. For more information, see :ref:`Workflow examples`. - Parametrize workflows --------------------- + It is important to test a ``PyAnsys`` library on different operating systems using different Python versions: @@ -118,7 +121,7 @@ Consider this example of a parametrized workflow example: example_matrix: strategy: matrix: - python: ['3.7', '3.8', '3.9', '3.10'] + python: ['3.9', '3.10', '3.11', '3.12'] os: [windows-latest, macos-latest, ubuntu-latest] steps: @@ -128,22 +131,22 @@ Consider this example of a parametrized workflow example: .. code-block:: text - Running Python 3.7 in windows-latest - Running Python 3.8 in windows-latest Running Python 3.9 in windows-latest Running Python 3.10 in windows-latest - Running Python 3.7 in macos-latest - Running Python 3.8 in macos-latest + Running Python 3.11 in windows-latest + Running Python 3.12 in windows-latest Running Python 3.9 in macos-latest Running Python 3.10 in macos-latest - Running Python 3.7 in ubuntu-latest - Running Python 3.8 in ubuntu-latest + Running Python 3.11 in macos-latest + Running Python 3.12 in macos-latest Running Python 3.9 in ubuntu-latest Running Python 3.10 in ubuntu-latest - + Running Python 3.11 in ubuntu-latest + Running Python 3.12 in ubuntu-latest Workflow examples ----------------- + Workflow examples are provided for checking :ref:`Coding style`, :ref:`Documenting`, :ref:`Testing`, and :ref:`Releasing and publishing`. @@ -159,19 +162,16 @@ Workflow examples are provided for checking :ref:`Coding style`, .. literalinclude:: code/tests.yml :language: yaml - .. tab-item:: docs.yml .. literalinclude:: code/docs.yml :language: yaml - .. tab-item:: build.yml .. literalinclude:: code/build.yml :language: yaml - .. tab-item:: release.yml .. literalinclude:: code/release.yml diff --git a/doc/source/how-to/contributing.rst b/doc/source/how-to/contributing.rst index ed4957019..45b95497d 100644 --- a/doc/source/how-to/contributing.rst +++ b/doc/source/how-to/contributing.rst @@ -1,5 +1,6 @@ Contributing ============ + Before contributing to a PyAnsys repository, you must understand the general coding paradigms being used for PyAnsys development. @@ -27,7 +28,6 @@ coding paradigms being used for PyAnsys development. #. Review the Ansys `Code of Conduct `_. - All ``PyAnsys`` projects are hosted in `GitHub `_ in the form of :ref:`Git` repositories. GitHub is a platform that not only provides storage for projects but also additional features like code reviews or issue @@ -37,12 +37,12 @@ boards.
- +
- Create a GitHub account ----------------------- + To use GitHub, start by creating an account for the platform. Follow the `GitHub Join Process `_. @@ -50,8 +50,6 @@ For Ansys employees: If you would like to join the `Ansys GitHub Organization `_, visit `Join Ansys GitHub Organization `_. - - GitHub repository sections -------------------------- @@ -77,6 +75,7 @@ your access level determines tabbed sections you can see. Create an issue --------------- + You create an issue to either report a bug or request help or a new feature. Commenting allows you to interact with other users, developers, and project maintainers. @@ -90,6 +89,7 @@ files. For more information, see `Basic writing and formatting syntax Request new features ~~~~~~~~~~~~~~~~~~~~ + If you would like a new feature to be added to a PyAnsys library, you open a new issue and select either the template for code enhancements or a feature idea. In the issue, you then do the following: @@ -102,9 +102,9 @@ feature idea. In the issue, you then do the following: - Add any references that could help during the development process. - Report bugs ~~~~~~~~~~~ + If you encounter a bug in the code, you open a new issue and select the template for creating a bug report. In the bug report, try to: @@ -114,9 +114,9 @@ for creating a bug report. In the bug report, try to: - Add any additional information that you consider useful for fixing the bug. - Fork a repository ----------------- + Forking a repository is like copying and pasting a project into your own GitHub profile. Notice that only ``public`` labeled repositories can be forked. You cannot fork a repository labeled as ``internal`` or ``private``. @@ -124,14 +124,15 @@ cannot fork a repository labeled as ``internal`` or ``private``. To fork a repository, click the ``Fork`` button at the top of the project's ``Code`` tabbed section. - Clone a repository ------------------ + Cloning a repository means downloading it to your local machine. While there are two ways of doing this (``HTTPS`` or ``SSH``), to force the usage of ``SSH``, only this method is explained. Clone using SSH ~~~~~~~~~~~~~~~ + Cloning using ``SSH`` requires :ref:`Enabling SSH`. After that, you can clone a repository by running: @@ -146,9 +147,9 @@ project with: git clone git@github.com:ansys/pymapdl.git - -Install in editable mode +Install 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 reflected in your Python environment. @@ -158,7 +159,7 @@ To install a Python library in editable mode: 1. Ensure that you :ref:`Create` and :ref:`Activate` a Python virtual environment, as explained in the :ref:`Virtual environments` section. -2. Update `pip` with: +2. Update ``pip`` with: .. code-block:: bash @@ -170,9 +171,9 @@ To install a Python library in editable mode: python -m pip install --editable . - Create a branch --------------- + It is likely that the default branch name is ``main`` or ``master``. This is the development branch for PyAnsys projects. For more information, see :ref:`Branch model`. @@ -187,6 +188,7 @@ You create a branch with: Branch naming conventions ~~~~~~~~~~~~~~~~~~~~~~~~~ + The following requirements for naming branches helps to streamline development. They help core developers know what kind of changes any given branch is introducing before looking at the code. @@ -204,9 +206,9 @@ changes any given branch is introducing before looking at the code. - ``testing/``: Improvements or changes to testing - ``release/``: Releases (see below) - Push a new branch ----------------- + Once you have implemented new changes and committed them, you push your branch, which uploads your changes to the repository. These changes are only visible in the branch that you just pushed. @@ -217,6 +219,7 @@ visible in the branch that you just pushed. Create a pull request --------------------- + Once you have tested your branch locally, create a pull request (PR) and target your merge to ``main``. This automatically runs CI testing and verifies that your changes work across all supported platforms. For procedural information, see `Creating a pull request @@ -238,6 +241,7 @@ or someone else with write permission must merge your PR and then delete your PR Use GitHub CLI -------------- + Because developers do not like leaving their terminals when working in projects, GitHub offers a `command-line interface (CLI) `_. diff --git a/doc/source/how-to/dns-configuration.rst b/doc/source/how-to/dns-configuration.rst index 00062d300..47fbfb1f0 100644 --- a/doc/source/how-to/dns-configuration.rst +++ b/doc/source/how-to/dns-configuration.rst @@ -73,7 +73,6 @@ Case scenario - **vulnerable** subdomain This CNAME **can** be used by external users for their repositories. For this reason, you must avoid creating CNAME requests that are not verified by the organization. - Preventing CNAME takeover ------------------------- @@ -93,7 +92,6 @@ Thus, it is important that you follow these guidelines: * Request deletion of the CNAME once it is no longer used to prevent others from hosting their sites on it. - .. Links diff --git a/doc/source/how-to/documenting.rst b/doc/source/how-to/documenting.rst index 897e8eb93..52b8af0a9 100644 --- a/doc/source/how-to/documenting.rst +++ b/doc/source/how-to/documenting.rst @@ -1,8 +1,9 @@ Documenting =========== + 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 +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 only specific to PyAnsys library documentation. @@ -18,12 +19,12 @@ code: Documentation sources --------------------- + .. raw:: html
- +
-
The generation of PyAnsys documentation uses `Sphinx `__ and an Ansys-branded theme @@ -36,6 +37,7 @@ assemble content in: Docstrings ~~~~~~~~~~ + Docstrings must be formatted so that Sphinx can parse them. Sphinx provides these extensions for docstring formatting: @@ -62,9 +64,10 @@ For more information, see :ref:`Documentation style`. RST files ~~~~~~~~~ + To provide general usage information in your documentation, use your favorite editor to create RST (ReStructured Text) files that you then place in :ref:`The \`\`doc/\`\` -directory` directory. The ``index.rst`` file in the ``doc/source`` directory +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 number of heading levels that the documentation is to display. Following this @@ -134,9 +137,10 @@ documentation structure, see the `Sphinx Getting Started Indicating RST titles +++++++++++++++++++++ + Within RST files, heading titles are to use sentence case per `capitalization guidelines `_ -in the *Google Developer Documentation Style Guide*. The line that follows +in the *Google developer documentation style guide*. The line that follows the heading title must have 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 generates a warning. @@ -160,6 +164,7 @@ you to understand the syntax and see how RST files are nested to create this gui Recommended sections ++++++++++++++++++++ + Although each project is different, documentation has the same goal: providing instructions and guidelines for users. Thus, you can find some common sections across the documentation for PyAnsys libraries. Try to include these top-level @@ -169,12 +174,12 @@ sections in your library documentation: - ``User guide`` describes how to use basic features of the library. - ``API reference`` documents API resources provided by the library. - ``Examples`` provides fully fledged examples for using the library. -- ``Contributing`` refers to the `PyAnsys Developer's Guide`_ +- ``Contributing`` refers to the `PyAnsys developer's guide`_ for overall guidance and provides library-specific contribution information. - Examples ~~~~~~~~ + Examples come in two formats: - Basic code snippets demonstrating the feature @@ -239,6 +244,7 @@ Using Python, here is a :ref:`General example` using sphinx gallery. Document Python code -------------------- + You can use `sphinx.ext.autodoc` to generate documentation from your Python code. When using this extension, you can include these directives in your :ref:`RST files`: @@ -250,9 +256,9 @@ For a full list of 'auto' directives, see `Include documentation from docstrings `_ in the Sphinx documentation. - Document classes ~~~~~~~~~~~~~~~~ + There are two main ways of using Sphinx to document a class: * Manually describe 'how' and 'why' you use a class in :ref:`RST files`. @@ -262,6 +268,7 @@ There are two main ways of using Sphinx to document a class: Manually generate documentation +++++++++++++++++++++++++++++++ + To describe 'why' and 'how' you use a class within :ref:`RST files`, use the ``code-block`` directive: @@ -295,6 +302,7 @@ To describe 'why' and 'how' you use a class within :ref:`RST files`, use the Automatically generate documentation ++++++++++++++++++++++++++++++++++++ + To automatically generate class descriptions from the numpydoc strings in your Python files, use either the ``autoclass`` or ``autosummary`` directive in your :ref:`RST files`. For information on docstrings and required docstring @@ -302,7 +310,6 @@ sections, see :ref:`Numpydoc docstrings`. For simple classes, use the ``autoclass`` directive: - .. tab-set:: .. tab-item:: Doc Source Code @@ -351,6 +358,7 @@ and each method and attribute in that class also has its own page. Document multiple classes +++++++++++++++++++++++++ + To document a set of small but highly cohesive classes, you can combine the two preceding approaches. To accomplish this, you include multiple ``autoclass`` directives in the same RST file with headings and text blocks as @@ -375,9 +383,9 @@ and classes are shared across multiple queries. Consequently, these classes are documented separately. - Build documentation ------------------- + `Sphinx `_ is used to build the documentation. You configure the entire build process in the ``conf.py`` file, located in the ``source/`` directory in :ref:`The \`\`doc/\`\` directory`. @@ -389,6 +397,7 @@ documentation output, such as ``HTML``, ``LaTeX`` or Build HTML documentation ~~~~~~~~~~~~~~~~~~~~~~~~ + You build HTML documentation with: .. tab-set:: @@ -416,6 +425,7 @@ You can display the HTML documentation with: Build PDF documentation ~~~~~~~~~~~~~~~~~~~~~~~ + To build PDF documentation, the following rules must be added to the ``Makefile`` and ``make.bat`` files: @@ -469,6 +479,7 @@ The resulting PDF and intermediate LaTeX files are created in the Enabling multi-version documentation ------------------------------------ + With the release of `ansys/actions@v4 `_ , projects can benefit from multi-version documentation. Projects taking advantage of this @@ -480,7 +491,6 @@ Follow these steps to enable multi-version documentation in your project: - Use ``ansys-sphinx-theme>=0.8`` for building the documentation in your project. - Include the following lines in :ref:`The \`\`conf.py\`\` file`: - .. code-block:: python import os @@ -498,8 +508,7 @@ Follow these steps to enable multi-version documentation in your project: }, ... } - - + .. admonition:: About the ``DCOUMENTATION_CNAME`` environment variable The ``DOCUMENTATION_CNAME`` environment variable is expected to be @@ -507,11 +516,9 @@ Follow these steps to enable multi-version documentation in your project: 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, see :ref:`Deploying documentation`. - With all the previous configuration, your project is ready to use multi-version documentation in an automated way. This means that every time you release a new version, it is added to the drop-down button in the upper right corner of @@ -531,9 +538,9 @@ released versions. If you require support for migrating to the multi-version documentation, email `pyansys.core@ansys.com `_. - Deploying documentation ----------------------- + PyAnsys libraries deploy their documentation online via `GitHub Actions`_ to `GitHub Pages`_. This documentation is hosted on the `gh-pages`_ branch of the repository of the project. Documentation deployment is done by uploading the @@ -579,9 +586,9 @@ in an automated way. cname: ${{ env.DOCUMENTATION_CNAME }} token: ${{ secrets.GITHUB_TOKEN }} - Deploying to another repository ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + If you are planning to deploy documentation to a repository other than the one for your project, make sure you create this new repository before deploying your documentation for the first time. @@ -642,7 +649,8 @@ workflow: Multi-version migration from ``ansys/actions@v3`` to ``ansys/actions@v4`` ------------------------------------------------------------------------------- +-------------------------------------------------------------------------- + Projects using the multi-version feature should upgrade to `ansys/actions@v4 `_ or higher to benefit from stable links. This is achieved by introducing a new layout that is @@ -660,9 +668,9 @@ To perform the migration, follow these steps: * Apply previous steps as fix patches in all the desired versions to be included in the multi-version documentation. - Access online documentation --------------------------- + Documentation for the latest stable release of a PyAnsys library is accessible from its repository. The canonical name for the documentation of the project is constructed using the following structure: @@ -699,6 +707,7 @@ GitHub pull request. For more information, see :ref:`Build documentation`. Using PyMeilisearch as search engine ------------------------------------ + PyMeilisearch is a Python client library that enables you to utilize MeiliSearch, an open-source search engine, to provide fast and relevant search capabilities for your application's data. @@ -731,7 +740,6 @@ To enable multi-version documentation in your project, follow these steps: In this code, replace with the desired name for your MeiliSearch index. The ``convert_version_to_pymeilisearch`` function is to convert your package's version into a format suitable for MeiliSearch indexing. - - Enable documentation index deployment for development and stable versions using GitHub Actions: .. code-block:: yaml diff --git a/doc/source/how-to/grpc-api-packages.rst b/doc/source/how-to/grpc-api-packages.rst index ae24478cf..e8444dc38 100644 --- a/doc/source/how-to/grpc-api-packages.rst +++ b/doc/source/how-to/grpc-api-packages.rst @@ -241,7 +241,6 @@ replaced by: TWINE_PASSWORD: ${{ secrets.PYANSYS_PYPI_PRIVATE_PAT }} TWINE_REPOSITORY_URL: https://pkgs.dev.azure.com/pyansys/_packaging/pyansys/pypi/upload - Consuming the API package within Python ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/source/how-to/images/guidelines_chart.png b/doc/source/how-to/images/guidelines_chart.png index 5b57653d9..ca7792946 100644 Binary files a/doc/source/how-to/images/guidelines_chart.png and b/doc/source/how-to/images/guidelines_chart.png differ diff --git a/doc/source/how-to/index.rst b/doc/source/how-to/index.rst index 910d17a0c..35b2a2559 100644 --- a/doc/source/how-to/index.rst +++ b/doc/source/how-to/index.rst @@ -1,5 +1,5 @@ How-to -###### +====== This section describes several guidelines and best practices for creating effective and efficient Python libraries to interface with Ansys products and diff --git a/doc/source/how-to/logging.rst b/doc/source/how-to/logging.rst index 930fb511d..c8b89551f 100644 --- a/doc/source/how-to/logging.rst +++ b/doc/source/how-to/logging.rst @@ -1,6 +1,7 @@ Logging ======= -This section provides guidelines for logging in PyAnsys libraries. These + +This page provides guidelines for logging in PyAnsys libraries. These guidelines are best practices discovered through implementing logging services and modules within PyAnsys libraries. Suggestions and improvements are welcomed. @@ -11,9 +12,9 @@ particular, see: - `Python Basic Logging Tutorial `_ - `Python Advanced Logging Tutorial `_ - Description and usage --------------------- + Logging helps to track events occurring in the app. A log record is created for each event. This record contains detailed information about the current app operation. Whenever information must be exposed, displayed, @@ -121,9 +122,9 @@ This method contains all modified content to send to the stream: self._std_out_handler.setFormatter(FORMATTER) self.global_logger.addHandler(self._std_out_handler) - Use %-formatting for strings ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Although using the f-string for formatting most strings is often recommended, when it comes to logging, using the former %-formatting is preferable. When %-formatting is used, the string is not evaluated at runtime. Instead, it @@ -134,10 +135,10 @@ errors occur, they are reported as logging errors and do not halt code. logger.info("Project %s has been opened.", project.GetName()) - App and service logging modules ---------------------------------------- -PyAnsys libraries use app and Service logging modules to extend +------------------------------- + +PyAnsys libraries use app and service logging modules to extend or expose features from an Ansys app, product, or service, which can be local or remote. @@ -159,8 +160,7 @@ of the global and instance loggers. :alt: Logging in PyMAPDL :figclass: align-center - -You can find the source for this example logger in the collapsible section below +You can find the source for this example logger in the following collapsible section and in the ``dev_guide`` repository at `pyansys_logging.py `_. @@ -168,7 +168,6 @@ and in the ``dev_guide`` repository at `pyansys_logging.py .. literalinclude:: code/pyansys_logging.py - Some unit tests demonstrating how to use the PyAnsys custom logger module implemented in the preceding code are shown in this collapsible section: @@ -176,7 +175,6 @@ in the preceding code are shown in this collapsible section: .. literalinclude:: code/test_pyansys_logging.py - Global logger ------------- @@ -200,7 +198,6 @@ another logger, you can rename it with: from ansys.product.service import LOG as logger - The default logging level of the global logger is ``ERROR`` (``logging.ERROR``). You can change the output to a different error level with: @@ -210,7 +207,6 @@ You can change the output to a different error level with: LOG.file_handler.setLevel("DEBUG") # if present LOG.stdout_handler.setLevel("DEBUG") # if present - Alternatively, you can use this approach to ensure that all handlers are set to the desired log level: @@ -218,7 +214,6 @@ handlers are set to the desired log level: LOG.setLevel("DEBUG") - By default, the global logger does not log to a file. However, you can enable logging to both a file and the standard output by adding a file handler: @@ -243,13 +238,13 @@ To log using the global logger, simply call the desired method as a normal logge >>> LOG = Logger(level=logging.DEBUG, to_file=False, to_stdout=True) >>> LOG.debug("This is LOG debug message.") - | Level | Instance | Module | Function | Message - |----------|-----------------|------------------|----------------------|-------------------------------------------------------- - | DEBUG | | __init__ | | This is LOG debug message. - + | Level | Instance | Module | Function | Message + |----------|------------|--------------|-------------|--------------------------- + | DEBUG | | __init__ | | This is LOG debug message. Instance logger --------------- + An instance logger is created every time that the class ``_MapdlCore`` is instantiated. Using this instance logger is recommended when using the ``pool`` library or when using multiple instances of ``Mapdl``. The main feature of the instance @@ -278,14 +273,14 @@ Here is an example of how to use an instance logger: >>> mapdl = launch_mapdl() >>> mapdl._log.info("This is an useful message") - | Level | Instance | Module | Function | Message - |----------|-----------------|------------------|----------------------|-------------------------------------------------------- - | INFO | 127.0.0.1:50052 | test | | This is an useful message - + | Level | Instance | Module | Function | Message + |----------|-----------------|----------|-------------|-------------------------- + | INFO | 127.0.0.1:50052 | test | | This is an useful message Ansys product loggers --------------------- + An Ansys product, due to its architecture, can have several loggers. The ``logging`` library features support working with a finite number of loggers. The factory function ``logging.getLogger()`` helps to access each logger by its name. In @@ -303,14 +298,14 @@ in the standard logger and all the upcoming improvements. Custom log handlers ------------------- + You might need to catch Ansys product messages and redirect them to another logger. For example, Ansys Electronics Desktop (AEDT) has its own internal -logger called the *message manager*, which has three main destinations: +logger called the **message manager**, which has three main destinations: -- *Global*, which is for the entire project manager -- *Project*, which is related to the project -- *Design*, which is related to the design, making it the most specific - destination of the three loggers +- **Global**, which is for the entire project manager +- **Project**, which is related to the project +- **Design**, which is related to the design, making it the most specific destination of the three loggers The message manager does not use the standard Python logging module, which can be a problem when exporting messages and data from it to a common tool. @@ -341,7 +336,6 @@ logging service with the AEDT message manager. def emit(self, record): pass - The purpose of this class is to send log messages in the AEDT logging stream. One of the mandatory actions is to overwrite the ``emit`` function. This method operates as a proxy, dispatching all log messages to the message manager. diff --git a/doc/source/how-to/packaging.rst b/doc/source/how-to/packaging.rst index 6d893dc86..b2863e550 100644 --- a/doc/source/how-to/packaging.rst +++ b/doc/source/how-to/packaging.rst @@ -1,18 +1,18 @@ Packaging ========= + Packaging is the process for distributing software to guarantee that final users can use it. By packaging Python libraries, it is possible to declare which source code or binary files need to be distributed, project metadata and third party dependencies. - The fundamentals of Python packaging together with the packaging style guidelines that apply to PyAnsys projects are collected in the :ref:`Packaging style` section. - Specifying dependencies ----------------------- + It is common to take advantage of third party libraries to simplify source code. The formal way of doing so is by specifying these third party libraries as dependencies. There are two types of dependencies: :ref:`Required @@ -20,14 +20,14 @@ dependencies` and :ref:`Optional dependencies`. Required dependencies ~~~~~~~~~~~~~~~~~~~~~ -Required dependencies are third party libraries that a software requires to + +Required dependencies are third-party libraries that a software requires to properly function. If these dependencies are not installed or present, the software does not work as expected. -Required dependencies need to be declared in :ref:`the \`\`setup.py\`\` file` or -in :ref:`the \`\`pyproject.toml\`\` file`, according to the selected :ref:`Build -system`: - +Required dependencies must be declared in :ref:`The \`\`setup.py\`\` file` or +in :ref:`The \`\`pyproject.toml\`\` file`, according to the +selected :ref:`Build system`: .. tab-set:: @@ -67,9 +67,9 @@ system`: ], ) - Optional dependencies ~~~~~~~~~~~~~~~~~~~~~ + Optional dependencies are third-party libraries without which a software is not able to execute particular features. This makes it convenient to declare dependencies for ancillary functions such as *plotting*, *tests*, or *docs*. You @@ -100,9 +100,9 @@ reasons, including: If you choose to implement optional packages for your PyAnsys library, some helpful best practices follow. - Implementing optional packages in the build system ++++++++++++++++++++++++++++++++++++++++++++++++++ + Here's how to implement and use optional requirements for the three most popular build systems: @@ -186,9 +186,9 @@ popular build systems: pip install package-name[qt] - Implementing optional libraries in features +++++++++++++++++++++++++++++++++++++++++++ + One of the best ways to implement an optional dependency is to execute a *lazy import* at runtime for the feature in question. For example, if your library has an optional dependency on ``matplotlib``, you can implement it with: diff --git a/doc/source/how-to/releasing.rst b/doc/source/how-to/releasing.rst index 88418b7b7..0eaf21ace 100644 --- a/doc/source/how-to/releasing.rst +++ b/doc/source/how-to/releasing.rst @@ -1,5 +1,6 @@ Releasing and publishing ======================== + Releasing a new version is a critical procedure. It should be automated as much as possible to avoid human error. @@ -11,9 +12,9 @@ to create a successful release. A project needs to be authorized to be released into public by following the process explained in the :ref:`Project approval and public release` section. - Semantic versioning ------------------- + PyAnsys library releases are managed through both automated and manual review processes. @@ -48,10 +49,10 @@ to be much more stable. Branch model ------------ + The branching model for a PyAnsys project enables rapid development of features without sacrificing stability. The model closely follows the -`Trunk Based Development `_ approach: - +`trunk-based development `_ approach: - The ``main`` branch is the primary development branch. All features, patches, and other branches should be merged here. While all PRs @@ -62,7 +63,6 @@ features without sacrificing stability. The model closely follows the .. include:: diag/main_branch.rst - - When a minor release candidate is ready, a new ``release`` branch is created from ``main`` with the next incremented minor version (for example, ``release/0.2``). This ``release`` branch is thoroughly @@ -70,7 +70,6 @@ features without sacrificing stability. The model closely follows the in this case). Older release branches should not be deleted so that they can be patched as needed. - - There is one or more ``release/`` branches based on minor releases (for example, ``release/0.2``) that contain a stable version of the code base that is also reflected on PyPI. Hotfixes from ``fix/`` branches should be @@ -82,22 +81,21 @@ features without sacrificing stability. The model closely follows the .. include:: diag/release_branch.rst - Releasing new versions ---------------------- + Releasing is the process of creating a version of a software that developers consider useful for customers or other developers. Releases are usually labeled with *tags*. These tags are used to quickly identify a release in the version control system. -.. card:: |uncheck| Release checklist - - * Your main or release branch is up to date. - * All code and documentation style checks are passing successfully. - * All tests are passing successfully. - * All documentation builds successfully. - * The project builds successfully. +.. card:: Release checklist + | |uncheck| Your main or release branch is up to date. + | |uncheck| All code and documentation style checks are passing successfully. + | |uncheck| All tests are passing successfully. + | |uncheck| All documentation builds successfully. + | |uncheck| The project builds successfully. .. dropdown:: Releasing major and minor versions @@ -192,9 +190,9 @@ control system. git push -u origin release/X.Y git push origin vX.Y.Z - Publishing artifacts -------------------- + When a new version is released, some artifacts are provided with it. In Python, these :ref:`Artifacts` are typically the ``Wheel`` and ``Source`` files. Documentation in the form of PDF and HTML files are also considered artifacts. @@ -204,8 +202,7 @@ Documentation in the form of PDF and HTML files are also considered artifacts. Do not distribute artifacts without approval. A project needs to be authorized to be released into public by following the - process explained in the :ref:`Project approval and public release` section. - + process explained in :ref:`Project approval and public release`. There are three possible places where artifacts can be published: @@ -239,6 +236,7 @@ There are three possible places where artifacts can be published: Private PyPI ~~~~~~~~~~~~ + It is sometimes necessary to host and pull packages that are not ready to be hosted on the public `PyPI`_. For example, if a PyAnsys library requires auto-generated gRPC interface files from a feature or service that is still @@ -278,7 +276,6 @@ Here's a cross-platform one liner for uploading using ``twine```: Replace ```` with the private PyPI token respectively. - .. dropdown:: Using GitHub actions The following code allows you to publish any Python :ref:`Artifacts` contained in @@ -348,12 +345,11 @@ Replace ```` with the private PyPI token respectively. python -m twine upload dist/* - - .. _public-pypi: Public PyPI ~~~~~~~~~~~ + Publishing :ref:`Artifacts` to `PyPI`_ is the way of distributing :ref:`Python libraries`. Publishing to `PyPI`_ requires a username and a password: @@ -406,6 +402,7 @@ Replace ```` and ```` with the package name and th GitHub ~~~~~~ + Publishing :ref:`Artifacts` to GitHub is also possible. These are available in the ``https://github.com/ansys/project-name/releases`` section. The visibility of these artifacts follows the one in the repository. Visibility can @@ -431,13 +428,12 @@ the :ref:`Project approval and public release` section. with: library-name: "ansys--" - Downloading artifacts --------------------- + Artifacts can be downloaded from all previous sources: Ansys private PyPI, public PyPI and GitHub. - .. dropdown:: Downloading artifacts from the Ansys private PyPI Request the value of the ``PYANSYS_PYPI_PRIVATE_PAT`` token by sending an @@ -522,7 +518,6 @@ public PyPI and GitHub. python -m pip install path/to/package/wheel.whl - .. _PyPI: https://pypi.org/ .. _PyAnsys PyPI: https://pkgs.dev.azure.com/pyansys/_packaging/pyansys/pypi .. _PyAnsys: https://github.com/ansys diff --git a/doc/source/how-to/repository-protection.rst b/doc/source/how-to/repository-protection.rst index 03e37221b..d466708b5 100644 --- a/doc/source/how-to/repository-protection.rst +++ b/doc/source/how-to/repository-protection.rst @@ -76,7 +76,6 @@ The PyAnsys team recommends to set the following rules for the ``main`` branch: this forces assignees to actually go through all comments. It is just a safety measure so that at least any comment left by reviewers is read (and hopefully applied). - Tag protection -------------- diff --git a/doc/source/how-to/setting-up.rst b/doc/source/how-to/setting-up.rst index 4717fd779..59e971cd7 100644 --- a/doc/source/how-to/setting-up.rst +++ b/doc/source/how-to/setting-up.rst @@ -1,5 +1,6 @@ Setting up your development environment ======================================= + Before you can contribute to any PyAnsys project, you must set up your developer environment. @@ -8,7 +9,10 @@ Python .. raw:: html
- +
All PyAnsys projects require a Python interpreter for interacting @@ -17,6 +21,7 @@ interpreter is installed on your local machine. Installation ~~~~~~~~~~~~ + There are several ways to install a Python package on your local machine: - Use an official installer from the `official Python download section `_. @@ -50,7 +55,7 @@ There are several ways to install a Python package on your local machine: .. note:: It is likely that your macOS distribution already comes with some - version of Python installed. For more information, see :ref:`Verification`. + version of Python installed. For more information, see :ref:`Verify Python version`. .. tab-item:: Linux/UNIX @@ -64,46 +69,21 @@ There are several ways to install a Python package on your local machine: .. note:: It is likely that your Linux/UNIX distribution already comes with some - version of Python installed. For more information, see :ref:`Verification`. - - -Verification -~~~~~~~~~~~~ -Once your Python installation is complete, verify it with: - -.. tab-set:: - - .. tab-item:: Windows - - .. tab-set:: - - .. tab-item:: CMD + version of Python installed. For more information, see :ref:`Verify Python version`. - .. code-block:: text - - py --version - - .. tab-item:: PowerShell - .. code-block:: text - - py --version - - .. tab-item:: macOS - - .. code-block:: text - - python --version - - .. tab-item:: Linux/UNIX +Verify Python version +~~~~~~~~~~~~~~~~~~~~~ - .. code-block:: text +Once your Python installation is complete, verify it with: - python --version +.. code-block:: text + python --version Virtual environments -------------------- + When working in multiple Python projects, it is likely each of these projects has its own requirements. Sometimes, requirements across projects can be incompatible. Virtual environments were devised to isolate Python environments, which guarantees @@ -115,6 +95,7 @@ the venv module `_. Check ~~~~~ + Before creating a new virtual environment, you must run this code to see if you are already working with one: @@ -128,7 +109,7 @@ working with one: .. code-block:: text - where.exe python + where python .. tab-item:: PowerShell @@ -136,13 +117,7 @@ working with one: where.exe python - .. tab-item:: macOS - - .. code-block:: text - - which python - - .. tab-item:: Linux/UNIX + .. tab-item:: macOS/Linux/UNIX .. code-block:: text @@ -156,42 +131,18 @@ information on deactivating your virtual environment. Create ~~~~~~ -Usually, virtual environments are named ``venv`` or ``.venv``. -You can create a virtual environment named `` with: - -.. tab-set:: - - .. tab-item:: Windows - - .. tab-set:: - - .. tab-item:: CMD - .. code-block:: text - - py -m venv - - .. tab-item:: PowerShell - - .. code-block:: text - - py -m venv - - .. tab-item:: macOS - - .. code-block:: text +Usually, virtual environments are named ``venv`` or ``.venv``. +You can create a virtual environment named ```` with: - python -m venv +.. code-block:: text - .. tab-item:: Linux/UNIX - - .. code-block:: text - - python -m venv + python -m venv Activate ~~~~~~~~ -You would activate the preceding virtual environment with: + +You would activate the preceding virtual environment with the command for your OS: .. tab-set:: @@ -211,60 +162,32 @@ You would activate the preceding virtual environment with: \Scripts\Activate.ps1 - .. tab-item:: macOS + .. tab-item:: macOS/Linux/UNIX .. code-block:: text source /bin/activate - .. tab-item:: Linux/UNIX - - .. code-block:: text - - source /bin/activate Deactivate ~~~~~~~~~~ -You would deactivate a virtual environment with: - -.. tab-set:: - - .. tab-item:: Windows - - .. tab-set:: - - .. tab-item:: CMD - - .. code-block:: text - - deactivate - .. tab-item:: PowerShell - - .. code-block:: text +You could deactivate a virtual environment with the command for your OS: - deactivate - - .. tab-item:: macOS - - .. code-block:: text - - deactivate - - .. tab-item:: Linux/UNIX - - .. code-block:: text - - deactivate +.. code-block:: text + deactivate Git --- + .. raw:: html
- -

+
`Git `_ is an open source version control system (VCS). It @@ -298,54 +221,30 @@ Installation 1. Check the `latest stable Git version for Linux/UNIX `_. 2. Run the installation command for your package manager. +Verify Git version +~~~~~~~~~~~~~~~~~~ -Verification -~~~~~~~~~~~~ Once your installation process is complete, verify your Git installation with: -.. tab-set:: - - .. tab-item:: Windows - - .. tab-set:: - - .. tab-item:: CMD - - .. code-block:: text +.. code-block:: text - git --version - - .. tab-item:: PowerShell - - .. code-block:: text - - git --version - - .. tab-item:: macOS - - .. code-block:: text - - git --version - - .. tab-item:: Linux/UNIX - - .. code-block:: text - - git --version + git --version Usage ~~~~~ -If you are not familiar with Git, see the `Git Reference Manual `_. -for comprehensive information on how to use it. -If you are not familiar with Git and the Git workflows in terms of development, it is -recommended that you follow this tutorial on `Learning Git branching `_. +If you're new to Git, see the `Git Reference Manual `_ +for comprehensive usage information. -Also, if you are not that familiar with GitHub, feel free to go through the -`GitHub Training Manual `_. +For an understanding of Git workflows and branching strategies, +see the `Learning Git branching `_ tutorial. + +If you're unfamiliar with GitHub, see the +`GitHub Training Manual `_ for guidance. Configuration ~~~~~~~~~~~~~ + It is very important to properly configure Git so that every modification that you make to the code points to you. There are two types of configuration: :ref:`Global` and :ref:`Local`. It is also possible to combine both to have @@ -386,6 +285,7 @@ Some examples follow. Local +++++ + There might be a time when you want to declare a specific configuration to use only in a given project. To override the :ref:`Global` configuration, you can declare a local configuration. @@ -400,6 +300,7 @@ the ``.git/config`` file. Dynamic +++++++ + It is possible to configure :ref:`Git` such that it selects between multiple configuration profiles according to whether your project is located in your system. This allows you to define common configurations for working under ``PyAnsys``, @@ -429,7 +330,6 @@ Each one of these files can look like this: [includeIf "gitdir:path/to/your/personal/folder/of/projects"] path = path/to/.gitconfig-personal - .. tab-item:: .gitconfig-ansys .. code-block:: text @@ -440,7 +340,6 @@ Each one of these files can look like this: email = signingkey = - .. tab-item:: .gitconfig-personal .. code-block:: text @@ -454,6 +353,7 @@ Each one of these files can look like this: Signing commits ~~~~~~~~~~~~~~~ + To verify which code changes were made by you, signing the commit is required. To sign a commit, you must generate a ``GPG`` key, associate it with ``GitHub``, and specify it in your ``Git`` :ref:`Configuration`. @@ -464,9 +364,10 @@ Commit Signatures - Windows terminal ---------------- + .. image:: images/windows_terminal.png :align: center :alt: The Windows Terminal with different active shell sessions. @@ -581,5 +486,6 @@ is to collect and manage all shell sessions in a single program. Installation ~~~~~~~~~~~~ + You can install ``Windows Terminal`` directly from the `official Microsoft Store package `_. diff --git a/doc/source/how-to/supporting-python-versions.rst b/doc/source/how-to/supporting-python-versions.rst index 5c85e44b3..498803960 100644 --- a/doc/source/how-to/supporting-python-versions.rst +++ b/doc/source/how-to/supporting-python-versions.rst @@ -1,5 +1,6 @@ Supporting Python versions ========================== + Like other programming languages, Python evolves with time. New features get added to the language, and others get deprecated. For more information, see `Status of Python branches @@ -8,22 +9,19 @@ more information, see `Status of Python branches +---------+------------+-------------+-----------------------+--------+ | Version | PEP | Released | Security Support Ends | Status | +---------+------------+-------------+-----------------------+--------+ -| 3.11 | `PEP 664`_ | 03 Oct 2022 | 03 Oct 2027 | Dev | -+---------+------------+-------------+-----------------------+--------+ -| 3.10 | `PEP 619`_ | 04 Oct 2021 | 04 Oct 2026 | Dev | +| 3.12 | `PEP 693`_ | 02 Oct 2023 | Oct 2028 | Stable | +---------+------------+-------------+-----------------------+--------+ -| 3.9 | `PEP 596`_ | 05 Oct 2020 | 05 Oct 2025 | Stable | +| 3.11 | `PEP 664`_ | 03 Oct 2022 | Oct 2027 | Stable | +---------+------------+-------------+-----------------------+--------+ -| 3.8 | `PEP 569`_ | 14 Oct 2019 | 14 Oct 2024 | Stable | +| 3.10 | `PEP 619`_ | 04 Oct 2021 | Oct 2026 | Stable | +---------+------------+-------------+-----------------------+--------+ -| 3.7 | `PEP 537`_ | 27 Jun 2018 | 27 Jun 2023 | 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/ .. _PEP 619: https://peps.python.org/pep-0619/ .. _PEP 596: https://peps.python.org/pep-0596/ -.. _PEP 569: https://peps.python.org/pep-0569/ -.. _PEP 537: https://peps.python.org/pep-0537/ .. admonition:: Consider supporting stable Python versions. @@ -46,20 +44,20 @@ can enforce a minimum-required Python version within ``setup.py`` with: [...] - setup(name="my_package_name", python_requires=">3.6", [...]) + setup(name="my_package_name", python_requires=">3.9", [...]) This helps ``pip`` to know which versions of your library support which versions of Python. You can also impose an upper limit if you're sure you don't support certain versions of Python. For example, if you only -support Python 3.6 through 3.9, your command would look like this: ``python_requires='>=3.6, <3.10'``. - +support Python 3.9 through 3.12, your command would look like this: ``python_requires='>=3.9, <3.12'``. Verifying support ----------------- + The best way to validate whether a Python library supports a version of Python is by :ref:`Using continuous integration`. An example GitHub -workflow testing Python 3.7 through Python 3.10 on Windows and Linux would +workflow testing Python 3.9 through Python 3.12 on Windows and Linux would start with: .. code-block:: yaml @@ -73,7 +71,7 @@ start with: strategy: matrix: os: [windows-latest, ubuntu-latest] - python-version: ['3.7', '3.8', '3.9', '3.10'] + python-version: ['3.9', '3.10', '3.11', '3.12'] steps: - name: "Run tests using pytest" run: ansys/actions/test-pytest@v4 diff --git a/doc/source/how-to/testing.rst b/doc/source/how-to/testing.rst index f4bec88e7..e032540a4 100644 --- a/doc/source/how-to/testing.rst +++ b/doc/source/how-to/testing.rst @@ -1,5 +1,6 @@ Testing ======= + Unit testing and integration testing are critical for the successful continuous integration and delivery of any program or libraries belonging to the PyAnsys project. @@ -20,7 +21,7 @@ Test framework .. raw:: html
- +
For consistency, PyAnsys tools and libraries should use either the `unittest @@ -30,9 +31,9 @@ recommended unless any constraint in your project prevents you from using it. As described in :ref:`Required files`, unit tests should be placed in :ref:`The \`\`tests/\`\` directory` in the library's root directory. - Add testing dependencies ~~~~~~~~~~~~~~~~~~~~~~~~ + Requirements for testing dependencies should be included either in :ref:`The \`\`setup.py\`\` file`, :ref:`The \`\`pyproject.toml\`\` file` or in a ``requirements_tests.txt`` file. Only ``pytest`` and ``pytest-cov`` @@ -78,7 +79,6 @@ in `The Python Standard Library `_. pytest pytest-cov - These dependencies can be installed using ``pip``: .. tab-set:: @@ -98,6 +98,7 @@ These dependencies can be installed using ``pip``: Organize test files ~~~~~~~~~~~~~~~~~~~ + You must collect test files in :ref:`The \`\`tests/\`\` directory`. To guarantee that tests are run against the library source code, follow a ``src/`` layout as explained in :ref:`The \`\`src/\`\` directory` rather than @@ -109,9 +110,9 @@ This helps you to: - Catch errors caused by files that might be missed by the installer, including any C extensions or additional internal packages. - Run tests --------- + Once you have installed ``pytest``, you can execute the test suite with: .. code-block:: text @@ -120,6 +121,7 @@ Once you have installed ``pytest``, you can execute the test suite with: Filter tests ~~~~~~~~~~~~ + To run a subset of all available tests, you can taking advantage of the ``keywords`` and ``markers`` flags: @@ -136,12 +138,12 @@ of the ``keywords`` and ``markers`` flags: pytest -m slow - For more information about filtering tests, see `Working with Custom Markers `_ . Testing methodology ------------------- + You should consider three levels of testing for your PyAnsys library: unit, integration, and functional. @@ -260,14 +262,15 @@ file would be: This assumes that you do not have a ``serialize_chunks`` function in your library. If you did, you could exclude it from ``test_parse_chunks.py``. - Integration testing ~~~~~~~~~~~~~~~~~~~ + This section explains :ref:`Wrapped service methods` and how to :ref:`Test using remote method invocation`. Wrapped service methods +++++++++++++++++++++++ + Any PyAnsys library that provides features by wrapping a gRPC interface should include tests of the gRPC methods exposed by the PROTO files and wrapped by the Python library. They would not be expected to test the features of @@ -277,7 +280,6 @@ Python function. If the Python library wraps this gRPC method with a ``get_node`` method, your test would be implemented within ``tests/test_nodes.py``: - .. tab-set::: .. tab-item:: gRPC Code @@ -355,9 +357,9 @@ The goal of the unit test should be to test the API rather than the product or service. In the case of ``GetNode``, this method should have already been tested when designing and developing the service. - Test using remote method invocation +++++++++++++++++++++++++++++++++++ + For a Remote Method Invocation (RMI)-like method, it is only necessary to test the method with a basic case and potentially with any edge cases. A RMI-like API might send and receive strings that are executed on the @@ -401,9 +403,9 @@ received, executed, and sent back to the client. It does not validate all commands. Running such a test is necessary only if there are edge cases, which include characters that cannot be streamed or use long-running commands. - Functional testing ~~~~~~~~~~~~~~~~~~ + Functional testing should test the Python library using scripts or examples that are expected to be executed by the user. Unlike unit or integration testing, functional tests are testing the library as a whole by calling @@ -417,10 +419,9 @@ and integration testing is complete. Ideally, you should run them outside the .. _sphinx-gallery: https://sphinx-gallery.github.io/ - - Test code coverage ------------------ + Because Python is an interpreted language, syntax errors can only be caught during the almost trivial compile times. Thus, developers of Python libraries should aim to have high coverage for their libraries. Coverage is defined as parts @@ -428,9 +429,9 @@ of the executable and usable source that are tested by unit tests. You can use the `pytest-cov `_ library to view the coverage for your library. - Configure code coverage ~~~~~~~~~~~~~~~~~~~~~~~ + If you do not configure code coverage properly, the resulting report does not show the real scope covered by the test suite. @@ -445,7 +446,6 @@ This command tells ``pytest-cov`` to look for source code in the ``src/ansys/`` directory and generate a terminal report for all tests located in :ref:`The \`\`tests/\`\` directory`. - While 100% coverage is ideal, the law of diminishing returns applies to the coverage of a Python library. Consequently, achieving 80-90% coverage is often sufficient. For parts of your library that are difficult or impossible @@ -471,9 +471,10 @@ wrong data type or value can be reasonably tested. Enforce code coverage ~~~~~~~~~~~~~~~~~~~~~ + One way of enforcing unit test coverage with a project on GitHub is to use ``codecov.io`` to enforce minimum patch (and optionally project) coverage. Because -this app is already available to the `PyAnsys Organization +this app is already available to the `Ansys Organization `_, you can simply add a ``codecov.yml`` file to the root directory of your repository. This example file provides a sample configuration: @@ -505,9 +506,9 @@ directory of your repository. This example file provides a sample configuration: Using a ``codecov.yml`` file requires that each PR has a patch coverage of 90%, meaning that 90% of any source added to the repository (unless ignored) must be covered by unit tests. - Test using GitHub Actions ------------------------- + Effective CI/CD assumes that unit testing is developed during feature development or bug fixes. However, given the limited scope of the local development environment, it is often not possible to enforce testing on diff --git a/doc/source/index.rst b/doc/source/index.rst index 7cc35d525..d3d3c438b 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -3,7 +3,6 @@ .. include:: ../../README.rst - .. card:: Getting started .. grid:: 2 @@ -60,8 +59,6 @@ Best practices for writing documentation. - - .. toctree:: :hidden: :maxdepth: 3 diff --git a/doc/source/packaging/build-systems.rst b/doc/source/packaging/build-systems.rst index b2c43ebde..d5ae2dc64 100644 --- a/doc/source/packaging/build-systems.rst +++ b/doc/source/packaging/build-systems.rst @@ -1,14 +1,12 @@ .. _ref_build_system: -############ Build system -############ +============ The build system is a fundamental tool for packaging Python libraries. It generates distribution files that can be shared with users and developers. - Artifacts ========= @@ -27,7 +25,6 @@ PyAnsys project. `MANIFEST.in`_ is required at the root of the project to specify additional files. - 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 @@ -35,7 +32,6 @@ project directory and generate the artifacts, as :numref:`build system diag` sho .. include:: diag/build_system_diag.rst - PEP 517 and PEP 518 =================== @@ -52,7 +48,6 @@ introduced the following problems: These problems led to the acceptance of `PEP 517`_ and `PEP 518`_. - PEP 517 ------- @@ -68,7 +63,6 @@ most popular backends: `PEP 517` introduced the ``build-backend`` key inside the ``[build-system]`` table in the ``pyproject.toml``. - PEP 518 ------- @@ -92,7 +86,6 @@ The combination of `PEP 517`_ and `PEP 518`_ leads to the following syntax in a requires = ["flit"] # Defined by PEP 518 build-backend = "flit_core.api" # Defined by PEP 517 - Build backend tools =================== @@ -118,7 +111,6 @@ build backend system. All of these `setuptools metadata fields`_ are valid and must be specified either in the ``setup.py`` or ``setup.cfg`` file. - Flit ---- @@ -135,7 +127,6 @@ The ``[project]`` section specifies the project's metadata and required dependencies. For more information, see `flit pyproject.toml guidelines`_. - Poetry ------ @@ -159,7 +150,6 @@ Using `poetry`_ is popular because it: The ``[tool.poetry]`` section contains metadata and defines project dependencies. For more information, see `poetry pyproject.toml documentation`_. - .. _MANIFEST.in: https://packaging.python.org/en/latest/guides/using-manifest-in/ .. _PyPI: https://pypi.org/ .. _pip: diff --git a/doc/source/packaging/index.rst b/doc/source/packaging/index.rst index b30357338..10032d46f 100644 --- a/doc/source/packaging/index.rst +++ b/doc/source/packaging/index.rst @@ -1,6 +1,6 @@ -############### + Packaging style -############### +=============== A PyAnsys library eliminates the need to share snippets of code that perform actions. Users can instead create workflows consisting of @@ -35,7 +35,6 @@ from scratch. Therefore, the best practice is to create a Python layer that maps the raw API into a carefully designed, object-oriented data model and API. - .. toctree:: :hidden: :maxdepth: 3 diff --git a/doc/source/packaging/structure.rst b/doc/source/packaging/structure.rst index 2b4d6cdf8..fa2168c87 100644 --- a/doc/source/packaging/structure.rst +++ b/doc/source/packaging/structure.rst @@ -1,15 +1,13 @@ .. _ref_project_structure: -################# Project structure -################# +================= Most of the projects in the PyAnsys ecosystem ship in the form of a Python library with other additional files. All these files form what it is called a *project*. A project can be uploaded to a repository to better track the changes applied to it. - Naming convention ================= @@ -44,7 +42,6 @@ Using long Python library names provides two primary advantages: - `Namespace packages`_ can be used to designate official Ansys packages. - Consistent branding and style can be applied to PyAnsys libraries. - gRPC interface package ---------------------- Lower-level gRPC interface packages like `ansys-api-mapdl`_ should always be @@ -59,7 +56,6 @@ This structure leads to the following namespace within ``*.proto`` files: package ansys.api..v0; - Python libraries ================ @@ -73,7 +69,6 @@ is compliant with the `Python Packaging Authority`_ and PyAnsys recommendations. Packaging User Guide`_, maintained by the `Python Packaging Authority`_ (PyPA). PyAnsys guidelines are built on top of PyPA guidelines. - Scripts, modules, subpackages, and packages -------------------------------------------- @@ -85,7 +80,6 @@ the difference between Python scripts, modules, sub-packages, and packages. * ``Sub-package``: Any directory containing various Python modules * ``Package``: Any directory containing Python modules and sub-packages - Differences between a Python package and library ------------------------------------------------ @@ -96,7 +90,6 @@ sub-packages, while a Python Library is a collection of Python packages. Figure .. include:: diag/python_library_diag.rst - Required files ============== @@ -114,7 +107,6 @@ Descriptions follow for some of the directories in the structure: - ``setup.py`` or ``pyproject.toml`` is the project file. - The ``doc/`` directory ---------------------- @@ -135,7 +127,6 @@ Projects in the PyAnsys ecosystem take advantage of `Sphinx`_, a tool used for building documentation for Python-based projects. As shown in :numref:`doc structure diag`, `Sphinx`_ requires a ``doc/`` directory with a specific structure: - .. include:: diag/doc_structure_diag.rst - ``_build/`` contains the rendered documentation in various formats, such as HTML @@ -159,7 +150,6 @@ The ``source/`` directory must contain at least these files: If you would like to include images or documents, add them in the ``_static/`` directory. - The ``src/`` directory ---------------------- @@ -183,7 +173,6 @@ shown in the diagram :numref:`src structure diag`: .. include:: diag/src_structure_diag.rst - The ``tests/`` directory ------------------------ @@ -200,10 +189,9 @@ Notice the use of ``tests_*/`` when creating new directories inside the This is the preferred way of naming directories and files inside the ``tests/`` directory. - - The ``AUTHORS`` file -------------------- + An ``AUTHORS`` file is used to specify the authorship of the repository. Its format has been defined by the Ansys Legal department. External contributors may be added on demand to this file. Make sure to adapt the project name on @@ -211,7 +199,6 @@ your specific repository's ``AUTHORS`` file. .. include:: code/authors_code.rst - The ``CHANGELOG.md`` file ------------------------- @@ -222,7 +209,6 @@ enhancements to the project. .. literalinclude:: code/changelog_file.md :language: markdown - The ``CODE_OF_CONDUCT.md`` file ------------------------------- @@ -233,7 +219,6 @@ Covenant Code of Conduct``, which is very popular across open source projects. .. literalinclude:: code/code_of_conduct_file.md :language: markdown - The ``CONTRIBUTING.md`` file ---------------------------- This file is used as a quick entry-point for developers wiling to contribute to @@ -244,12 +229,11 @@ the project. It usually provides references to: - Additional ways of contributing to the source code. Ideally, the ``CONTRIBUTING.md`` file for a PyAnsys project should be pointing -towards the `PyAnsys Developer's Guide `_. +towards the `PyAnsys developer's guide `_. .. literalinclude:: code/contributing_file.md :language: markdown - The ``CONTRIBUTORS.md`` file ---------------------------- The ``CONTRIBUTORS.md`` file is used to list the contributors to the repository. Its @@ -260,7 +244,6 @@ a link to your GitHub username. .. literalinclude:: code/contributors_file.md :language: markdown - The ``LICENSE`` file -------------------- @@ -276,7 +259,6 @@ this license is provided below: it is free or open source. If you need to use unlicensed software, contact its development team so they can provide you with the correct license. - The ``README.rst`` file ----------------------- @@ -299,7 +281,6 @@ The ``README.rst`` file should at the minimum contain these elements: The ``README.rst`` file is also reused within the project file metadata. It is usually included in the ``long-description`` field. - The ``pyproject.toml`` file --------------------------- @@ -312,7 +293,6 @@ for some of the most popular build-system backend tools in the Python ecosystem: .. include:: code/pyproject_code.rst - The ``setup.py`` file --------------------- @@ -327,7 +307,6 @@ process but can also introduce security issues. The ``setup.py`` is only compatible with `setuptools`_. Consider using a ``pyproject.toml`` file instead. - While a ``setup.cfg`` file can be used to specify the metadata and packages, the ``setup.py`` file must also be present. For more information, see: @@ -337,10 +316,8 @@ file must also be present. For more information, see: As a minimum configuration for a PyAnsys project, the following ``setup.py`` template can be used: - .. include:: code/setup_file_code.rst - .. REFERENCES & LINKS .. _MIT License: https://opensource.org/licenses/MIT diff --git a/doc/source/packaging/templates.rst b/doc/source/packaging/templates.rst index 3dea9bce9..172629f89 100644 --- a/doc/source/packaging/templates.rst +++ b/doc/source/packaging/templates.rst @@ -1,8 +1,7 @@ .. _templates: -######### Templates -######### +========= Starting a new project from scratch is a tedious task. To simplify the starting process and make project generation more dynamic, the `ansys-templates`_ tool was created. Using this @@ -23,13 +22,11 @@ Ansys templates documentation. Here are important links for this tool: - **Documentation**: https://templates.ansys.com - **Issues board**: https://github.com/ansys/ansys-templates/issues - .. note:: If you encounter any problem during the installation or usage of this tool, open a new issue on the `ansys-templates issues board`_. - PyAnsys available templates =========================== @@ -42,7 +39,6 @@ projects: ``pyansys`` and ``pyansys-advanced``. For information on how to use this tool, see `User guide`_ in the Ansys templates documentation. - PyAnsys template ---------------- @@ -63,7 +59,6 @@ this code: ansys-templates new pyansys - PyAnsys advanced template ------------------------- diff --git a/doc/styles/Vocab/ANSYS/accept.txt b/doc/styles/Vocab/ANSYS/accept.txt index 715a7ef53..48687cef7 100644 --- a/doc/styles/Vocab/ANSYS/accept.txt +++ b/doc/styles/Vocab/ANSYS/accept.txt @@ -22,7 +22,7 @@ deserializes Deserializing Dev (?i)Dns -Docformatter +[Dd]ocformatter [Dd]ocstring [Dd]ocstrings [Dd]octest diff --git a/examples/README.rst b/examples/README.rst index 6c563100c..aab424e98 100644 --- a/examples/README.rst +++ b/examples/README.rst @@ -1,4 +1,4 @@ General example -############### +=============== -This gallery consists of introductory example using pyvista. \ No newline at end of file +This gallery consists of introductory example using PyVista. \ No newline at end of file diff --git a/examples/pyvista_example.py b/examples/pyvista_example.py index 019327db8..07aed87a7 100644 --- a/examples/pyvista_example.py +++ b/examples/pyvista_example.py @@ -1,21 +1,24 @@ """ .. _adding_a_new_gallery_example: -Adding a New Gallery Example +Adding a new gallery example ============================ + This example demonstrates how to add a new PyAnsys `Sphinx Gallery `_ example as well as being a template that can be used in their creation. Each example should have a reference tag/key in the form: -``.. __example:`` +``.. __example:``. + The ``.. _`` is necessary. Everything that follows is your reference tag, which can potentially be used within a docstring. As convention, we keep all references in ``snake_case``. This section should give a brief overview of what the example is about and/or -demonstrates. The title should be changed to reflect the topic your example +demonstrates. The title should be changed to reflect the topic your example covers. New examples should be added as python scripts to: ``examples/-/.py`` + .. note:: Avoid creating new directories unless absolutely necessary. If you *must* @@ -32,8 +35,9 @@ import pyvista as pv ############################################################################### -# Section Title +# Section title # ~~~~~~~~~~~~~ +# # Code blocks can be broken up with text "sections" which are interpreted as # restructured text. # @@ -45,9 +49,10 @@ # # As in Jupyter notebooks, if a statement is unassigned at the end of a code # block, output will be generated and printed to the screen according to its -# ``__repr__`` method. Otherwise, you can use ``print()`` to output text. +# ``__repr__`` method. Otherwise, you can use ``print()`` to output text. # Create a dataset and exercise its repr method + dataset = pv.Sphere() dataset @@ -55,23 +60,21 @@ # Plots and images # ~~~~~~~~~~~~~~~~ # If you use anything that outputs an image (for example, -# :func:`pyvista.Plotter.show`) the resulting image will be rendered within the +# :func:`pyvista.Plotter.show`) the resulting image is rendered within the # output HTML. # # .. note:: # # Unless ``sphinx_gallery_thumbnail_number = `` is included at the top -# of the example script, first figure (this one) will be used for the +# of the example script, first figure (this one) is used for the # gallery thumbnail image. # # Also note that this image number uses one based indexing. - dataset.plot(text="Example Figure") - ############################################################################### -# Caveat - Plotter must be within One Cell +# Caveat - plotter must be within one cell # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ # It's not possible for a single :class:`pyvista.Plotter` object across # multiple cells because these are closed out automatically at the end of a @@ -86,20 +89,20 @@ actor ############################################################################### -# This Cell Cannot Run the Plotter +# This cell cannot run the plotter # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -# The plotter will already be closed by ``sphinx_gallery``. +# The plotter is already closed by ``sphinx_gallery``. # This cannot be run here because the plotter is already closed and would raise # an error: # >>> pl.show() # You can, however, close out the plotter or access other attributes. -pl.close() +pl.close() ############################################################################### -# Making a Pull Request +# Making a pull request # ~~~~~~~~~~~~~~~~~~~~~ # Once your example is complete and you've verified it builds locally, you can # make a pull request (PR). @@ -111,5 +114,5 @@ # .. note:: # # You only need to create the Python source example (``*.py``). The Jupyter -# notebook and the example HTML will be auto-generated via `sphinx-gallery +# notebook and the example HTML are auto-generated via `sphinx-gallery # `_.