diff --git a/doc/source/documentation_style/coding_style.rst b/doc/source/coding_style/beyond_pep8.rst similarity index 94% rename from doc/source/documentation_style/coding_style.rst rename to doc/source/coding_style/beyond_pep8.rst index a6093711f..b334d0d92 100644 --- a/doc/source/documentation_style/coding_style.rst +++ b/doc/source/coding_style/beyond_pep8.rst @@ -1,10 +1,6 @@ -Coding Style and Best Practices -############################### -This page provides best practices applicable to the `PyAnsys -`_ project. The intent is -not to repeat coding style documentation but rather to state -the approach used by the PyAnsys project when there are any -delineations, clarifications, or additional procedures above and +Beyond PEP8 +########### +This topic describes any delineations, clarifications, or additional procedures above and beyond `PEP8 `__. For example, `Stack Overflow Answer `_ @@ -87,7 +83,7 @@ Python, an alternative is to create a custom ``DeprecationError``. """Empty init.""" RuntimeError.__init__(self, message) -You then use this custom ``DeprecationError`` in place of an ``Exception``. +You can then use this custom ``DeprecationError`` in place of an ``Exception``. .. code:: python @@ -142,7 +138,7 @@ also be used to perform regression testing to verify that the code is executing as expected. This is an important feature of maintainable documentation as examples -must always match the API they are documenting. When using `doctest`` +must always match the API they are documenting. When using ``doctest`` through ``pytest``, any changes within the API without corresponding changes in the documentation will trigger doctest failures. @@ -270,8 +266,8 @@ example by referencing the key ``icepak``. """ -Useful Features -~~~~~~~~~~~~~~~ +Useful ``doctest`` Features +~~~~~~~~~~~~~~~~~~~~~~~~~~~ Ellipses for Random Output ************************** @@ -299,7 +295,7 @@ To support this, ``doctest`` must be run with the option set to allow ellipses. The directive ``# doctest: +SKIP`` can be added to any line of a docstring example so that it is not executed in ``doctest-modules``. This is useful for examples that cannot run within ``pytest`` or have -side-effects that will affect the other tests if they are run during +side effects that will affect the other tests if they are run during the ``doctest`` session. .. code :: python diff --git a/doc/source/coding_style/flake8.rst b/doc/source/coding_style/flake8.rst index 1b64abaf2..1780f642a 100644 --- a/doc/source/coding_style/flake8.rst +++ b/doc/source/coding_style/flake8.rst @@ -2,7 +2,7 @@ Style Guide Enforcement ======================= -The following sections describe the use of `Flake8`_ for `PEP8`_ style +This topic describes the use of `Flake8`_ for `PEP8`_ style enforcement and the minimum standards expected. PyAnsys libraries are expected to be consistent with these guidelines. @@ -27,7 +27,7 @@ Configuring Flake8 Flake8 supports configuring a specific set of style rules to enforce. This configuration can be stored in your library in a ``setup.cfg``, ``tox.ini``, or ``.flake8`` file. PyAnsys libraries -store the flake8 configuration in a ``.flake8`` file at the root of the +store the Flake8 configuration in a ``.flake8`` file at the root of the repository. Here is an example of a ``.flake8`` configuration file from a PyAnsys @@ -44,48 +44,50 @@ library: statistics = True Flake8 has many options that can be set within the configuration file. -A list of possible options can be found `here `__. +For a list and descriptions, see this `Flake8 documentation topic +`__. -The above configuration defines the following options: +The example configuration defines the following options: - ``exclude`` - This denotes subdirectories and ``doc/_build``, along with all + Denotes subdirectories and ``doc/_build``, along with all ``__init__.py`` files to be excluded from the check. - ``select`` - This is a sequence of error codes that flake8 will report errors + Sequence of error codes that Flake8 will report errors for. The set in the above configuration is a basic set of errors to check for and is not an exhaustive list. - A full list of error codes and their descriptions can be found `here `__. + For a full list of error codes and their descriptions, see this `Flake8 + documentation topic `__. - ``count`` - The total number of errors is printed at the end of the check. + Total number of errors to print at the end of the check. - ``max-complexity`` - This sets the maximum allowed McCabe complexity value for a block of code. + Sets the maximum allowed McCabe complexity value for a block of code. The value of 10 was chosen because it is a common default. - ``max-line-length`` - This denotes the maximum line length for any one line of code. + Denotes the maximum line length for any one line of code. The `PEP8`_ standard advises a maximum line length of 79. Because this is a bit limiting in some cases, the maximum line length recommended for a PyAnsys library is 100. - ``statistics`` - This enables the number of occurrences of each error or warning code + Number of occurrences of each error or warning code to be printed as a report at the end of the check. Running Flake8 -------------- -First, to install flake8, run: +First, to install Flake8, run: .. code:: python -m pip install flake8 -Then, flake8 can be run from inside your project directory by executing: +Then, you can run Flake8 from inside your project directory by executing: .. code:: @@ -95,7 +97,7 @@ This uses the configuration defined in the ``.flake8`` file to run the style checks on the appropriate files within the project and report any errors. -In PyAnsys libraries, flake8 is run as part of the CI/CD for code style. +In PyAnsys libraries, Flake8 is run as part of the CI/CD for code style. This action is run as a required check on pull requests, preventing code in violation of style rules from being merged into the code base. @@ -110,12 +112,12 @@ the formatting tool `black`_. On completing a code change, and before committing, `black`_ can be run to reformat the code, following the PEP8 guidelines enforced through -flake8. This will limit any manual code changes needed to address style +Flake8. This will limit any manual code changes needed to address style rules. .. _black: https://black.readthedocs.io/en/stable/ -Optionally, it is possible to automate the use of ``black``. This can be +Optionally, it is possible to automate the use of `black`_. This can be done with the tool `pre-commit`_. Setting up a `pre-commit hook to run black `_ will automatically format the code before committing. This simple way of @@ -128,7 +130,7 @@ PEP8 guidelines requires minimal manual effort. Minimum Standards ~~~~~~~~~~~~~~~~~ The following section describes the minimum set of code style standards -expected in an PyAnsys library. +expected in a PyAnsys library. * `W191`_ - **Indentation contains tabs.** @@ -193,11 +195,11 @@ expected in an PyAnsys library. * `E501`_ - **Line too long.** All code lines should not exceed 100 characters. The - `PEP8 line length `_ - guidelines suggest a maximum line length of 79. Following this limit + `PEP8 line length guideline `_ + suggests a maximum line length of 79. Following this limit is not as necessary today due to modern screen sizes. The suggested maximum length of 100 can be easier to accommodate and can still support - viewing files side-by-side in code editors. + viewing files side by side in code editors. * `F401`_ - **Module imported but unused.** diff --git a/doc/source/coding_style/index.rst b/doc/source/coding_style/index.rst index f9a3e7896..5a59528fe 100644 --- a/doc/source/coding_style/index.rst +++ b/doc/source/coding_style/index.rst @@ -4,7 +4,7 @@ Coding Style ************ PyAnsys libraries are expected to follow `PEP8`_ and -be consistent in style and formatting with the "big three" +be consistent in style and formatting with the 'big three' data science libraries: `NumPy`_, `SciPy`_, and `pandas`_. .. _NumPy: https://numpy.org/ @@ -24,5 +24,6 @@ data science libraries: `NumPy`_, `SciPy`_, and `pandas`_. :hidden: :maxdepth: 3 + pep8_best_practices + beyond_pep8 flake8 - best_practices diff --git a/doc/source/coding_style/best_practices.rst b/doc/source/coding_style/pep8_best_practices.rst similarity index 91% rename from doc/source/coding_style/best_practices.rst rename to doc/source/coding_style/pep8_best_practices.rst index 1b3da7e2b..046ab000b 100644 --- a/doc/source/coding_style/best_practices.rst +++ b/doc/source/coding_style/pep8_best_practices.rst @@ -1,10 +1,10 @@ .. _best_practices: -Best Practices -============== -The following sections summarize the key points from `PEP8`_ and how +PEP 8 Best Practices +==================== +This topic summarizes key points from `PEP8`_ and how they apply to PyAnsys libraries. The goal is for PyAnsys libraries to -be consistent in style and formatting with the "big three" +be consistent in style and formatting with the `big three` data science libraries: `NumPy`_, `SciPy`_, and `pandas`_. .. _NumPy: https://numpy.org/ @@ -22,7 +22,7 @@ might only be discovered during runtime. .. _ImportError: https://docs.python.org/3/library/exceptions.html#ImportError -Avoid: +Instead of: .. code:: python @@ -40,13 +40,13 @@ Use: return math.log(8, x) -For better readability, you should group imports following this order: +For better readability, group imports in this order: #. Standard library imports #. Related third-party imports -#. Local application/library-specific imports +#. Local application- or library-specific imports -Avoid: +Instead of: .. code:: python @@ -75,7 +75,7 @@ Use: You should place imports in separate lines unless they are modules from the same package. -Avoid: +Instead of: .. code:: python @@ -99,9 +99,10 @@ Use: You should avoid using wild cards in imports because doing so -can make it difficult to detect undefined names. For more details see `Python Anti-Patterns: using wildcard imports <(https://docs.quantifiedcode.com/python-anti-patterns/maintainability/from_module_import_all_used.html>`_. +can make it difficult to detect undefined names. For more information, +see `Python Anti-Patterns: using wildcard imports <(https://docs.quantifiedcode.com/python-anti-patterns/maintainability/from_module_import_all_used.html>`_. -Avoid: +Instead of: .. code:: python @@ -157,7 +158,7 @@ Inside a class, use a single line before any method definition. """Second method docstring""" return -To make it clear when a "paragraph" of code is complete and a new section +To make it clear when a 'paragraph' of code is complete and a new section is starting, use a blank line to separate logical sections. Instead of: @@ -227,9 +228,8 @@ classic loop. Naming Conventions ------------------ -It is important to use concise and descriptive names for classes, -methods, functions, and constants for readable and maintainable -code. Regardless of the programming language, you must follow these +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: #. Choose descriptive and unambiguous names. @@ -264,7 +264,7 @@ from PyPi. Class Naming Conventions ~~~~~~~~~~~~~~~~~~~~~~~~ -Use `CamelCase `_ when naming classes. Do not separate words +Use `camel case `_ when naming classes. Do not separate words with underscores. .. code:: python @@ -301,7 +301,7 @@ words with underscores to improve readability. """This method should only be called from ``MyClass``. Protected methods can be called from inherited classes, - unlike private methods, which names are "mangled" to avoid + unlike private methods, which names are 'mangled' to avoid these methods from being called from inherited classes. """ @@ -337,7 +337,7 @@ readability. Comments --------- +~~~~~~~~ Because a PyAnsys library generally involves multiple physics domains, users 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 @@ -403,7 +403,7 @@ avoided: Focus on writing self-documenting code and using short but descriptive variable names. -Avoid: +Instead of: .. code:: python @@ -416,21 +416,21 @@ Use: user_name = 'John Smith' -Documentation Convention ------------------------- +Docstring Conventions +~~~~~~~~~~~~~~~~~~~~~ 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. Write docstrings for all public modules, functions, classes, and -methods. Docstrings are not necessary for non-public methods, but such +methods. Docstrings are not necessary for private methods, but such methods should have comments that describe what they do. To create a docstring, surround the comments with three double quotes on either side. For a one-line docstring, keep both the starting and ending ``"""`` on the -same line. +same line: .. code:: python @@ -440,27 +440,27 @@ For a multi-line docstring, put the ending ``"""`` on a line by itself. PyAEDT follows the `numpydoc `_ -documentation style, which is used by `numpy `_, +docstring style, which is used by `numpy `_, `scipy `_, `pandas `_, and a variety of other Python open -source projects. For a full description of the code style, reference -`PyAnsys sphinxdocs `_. +source projects. For more information on docstrings for PyAnsys +libraries, see :ref:`api_documentation`. Programming Recommendations ---------------------------- -This section provides some `PEP8 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The following sections provide some `PEP8 `_ suggestions for removing ambiguity and preserving consistency. They address some common pitfalls when writing Python code. Booleans and Comparisons -~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------ Don't compare Boolean values to ``True`` or ``False`` using the equivalence operator. -Avoid: +Instead of: .. code:: python @@ -478,7 +478,7 @@ Knowing that empty sequences are evaluated to ``False``, don't compare the length of these objects but rather consider how they would evaluate by using ``bool()``. -Avoid: +Instead of: .. code:: python @@ -496,7 +496,7 @@ Use: In ``if`` statements, use ``is not`` rather than ``not ...``. -Avoid: +Instead of: .. code:: python @@ -515,10 +515,10 @@ especially important when parsing arguments. Handling Strings -~~~~~~~~~~~~~~~~ +---------------- Use ``.startswith()`` and ``.endswith()`` instead of slicing. -Avoid: +Instead of: .. code:: python @@ -540,7 +540,7 @@ Use: 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. @@ -559,7 +559,7 @@ Bad practice - Example 2 Duplicated Code -~~~~~~~~~~~~~~~ +--------------- Follow the DRY principle, which states that "Every piece of knowledge must have a single, unambiguous, authoritative representation within a system." Attempt to follow this principle unless it overly complicates @@ -619,7 +619,7 @@ correct. Nested Blocks -~~~~~~~~~~~~~ +------------- Avoid deeply nested block structures (such as conditional blocks and loops) within one single code block. @@ -652,13 +652,13 @@ reusable and unit-testable. Loops -~~~~~ +----- While there is nothing inherently wrong with nested loops, to avoid -certain pitfalls, avoid having loops with more than two levels. In +certain pitfalls, steer clear of having loops with more than two levels. In some cases, you can rely on coding mechanisms like list comprehensions -to avoid nested loops. +to circumvent nested loops. -Rather than: +Instead of: .. code:: @@ -695,7 +695,7 @@ example, extract all consonants in a sentence: This is better implemented by creating a simple method to return if a -letter is a consonant. +letter is a consonant: >>> def is_consonant(letter): ... """Return ``True`` when a letter is a consonant.""" diff --git a/doc/source/documentation_style/class_documentation.rst b/doc/source/documentation_style/class_documentation.rst index fb7852d58..b8ec2f0fc 100644 --- a/doc/source/documentation_style/class_documentation.rst +++ b/doc/source/documentation_style/class_documentation.rst @@ -1,17 +1,17 @@ Class Documentation ################### -There are two main ways of using Sphinx to document an API class: +There are two main ways of using Sphinx to document a class: -* Manually describe "how" and "why" to use a class in either +* Manually describe 'how' and 'why' to use a class in either a "User Guide" or an example within the library's documentation -* Automatically generate API documentation for classes using the +* Automatically generate documentation for classes using the ``autoclass`` or ``autosummary`` directive Manual Documentation -------------------- -To manually describe "how" and "why" to exercise a class, use the +To manually describe 'how' and 'why' to exercise a class, use the ``.. code:: python`` directive:: Initialize ``my_module.MyClass`` with initial parameters. These @@ -24,7 +24,7 @@ To manually describe "how" and "why" to exercise a class, use the >>> my_obj.parm1 'apple' -This is rendered as: +In the documentation, this is rendered as: Initialize ``my_module.MyClass`` with initial parameters. These parameters are automatically assigned to the class. @@ -37,7 +37,7 @@ parameters are automatically assigned to the class. 'apple' -Auto-Generated Documentation +Auto-generated Documentation ---------------------------- To automatically generate class descriptions, use either the ``autoclass`` @@ -48,7 +48,7 @@ For simple classes, use the ``autoclass`` directive:: .. autoclass:: pyansys_sphinx_theme.samples.ExampleClass :members: -This is rendered as: +In the documentation, this is rendered as: .. autoclass:: pyansys_sphinx_theme.samples.ExampleClass :members: diff --git a/doc/source/documentation_style/docstrings.rst b/doc/source/documentation_style/docstrings.rst index bcc20c600..0c875096a 100644 --- a/doc/source/documentation_style/docstrings.rst +++ b/doc/source/documentation_style/docstrings.rst @@ -3,8 +3,12 @@ Docstring Standards ################### When writing docstrings for PyAnsys libraries, use the `numpydoc`_ -documentation style. To use `numpydoc`_, add the following to your -``conf.py`` file: +style, regardless as to whether you are using this Sphinx extension or the +`napoleon `_ Sphinx extension +to generate your library documentation. + +You add the extension to use for documentation generation in your ``conf.py`` file. +For example, to use `numpydoc`_, you would add: .. code:: python @@ -15,23 +19,23 @@ documentation style. To use `numpydoc`_, add the following to your For consistency within PyAnsys libraries, always use ``"""`` to introduce and conclude a docstring, keeping the line length shorter than 70 characters. Ensure that there are no blank spaces at the end of a line because they will cause errors in build checks that you -will then have to resolve. +will have to resolve. A blank line signifies the start of a new paragraph. To create a bulleted or numbered list, ensure that there is a blank line before the first item and after the last item. Because you -use the same markup in your docstrings as you do in RST files, see this `quick reference +use the same markup in docstrings as you do in RST files, see this `quick reference `_. Surround any text that you want to set apart as literal text in double back ticks to render it in a monospace gold font. Use double back ticks to surround the names of files, folders, classes, methods, and variables. For example:: - """Initialize the ``Desktop`` class with the version of AEDT to use.`` + """Initialize the ``Desktop`` class with the version of AEDT to use.""" .. note:: The PyAnsys style uses two back ticks to surround the names of classes, methods, and - variables, not the single back tick that is recommended by the `numpydoc`_ documentation + variables, not the single back tick that is recommended by `numpydoc`_ style. @@ -39,19 +43,19 @@ Minimum Section Requirements ---------------------------- PyAnsys library docstrings contain these `numpydoc`_ sections as a minimum: -* `Short description `_. +* `Short description `_ * `Extended Summary `_ if applicable * `Parameters `_ if applicable * `Returns `_ if applicable * `Examples `_ -These sections should follow numpydoc standards. To avoid inconsistencies between -PyAnsys libraries, adhere to the additional standards that follow. +These sections should follow numpydoc style. To avoid inconsistencies between +PyAnsys libraries, adhere to the additional style guidelines that follow. Classes ~~~~~~~ -A class is a "noun" representing a collection of methods. For consistency within PyAnsys libraries, -always start the brief description for a class with a verb ending in "s", followed by an extended +A class is a 'noun' representing a collection of methods. For consistency within PyAnsys libraries, +always start the brief description for a class with a verb ending in 's', followed by an extended summary if applicable:: class FieldAnalysis3D(Analysis): @@ -68,17 +72,17 @@ Ensure that there is a line break between the end of a class docstring and the s 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 +A method is a 'verb' representing an action that can be performed. For consistency within PyAnsys +libraries, always start the brief description for a method with a verb not ending in 's', followed by an extended summary if applicable:: def export_mesh_stats(self, setup_name, variation_string="", mesh_path=None): - """Export mesh statistics to a file." + """Export mesh statistics to a file.""" Methods with a leading underscore (_) are 'protected' methods, meaning that they are not rendered in the -documentation unless an explicit request is made to add them using Sphinx directives. However, clearing -documenting private methods is still important. +documentation unless an explicit request is made to add them using Sphinx directives. However, clearly +written descriptions for private methods are still important. If a method has the decorator ``@property``, it is turned into a property, which is described as a 'noun' rather than a 'verb'. Because the resulting property cannot have parameters, you remove @@ -170,7 +174,7 @@ It is possible for more than one item to be returned:: If a method does not have a decorator, the basic implementation of Python -methods is used. In this case, ``None`` is returned but you do not document it. +methods is used. In this case, while ``None`` is returned, you do not document it. Consequently, such a method does not have a 'Returns' section. Example Docstrings @@ -205,19 +209,18 @@ This will issue the following warning for any object without a docstring:: "The object does not have a docstring" The ``"GL08"`` code is required at minimum for PyAnsys libraries. -Other codes may be enforced at a later date. For a full listing, in the `numpydoc`_, -see the `Validation `_ -topic. +Other codes may be enforced at a later date. For a full listing, +see `Validation `_ +in the `numpydoc`_. Additional Information ---------------------- -Additional examples and notes can be found at `numpydoc`_. Reference -this documentation as the primary source of information regarding -docstring styles for directives that are not covered here. For example, -you would use the ``note::`` directive to highlight important information -and the ``warning::`` directive to point out an action that might result -in data loss. +You can find additional information and examples at `numpydoc`_. Reference +this documentation as the primary source regarding docstring styles for directives +that are not covered here. For example, you use the ``note::`` directive to highlight +important information and the ``warning::`` directive to point out an action that +might result in data loss. .. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html .. _googledoc: https://google.github.io/styleguide/ diff --git a/doc/source/documentation_style/index.rst b/doc/source/documentation_style/index.rst index fabd7d50b..1095ea68a 100644 --- a/doc/source/documentation_style/index.rst +++ b/doc/source/documentation_style/index.rst @@ -6,7 +6,7 @@ Good API documentation drives library adoption and usage and is the foundation for a good developer experience. Even with the best interfaces and the most functional product, no one will adopt the API if they don't know how to use it or if they aren't satisfied with the -documentation or examples they are presented with. +documentation or examples that they are presented with. Good API documentation provides: @@ -22,10 +22,10 @@ Good API documentation provides: The documentation for a PyAnsys library should contain: -* Module, class, method, and function documentation strings. See +* Module, class, method, and function docstrings. See :ref:`docstrings`. * Full gallery of examples. See `PyMAPDL Examples - `_ + `_. * Developer's guide for the library. * Link to this developer's guide. @@ -35,4 +35,3 @@ The documentation for a PyAnsys library should contain: docstrings class_documentation - coding_style diff --git a/doc/source/guidelines/doc_practices.rst b/doc/source/guidelines/doc_practices.rst index ee4252268..1648cd030 100644 --- a/doc/source/guidelines/doc_practices.rst +++ b/doc/source/guidelines/doc_practices.rst @@ -17,13 +17,14 @@ key. To keep documentation up to date with rapdily evolving code: - Perform periodic reviews The generation of PyAnsys documentation uses `Sphinx `__ -and an Ansys-branded theme (pyansys-sphinx-theme) to assemble content comes from docstrings, -reStructuredText (RST) files, and Python (PY) example files. +and an Ansys-branded theme (`pyansys-sphinx-theme `_) +to assemble content that comes from docstrings, reStructuredText (RST) files, and Python (PY) +example files. Docstrings ---------- -Docstrings must be formatted so that Sphinx can parse them. You can use either the -``numpydoc``or ``napoleon`` Sphinx extension: +Docstrings must be formatted so that Sphinx can parse them. You can use either of these +Sphinx extensions: - `numpydoc `_ - `napoleon `_ @@ -42,16 +43,13 @@ style docstrings, refers you to the `Google Python Style Guide `_ guide. @@ -96,7 +94,7 @@ For comprehensive syntax information, see the `reStrucutredText Markup Specifica Because you need to be familiar with the content in the *PyAnsys Developer's Guide*, page through its HTML pages and then explore the RST files in its repository. This will help you to understand -the syntax and see how RST files are nested to create this guide. +the syntax and see how RST files have been nested to create this guide. Examples -------- @@ -126,11 +124,13 @@ Accessing a Library's Documentation Documentation for the latest stable release of a PyAnsys library is accessible from its repository. You can generally access the latest development version of the documentation tracking the ``main`` branch by adding the prefix ``dev.`` to -the URL for the latest stable release. For example, the URL for documentation of the -latest stable release of PyAEDT is ``_, and -the URL for the latest documentation for the development version of PyAEDT is -``_. The latest development versions of both -the library and its documentation are kept up-to-date automatically via GitHub actions. +the URL for the latest stable release. For example, consider PyAEDT documentation. + +- The URL for documentation of the latest stable release is ``_. +- The URL for documentation of the lastest development version is ``_. + +The latest development versions of both the library and its documentation are automatically kept +up-to-date via GitHub actions. .. _doc_building: @@ -149,7 +149,7 @@ and running. #. If a PyAnsys library already exists, create a directory in which to place a clone of its GitHub repository. -#. Clone the PyAnsys library's repository. For more information, see :ref:`cloning`. +#. Clone the PyAnsys library's GitHub repository. For more information, see :ref:`cloning`. #. If you have not yet cloned the ``pyansys-sphinx-theme`` repository, clone it. @@ -199,7 +199,7 @@ that the full library is installed. #. After local documentation builds successfully, navigate to ``doc/_build/html/`` and use your browser to open the ``index.html`` file to review the documentation, - repeating this process until there are no errors or obvious issues. + repeating the local build process until there are no errors or obvious issues. .. note:: You can use ``make.bat`` to build more than HTML output. To view a summary of @@ -218,7 +218,8 @@ or GitBash. Using Windows PowerShell to Clone a GitHub Repository ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -#. In Windows PowerShell, navigate to where you clone repositories on your machine. +#. In Windows PowerShell, navigate to the directory on your machine where you want + to clone GitHub repositories. #. Go to the `PyAnsys GitHub account `_ and select the repository that you want to clone. @@ -236,28 +237,29 @@ Using Windows PowerShell to Clone a GitHub Repository #. Go back to Windows Powershell and type ``git clone`` and then click the right mouse button to paste the copied path. -#. Press ``Enter`` to copy the files in the repository to yoour local directory. +#. Press ``Enter`` to copy the files in the repository to your local directory. -#. Type ``ls`` to see a list of the files now in your local directory. +#. Type ``ls`` to see a list of the files now in the folder for this repository + in your local directory. .. note:: In Anaconda Powershell, typing ``dir`` is the equivalent to typing ``ls``. Using GitBash to Clone a GitHub Repository ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -#. In the folder where you clone PyAnsys repositories, right-click and select - ``GitBash Here``. +#. In the directory where you want to clone PyAnsys repositories, right-click and + select ``GitBash Here``. #. Type ``git clone`` followed by the address of the repo to clone. For example, to clone the ``pyansys-sphinx-theme`` repository, you would -enter: +type and enter: .. code:: git clone https://github.com/pyansys/pyansys-sphinx-theme -.. _create_pr: +.. _push_changes: Pushing Changes to the GitHub Repository ---------------------------------------- @@ -265,17 +267,16 @@ Once you have tested your changes in local documentation builds and are satisifed with them, you can push them to the library's GitHub repository. You can use Git commands or Git Extension to accomplish this. -For documentation changes, the branch name should have a prefix of ``doc\`` +For documentation changes, the branch name should always have a prefix of ``doc/`` followed by a short description of what you've changed. For more information, see :ref:`branch_naming`. Using Git Commands to Push Changes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This procedure assumes that you are using Git Commands to push your changes to the -GitHub repository. +To use Git commands to push your changes to the GitHub repository: #. In Windows Command Prompt, navigate to the directory where you cloned - the GitHub reposity. + the GitHub repository. #. Type ``git status`` to see a summary of the changes that you have made in this directory. @@ -325,15 +326,14 @@ GitHub repository. .. note:: For any subsequent push, you would simply use ``git push``. -#. Complete the PR as described in :ref:`complete_pr`. +#. Create the PR as described in :ref:`create_pr`. Using Git Extensions to Push Changes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This procedure assumes that you are using Git Extensions to push your changes to the -GitHub repository. +To use Git Extensions to push your changes to the GitHub repository: #. In Git Extensions, select ``Commands > Create branch`` and then provide a name for - the branch that you want to create, using the prefix ``doc`` followed by a short + the branch that you want to create, using the prefix ``doc/`` followed by a short description of what you intend to change. #. Make your documentation changes in the directory where you cloned the library's @@ -354,23 +354,27 @@ GitHub repository. #. Do a push of your branch to the GitHub repsitory. -#. Complete the PR as described in :ref:`complete_pr`. +#. Create the PR as described in :ref:`create_pr`. + +.. _create_pr: -.. _complete_pr: +Creating the GitHub PR +---------------------- +Regardless of what method you used to push your changes, do the following to create +the GitHub PR: -Completing the GitHub PR -------------------------- #. Go to the GitHub reposity, where you will see an entry for your pushed branch. #. If the pushed branch resolves an issue, in its description, type ``Resolves #`` and select from the list of issues that appears. #. Create either a PR or draft PR, making the title a simple statement because - the PR title is rendered in our `automatic release generator `_. + our `automatic release generator `_ + uses this PR title in the automatic rendering of release notes. If your PR is ready for review, select ``Create pull request``. Otherwise, select ``Create draft pull request`` and mark it as ready for review once - you are satisified with it. + you it includes all of your changes and you are satisified with it. If you need to change a PR title, to its right, click the ``Edit`` button, which becomes a ``Save`` button while you are in editing mode.