diff --git a/doc/source/documentation_style/index.rst b/doc/source/documentation_style/index.rst index e275b380e..d4f29f399 100644 --- a/doc/source/documentation_style/index.rst +++ b/doc/source/documentation_style/index.rst @@ -1,8 +1,8 @@ .. _api_documentation: -Documentation Style -################### -Good documentation drives library adoption and usage and is the +API Documentation Style +####################### +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 diff --git a/doc/source/guidelines/dev_practices.rst b/doc/source/guidelines/dev_practices.rst index 7d562486f..858f1b506 100644 --- a/doc/source/guidelines/dev_practices.rst +++ b/doc/source/guidelines/dev_practices.rst @@ -126,87 +126,22 @@ like this: Documentation ------------- -The source and content for documentation varies from repository to repository. For a PyAnsys library, -documentation is generated from three sources: +Good documentation is essential to Python community members adopting PyAnsys libraries. +While the source and content for each library's documentation differs, the documentation +itself is generated from three sources: - Docstrings from the library's classes, functions, and modules using `sphinx.ext.autodoc `_. - reStructuredText (RST) files from ``doc/`` - Examples from ``examples/`` -General usage information and API descriptions should be placed within -``doc/source`` and docstrings. Full examples should be placed in -``examples/``. +Docstrings are included in the Python (PY) files for your API. General usage information +is provided in RST files that are placed in ``doc/source``. Full-fledged standalone examples +that are meant to be run as individual downloadable scripts are provided in PY files that are +placed in ``examples/``. -Adding a New Example -~~~~~~~~~~~~~~~~~~~~ -Examples come in two formats: - -- Basic code snippets demonstrating some functionality -- Full-fledged standalone examples meant to be run as individual downloadable scripts - -While basic code snippets should be placed in the ``doc/source`` directory, full-fledged -standalone examples must be placed in the ``examples`` directory at the root of the repository. - -When adding a standalone example, you add it to an applicable subfolder in the ``examples`` -directory. If none of the existing directories match the category of your example, create -a new subfolder with a ``README.txt`` file describing the new category. As these examples -are built using the Sphinx gallery extension, you must follow `Sphinx gallery coding guidelines _`. - -PyMAPDL provides a self-demonstrating example of how to `add an example reference key `_. - -Documentation Style and Organization -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Docstrings should follow `numpydocs docstring `_ -guidelines. Documentation within the ``doc/`` directory use the reStructuredText. -(RST) format. Examples within the ``examples/`` directory should be PEP 8-compliant -and will be compiled dynamically during the build process. Always ensure that -examples run properly locally because they will be verified through the CI performed -via GitHub Actions. - -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. - -Building Documentation Locally -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can build and verify the HTML documentation for a PyAnsys project locally -by installing Sphinx and other documentation build dependencies. - -#. Optionally install the project in development mode: - -.. code:: - - pip install -e . - -#. Install the build requirements for documentation: - -.. code:: - - pip install -r requirements_docs.txt - - -#. If running on Linux/Mac OS, build the documentation: - -.. code:: - - make -C doc html - -Otherwise, if running on Windows, build the documentation: - -.. code:: - - cd doc - make.bat html - -#. After documentation builds successfully locally, navigate to - ``doc/_build/html/`` and use your browser to open the - ``index.html`` so that you can review the documenation. +For comprehensive documentation guidelines, including how to build documentation locally, +see :ref:`doc_practices`. Continuous Integration and Continuous Delivery (CI/CD) ------------------------------------------------------ diff --git a/doc/source/guidelines/doc_practices.rst b/doc/source/guidelines/doc_practices.rst new file mode 100644 index 000000000..a4251e0c2 --- /dev/null +++ b/doc/source/guidelines/doc_practices.rst @@ -0,0 +1,346 @@ +.. _doc_practices: + +Documentation Practices +======================= +The generation of documentation uses `Sphinx `__ +and an Ansys-branded theme. Documentation is built from docstrings, reStructuredText +(RST) files, and Python (PY) example files. + +Docstrings +---------- +Docstrings must be formatted so that Sphinx can parse them. You can use either the +``numpydoc``or ``napoleon`` Sphinx extension: + + - `numpydoc `_ + - `napoleon `_ + +The ``numpydoc`` extension is generally preferred because it supports an API +documentation structure with one page per method, providing Python community +members with documentation like that generated by `pandas `_ +and `NumPy `_. If, however, your API is very linear, you +might prefer the ``napoleon`` extension because it supports a documentation +structure where everything needed to solve a certain problem can be shown on one page. + +The ``numpydoc`` extension provides its own `style guide `_ +and a `user guide `_ that explains how to use +the extension with Sphinx. The ``napoleon`` extension, which parses both numpy and Google +style docstrings, refers you to the `Google Python Style Guide `_. + +Regardless of the extension that you choose for generating documentation, we +recommend the use of numpy-style docstrings so that there is consistency +across PyAnsys libraries. For more information, see :ref:`api_documentation`. + +RST Files +--------- +To provide general usage information in your documentation, you use your favorite editor to +create RST files that you then place in the repository's ``doc/`` directory. The ``index.rst`` +file in the ``doc\source`` directory defines the first level of the your documentation hierarchy. +The ``toctree`` directive indicates the maximum number of heading levels that the documentation +is to display. Below this directive are the directory names for your documentation sections. +Each documentation section has its own ``index.rst`` file. + +For example, if you open the ``index.rst`` file in the ``doc\source`` directory in the +``dev-guide`` repository, you will see that the ``toctree`` direction indicates that the +*PyAnsys Developer's Guide* is to display a maximum of three heading levels. You then +see the section structure for this guide: + +.. code:: + + overview/index + guidelines/index + library_description/index + coding_style/index + documentation_style/index + +While you do not include the ``.rst`` extension when defining the section structure, the +index file referenced for each section must be named ``index.rst``. If you open ``index.rst`` +in ``doc\source\overview``, you can see that it describes how the PyAnsys project provides +Python libraries that expose Ansys technologies to the Python ecosystem. + +After you build documenatation locally as described in :ref:`doc_building`, the first-level +heading in the ``index.rst`` file for each docuemntation section is shown as clickable link +in the header of the documentation's generated HTML output. + +You can nest RST files. Plenty of examples of nested RST files are available in the PyAnsys +libraries on GitHub. Because you need to be familiar with the content in the *PyAnsys Developer's +Guide*, paging through this doc and exploring its repository will help you better +understand how RST files are used. For more information on defining documentation +structure, see the `Sphinx Getting Started `_ +documentation. + +Examples +-------- +Examples come in two formats: + +- Basic code snippets demonstrating some functionality +- Full-fledged standalone examples that are meant to be run as individual downloadable scripts + +Basic code snippets should be placed in the ``doc/source`` directory. Full-fledged +standalone examples must be placed in the ``examples`` directory at the root of the +repository. All of these examples, which should be PEP 8-compliant, are compiled dynamically +during the build process. Always ensure that your examples run properly locally because +they will be verified through the CI performed via GitHub Actions. + +Adding a New Example +~~~~~~~~~~~~~~~~~~~~ +Adding a standalone example consists of placing it in an applicable subfolder in the ``examples`` +directory. If none of the existing directories match the category of your example, create +a new subfolder with a ``README.txt`` file describing the new category. Because these examples +are built using the `Sphinx-Gallery `_ +extension, you must follow its `coding guidelines `_. + +PyMAPDL provides a self-demonstrating example of how to `add an example reference key `_. + +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. + +.. _doc_building: + +Building Documentation Locally +------------------------------ +You can build and verify the HTML documentation for a PyAnsys library locally +by installing Sphinx and other documentation build dependencies. + +Setting Up Your Machine +~~~~~~~~~~~~~~~~~~~~~~~ +Anaconda provides Python and tools, such as a Python IDE (Interactive Development Environment), +a Python command line editor, and Sphinx dependencies. This gives you what you need to get up +and running. + +#. Install the `Anaconda individual edition `_. + +#. 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`. + +#. If you have not yet cloned the ``pyansys-sphinx-theme`` repository, clone it. + +Installing Build Requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +You can build documentation for the ``dev_guide`` and ``pyansys-sphinx-theme`` repositories without +installing a PyAnsys library in development mode. However, when you push changes that you have made +in a local branch to the GitHub repository for other PyAnsys libraries, CI checks typically require +that the full library is installed. + +#. In Anaconda Powershell, navigate to the base directory in the library's cloned repository. + +#. If your library must be installed in development mode, enter: + + .. code:: + + pip install -e . + +#. To install the build requirements for generating documentation, enter: + + .. code:: + + pip install -r requirements_docs.txt + +#. If you are running on a Linux/Mac OS, to build the documentation, enter: + + .. code:: + + make -C doc html + +#. If you are running on Windows, to build the documentation, enter two + commands: + + .. code:: + + cd doc + make.bat html + + + As Sphinx is generating HTML output in the library's ``doc\_build\html`` folder, + Anaconda Powershell displays any errors and warnings for unexpected indentations, + bad target locations for links, missing files, and extra files included in the + repository but not referenced by any ``index.rst`` file. + +#. Resolve all indicated issues before submitting a pull request (PR) to push + your changes to the library's GitHub repository. + +#. 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. + +.. note:: + You can use ``make.bat`` to build more than HTML output. To view a summary of + all target options, enter ``make.bat``. + +Your next step is to push your changes to the library's GitHub repository +by creating a PR. For more information, see :ref:`create_pr`. + +.. _cloning: + +Cloning a GitHub Repository +--------------------------- +While developers likely know how to clone a GitHub repository, technical documentation +specialists may not know how to do this. You can easily use either Windows PowerShell +or GitBash. + +Using Windows PowerShell to Clone a GitHub Repository +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +#. In Windows PowerShell, navigate to where you clone repositories on your machine. + +#. Go to the `PyAnsys GitHub account `_ and select the + repository that you want to clone. + + Because the list of repositories is quite long, you can use the ``Find + a repository`` option to search for the repository that you want to clone. For + example, you can seach for "theme" to find the ``pyansys-sphinx-theme`` repository. + +#. In the upper right corner of the repository, click the green ``Code`` button to + drop down a list of options. + +#. To the right of the ``HTTPS`` option, click the clipboard icon to copy the path to + the 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. + +#. Type ``ls`` to see a list of the files now 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``. + +#. Type ``git clone`` followed by the address of the repo to clone. + +For example, to clone the ``pyansys-sphinx-theme`` repository, you would +enter: + +.. code:: + + git clone https://github.com/pyansys/pyansys-sphinx-theme + +.. _create_pr: + +Pushing Changes to the GitHub Repository +---------------------------------------- +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\`` +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. + +#. In Windows Command Prompt, navigate to the directory where you cloned + the GitHub reposity. + +#. Type ``git status`` to see a summary of the changes that you have made in this + directory. + +#. Create a branch by entering ``git checkout -b`` followed by the name to give + this branch. + + The option ``-b`` is for adding a branch. If you were adding a branch with documentation + changes to the ``Contributing`` topic, you might enter: + + .. code:: + + git checkout -b doc/edit_contributing + +#. Enter ``git add .`` to stage the changed files to commit. + +#. Enter ``git status`` again to see all files that are staged for committing in green. + +#. If any unnecessary files are staged, delete them in File Explorer and then enter ``git status`` + again to ensure that the final red line indicates that these files have been deleted. + +#. If you make any additional file changes, type ``git add .`` again to restage the files to + commit. + +#. When finished, commit your changes to GitHub history by entering ``git commit -m`` followed by + a description in quotation marks. + + For the given example, you might enter: + + .. code:: + + git commit -m "Edit Contributing topic" + + The number of files changed are shown, followed by the number of insertions and deletions. + A create mode or rename doc action is then shown for each file. + +#. For the first push of a newly created branch, enter ``git push --set-upstream origin``, + followed by the branch name. + + For the given example, you would enter: + + + .. code:: + + git push --set-upstream origin doc/edit_contributing + + .. note:: + For any subsequent push, you would simply use ``git push``. + +#. Complete the PR as described in :ref:`complete_pr`. + +Using Git Extensions to Push Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +This procedure assumes that you are using 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 + description of what you intend to change. + +#. Make your documentation changes in the directory where you cloned the library's + GitHub reposity. + +#. Test your changes in local documentation builds. For more information, see + :ref:`doc_building`. + +#. In Git Extensions, click ``Commit`` to see the files that have been changed in your + local directory. + +#. In the window that opens, stage the files to commit, add a commit message, and then + click ``Commit``. + +#. Do a pull from the GitHub repository to your local directory to ensure that there + are no conflicts with what is in your branch. If there are conflicts, resolve + them. + +#. Do a push of your branch to the GitHub repsitory. + +#. Complete the PR as described in :ref:`complete_pr`. + +.. _complete_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 `_. + + 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. + + 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. diff --git a/doc/source/guidelines/index.rst b/doc/source/guidelines/index.rst index 51030f4b2..a7dfd0a03 100644 --- a/doc/source/guidelines/index.rst +++ b/doc/source/guidelines/index.rst @@ -14,6 +14,7 @@ Table of Contents :maxdepth: 2 dev_practices + doc_practices app_interface_abstraction data_transfer_and_representation logging