Modify documentation (#399)

* Removing redundant code blocks

* remove sg_execution_times gitignore

* - python version correction

- image size
- checklist modification
- table modification

* Update doc/source/how-to/setting-up.rst

Review feedback

Co-authored-by: Maxime Rey <[email protected]>

* Adjust specing of lines

* update python supporting versions

* Apply suggestions from code review

Review from @PipKat

Co-authored-by: Kathy Pippert <[email protected]>

* Update doc/source/doc-style/formatting-tools.rst

Co-authored-by: Kathy Pippert <[email protected]>

* Update doc/source/coding-style/formatting-tools.rst

Co-authored-by: Kathy Pippert <[email protected]>

* Update doc/source/doc-style/formatting-tools.rst

Co-authored-by: Kathy Pippert <[email protected]>

* Apply suggestions from code review

Feedback from @PipKat

Co-authored-by: Kathy Pippert <[email protected]>

* Update doc/source/how-to/logging.rst

Co-authored-by: Kathy Pippert <[email protected]>

* Update doc/source/how-to/setting-up.rst

Co-authored-by: Kathy Pippert <[email protected]>

* Update doc/source/how-to/setting-up.rst

Co-authored-by: Kathy Pippert <[email protected]>

* Update doc/source/how-to/setting-up.rst

Co-authored-by: Kathy Pippert <[email protected]>

* Update doc/source/how-to/setting-up.rst

Co-authored-by: Kathy Pippert <[email protected]>

* Update doc/source/how-to/setting-up.rst

Co-authored-by: Kathy Pippert <[email protected]>

* Update doc/source/how-to/setting-up.rst

Co-authored-by: Kathy Pippert <[email protected]>

* vale check

* vale feedback

---------

Co-authored-by: Maxime Rey <[email protected]>
Co-authored-by: Kathy Pippert <[email protected]>
Co-authored-by: Roberto Pastor Muela <[email protected]>

Author: 4 people

.gitignore

@@ -165,3 +165,7 @@ cython_debug/
 
 # Sphinx autogen
 doc/source/how-to/api/*
+doc/source/sg_execution_times.rst
+
+# rstcheck
+.rstcheck.cfg

README.rst

@@ -1,8 +1,8 @@
-#########################
-PyAnsys Developer's Guide
-#########################
 
-The `PyAnsys Developer's Guide <https://dev.docs.pyansys.com>`_ is the central
+PyAnsys developer's guide
+=========================
+
+The `PyAnsys developer's guide <https://dev.docs.pyansys.com>`_ is the central
 document for:
 
 - Ansys developers who want to create and "own" PyAnsys libraries

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

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.

doc/source/coding-style/code/tox-flit.rst

@@ -3,18 +3,18 @@
     [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
     
     [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 =

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

doc/source/coding-style/deprecation.rst

@@ -1,5 +1,6 @@
 Deprecation best practices
 ==========================
+
 While deprecation best practices are outlined in a `Stack
 Overflow Answer <https://stackoverflow.com/questions/2536307>`_ and
 in this `Deprecation library <https://deprecation.readthedocs.io/>`_ ,

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,17 +28,17 @@ The minimum `black`_ configuration for a PyAnsys project should look like this:
     line-length = "<length>"
 
 
-Isort
------
+The ``isort``
+-------------
+
 The goal of `isort`_  is to properly format ``import`` statements by making sure
 that they follow the standard order:
 
 #. library
 #. 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 <https://reuse.software/>`_. 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 <https://github.com/ansys/pre-commit-hooks/blob/main/README.rst>` 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<product>-<library>`` project should be:
 
-
 .. tab-set::
 
     .. tab-item:: Tox with Flit
@@ -232,21 +235,20 @@ configuration for a PyAnsys ``py<product>-<library>`` 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 <env-name0>,<env-name1>,...```.  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/

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