Fix minor doc issues (#32)

* Fix minor doc issues

* Fix use of both interpreted text role prefix and reference suffix

* Fix branch_naming`and and :ref:`branching_model

* Tried yet another approach to get past line 40

* Additional doc edits

* Update doc/source/guidelines/dev_practices.rst

Co-authored-by: Alex Kaszynski <[email protected]>

Co-authored-by: Alex Kaszynski <[email protected]>

Author: PipKat

doc/source/guidelines/dev_practices.rst

@@ -3,14 +3,14 @@
 Development Practices
 =====================
 This page explains how PyAnsys development is conducted. When
-contributing directly to PyAnsys libraries, use these general 
+contributing to a PyAnsys repository, use these general 
 coding paradigms:
 
 #. Follow the `Zen of Python <https://www.python.org/dev/peps/pep-0020/>`__.
    As silly as core Python developers are sometimes, there's much to be
    gained by following the basic guidelines listed in PEP 20. As suggested
    in these guidelines, focus on making your additions intuitive, novel,
-   and helpful for PyAnsys library users. When in doubt, use ``import this``.
+   and helpful for PyAnsys users. When in doubt, use ``import this``.
    For Ansys code quality standards, see :ref:`coding_style`.
 
 #. Document your contributions. Include a docstring for any added
@@ -31,13 +31,15 @@ coding paradigms:
 
 Contributing Through GitHub
 ---------------------------
-To submit new code to a PyAnsys Library:
+To submit new code to a PyAnsys repository:
 
 #. `Fork <https://docs.github.com/en/get-started/quickstart/fork-a-repo>`_
-   the respective library's GitHub repository and then clone
-   the forked repository to your computer. 
+   the respective GitHub repository and then clone the forked repository
+   to your computer. 
 
-#. In your local repository, create a branch. See `Branching Model <#Branching Model>`__.
+#. In your local repository, create a branch. See :ref:`branch_naming`.
+   Comprehensive information on our model for branching is availible in
+   `Branching Model <#Branching Model>`__.
 
 #. Add your new feature and commit it locally. Be sure to commit
    frequently as the ability to revert to past commits is often helpful,
@@ -54,15 +56,15 @@ Once you have tested your branch locally, create a PR and target your
 merge to ``main``. This will automatically run CI testing and verify
 that your changes will work across all supported platforms.
 
-For code verification, someone from the development team for the PyAnsys library
-will review your code to verify that it meets our standards. Once your code
-is approved, if you have write permission, you may merge the PR branch. If you
-don't have write permission, the reviewer or someone else with write permission
-will merge and delete the PR branch.
+For code verification, someone from the PyAnsys development team will review your
+code to verify that it meets our standards. Once your code is approved, if you
+have write permission, you may merge the PR branch. If you don't have write
+permission, the reviewer or someone else with write permission will merge your
+PR and then delete your PR branch.
 
 If your PR branch is a ``fix/`` branch, do not delete it because it may be necessary to
-merge your PR branch with the current release branch. See the next section for branch
-naming conventions.
+merge your PR branch with the current release branch. The next section explains our
+branch naming conventions.
 
 .. _branch_naming:
 
@@ -124,7 +126,8 @@ like this:
 
 Documentation
 -------------
-Documentation for a PyAnsys library is generated from three sources:
+The source and content for documentation varies from repository to repository. For a PyAnsys library,
+documentation is generated from three sources:
 
 - Docstrings from the library's classes, functions, and modules using
   `sphinx.ext.autodoc <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>`_.
@@ -161,21 +164,21 @@ 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 libary is accessible
-from its repository. You can access the latest development version of the
+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 the latest
-stable release of the PyAEDT documentation is
-`<https://dev.aedtdocs.pyansys.com/>`_, and the URL for the latest development 
-version of this documentation is `<https://dev.aedtdocs.pyansys.com/>`_. The
-latest development version is kept up-to-date automatically via GitHub actions.
+the URL for the latest stable release. For example, the URL for documentation of the
+latest stable release of PyAEDT is `<https://aedtdocs.pyansys.com/>`_, and
+the URL for the latest documentation for the development version of PyAEDT is
+`<https://dev.aedtdocs.pyansys.com/>`_. The latest development versions of both
+the library and its documentation are kept up-to-date automatically via GitHub actions.
 
-Building the Documentation Locally
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-You can build and verify a library's HTML documentation locally by installing
-Sphinx and other documentation build dependencies.
+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 library in development mode:
+#. Optionally install the project in development mode:
 
 .. code::
 
@@ -201,14 +204,14 @@ Otherwise, if running on Windows, build the documentation:
    cd doc
    make.bat html
 
-#. After documentation builds successfully locally, use your
-   browser to open the file ``index.html`` in ``doc/_build/html/`` 
-   to review it.
+#. 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.
 
 Continuous Integration and Continuous Delivery (CI/CD)
 ------------------------------------------------------
 
-A PyAnsys library uses continuous integration (CI) and continuous delivery (CD)
+A PyAnsys project uses continuous integration (CI) and continuous delivery (CD)
 to automate building, testing, and deployment tasks. The CI pipeline is
 deployed on both GitHub Actions and Azure Pipelines and performs the following
 tasks:
@@ -218,9 +221,11 @@ tasks:
 - Spelling and style verification
 - Documentation build
 
+.. _branching_model:
+
 Branching Model
 ---------------
-The branching model for a PyAnsys library enables rapid development of
+The branching model for a PyAnsys project enables rapid development of
 features without sacrificing stability. The model closely follows the 
 `Trunk Based Development <https://trunkbaseddevelopment.com/>`_ approach:
 
@@ -276,11 +281,10 @@ Release procedures follow for major and minor releases.
 #. After building the documentation, open the local build and examine
    the examples for any obvious issues.
 
-#. Update the version numbers in
-   ``ansys/<product>/<library>/_version.py`` and commit this file.  Push the
-   branch to GitHub and create a new PR for this release that merges
-   it to ``main``. While effort is focused on the release, development
-   to ``main`` should be limited.
+#. Update the version numbers in ``ansys/<product>/<library>/_version.py``
+   and commit this file. Push the branch to GitHub and create a new PR
+   for this release that merges it to ``main``. While effort is focused
+   on the release, development to ``main`` should be limited.
 
 #. Wait for the PyAnsys developers and community to functionally test the
    new release. Testors should locally install this branch and use it in
@@ -327,11 +331,12 @@ should not wait until a minor release. These are the steps for a patch release:
    an opportunity to validate and approve the bug fix release. Any
    additional hotfixes should be outside of this PR.
 
-#. When the PR is approved, merge it with the release branch, but not with
-   ``main`` as there is no reason to increment the version of the ``main`` branch.
+#. When the PR is approved, merge it with the release branch but not with
+   ``main`` because there is no reason to increment the version of the
+   ``main`` branch.
 
 #. Create a tag from the release branch with the applicable version number
    as described in the previous section.
 
-4. If deemed necessary, create and add release notes as described in the
+#. If deemed necessary, create and add release notes as described in the
    previous section.

doc/source/overview/basic.rst

@@ -1,41 +1,40 @@
 Quick Start Guide
 =================
 
-This is a brief overview on how to get started right away with your own PyAnsys library on the `PyAnsys GitHub Organization`_
+This is a brief overview on how to get started right away with your own PyAnsys
+repository on the `PyAnsys GitHub Organization`_. A repository is generally a
+project for a particular PyAnsys library.
+
+#. **Create the repository:** Create a repository from the
+   `pyansys/template`_.  See `Creating a repository from a template`_.
+   Be sure that the `repository visibility`_ is initially private.
+   
+#. **Rename the package:** Rename ``ansys/product/library`` to match
+   your product or library.  For example, the package name for
+   PyMAPDL is ``ansys/mapdl/core``. Do the
+   same renaming in ``setup.py``. Do this as a pull request.  In fact, only add
+   code as pull requests. Do not push to ``main``.)
+
+#. **Add source:** Add your source files to
+   ``ansys/<product>/<library>`` or create them.  Also add unit tests to 
+   ``tests/`` following the `pytest`_ convention. Be sure to maintain
+   sufficient coverage when adding your library. See `pytest-cov`_.
 
-#. **Create the Repository:** Create a new repository from the
-   `pyansys/template`_.  See
-   `Creating a repository from a template`_.  Be sure to start as a
-   private repository.
+   .. note::
+      If your tests require an active service, application, or product,
+      be sure to set up this application to run in an automated manner.
 
-#. **Rename the Package:** Rename ``ansys/product/library`` to match
-   your product or library.  For example ``ansys/mapdl/core``.  Do the
-   same in ``setup.py``.  Do this as a pull request.  In fact, only add
-   code as pull requests (don't push to main).
+#. **Update documentation:** The documentation source and content will
+   vary from repository to _repository. In ``doc/``, there are folders for
+   different types of documentation, which can include guides, examples,
+   and API. Ensure that all documentation is updated. See :ref:`api_documentation`.
 
-#. **Add Source:** Add your source files to
-   ``ansys/<product>/<library>``, or create them.  At the same time,
-   add unit tests to ``tests/`` following the `pytest`_ convention.
-   Be sure to maintain sufficient coverage when adding your library.
-   See `pytest-cov`_.
+#. **Prepare the package for release:** When you are ready to release
+   your package publicly, email `[email protected] <[email protected]>`_
+   to obtain the release checklist for obtaining official Ansys approval.
+   Once you have completed this checklist, change the `repository visibility`_
+   to public and create a release branch.
 
-   .. note::
-      If your tests require an active service,
-      application, or product, be sure to setup this application to run
-      in an automated manner.
-
-#. **Documentation:** Update documentation at ``doc/``.  There are two
-   types of docs, User-Guide and API.  Be sure that both are updated.
-   See :ref:`api_documentation`.
-
-#. **Package Release:** When ready to release your package publicly,
-   contact [email protected] to obtain the release
-   checklist in regards to official Ansys approval.  Once the
-   checklist is complete, change the `repository visibility`_,
-   create a release branch.
-
-The manner of the source and content of the documentation will vary
-from project to project.
 
 .. todo::
 

doc/source/overview/contributing.rst

@@ -10,13 +10,13 @@ our libraries powerful tools for all users. As such, we
 encourage you to submit questions, report bugs, request new
 features, contribute code, and start discussions.
 
-This page provides general information about contributing to a
-PyAnsys library. Contribution information specific to a particular
-library appears on the ``Contributing`` page in the respective
-library's documentation, including:
+This page provides general information about contributing code to a
+PyAnsys respository. Contribution information specific to a particular
+repository appears on the ``Contributing`` page in the respective
+respository's documentation, including:
 
 - Instructions for cloning the source repository from GitHub
-- URL to the library's ``Issues`` page
+- URL to the repository's ``Issues`` page
 
 Creating Issues
 ---------------
@@ -36,8 +36,9 @@ it with a comment that explains why you have done so. If you need to contact the
 PyAnsys project support team directly, email `[email protected] <[email protected]>`_.
 
 For convenience, here are URLs for ``Issues`` pages for
-Ansys product repositories:
+public Ansys repositories:
 
+- `OpenAPI Common Issues <https://github.com/pyansys/openapi-common/issues>`_
 - `PyAEDT Issues <https://github.com/pyansys/pyaedt/issues>`_
 - `PyDPF-Core Issues <https://github.com/pyansys/pydpf-core/issues>`_
 - `PyDPF-Post Issues <https://github.com/pyansys/pydpf-post/issues>`_
@@ -46,61 +47,59 @@ Ansys product repositories:
 
 Submitting Questions
 ~~~~~~~~~~~~~~~~~~~~
-For general or technical questions about a PyAnsys library, its
-applications, or software usage, create issues on the respective
-library's ``Issues`` page. This allows PyAnsys developers and
-community members with the needed expertise to collectively address
-them. It also makes their responses available to all users.
+For general or technical questions about the code in a PyAnsys repository or
+about its application or software usage, create issues on the ``Issues`` page
+of the repository. This allows PyAnsys developers and community members with
+the needed expertise to collectively address them. It also makes their responses
+available to all users.
 
 Reporting Bugs
 ~~~~~~~~~~~~~~
-If you encounter a bug or your workflow crashes while using a
-PyAnsys library, create an issue on the respective library's 
-``Issues`` page and tag it with an appropriate label so that it 
-can be promptly addressed. In describing the issue, be as descriptive
-as possible so that the issue can be reproduced. Whenever possible,
-provide a traceback, screenshots, and sample files that might help
-the community to address the issue.
+If you encounter a bug or your workflow crashes while using code in a PyAnsys
+repository, create an issue on the repository's ``Issues`` page and tag it with
+an appropriate label so that it can be promptly addressed. In describing the
+issue, be as descriptive as possible so that the issue can be reproduced.
+Whenever possible, provide a traceback, screenshots, and sample files that might
+help the community to address the issue.
 
 Requesting New Features
 ~~~~~~~~~~~~~~~~~~~~~~~
-We encourage you to submit ideas for improving PyAnsys libraries.
-To suggest a new feature, create an issue on the respective library's
-``Issues`` page and tag it with the ``Feature Request`` label. Use a 
-descriptive title and provide ample background information to help the
-community decide how the feature might be implemented. For example,
-if you would like to see a reader added for a specific file format,
-in the issue, provide a link to documentation for this file
-format and possibly some sample files and screenshots. The community
-will then use the issue thread to discuss the request and
-provide feedback on how the feature might best be implemented.
+We encourage you to submit ideas for improving the code in a PyAnsys
+repository. To suggest a new feature, create an issue on the repository's
+``Issues`` page and tag this issue with the ``Feature Request`` label.
+Use a descriptive title and provide ample background information to help the
+community decide how the feature might be implemented. For example, if you
+would like to see a reader added for a specific file format, in the issue,
+provide a link to documentation for this file format and possibly some sample
+files and screenshots. The community will then use the issue thread to discuss
+the request and provide feedback on how the feature might best be implemented.
 
 Contributing New Code
 ---------------------
 When you are ready to start contributing code, see:
 
-- :ref:`development_practices` for information on how development is
-  conducted in PyAnsys repositories
+- :ref:`development_practices` for information on how PyAnsys development is
+  conducted
 - :ref:`best_practices` for information on how to style and format your
   code to adhere to PyAnsys standards
 
 Starting Discussions
 --------------------
 For general questions about development practices, you should create discussions
-rather than issues. The repository for each PyAnsys library has its own
-``Discussions`` page. For example, to ask a question about a PyMAPDL development
-practice, you would create a discussion on this library's `Discussions <https://github.com/pyansys/pymapdl/discussions>`_
+rather than issues. Each PyAnsys repository has its own ``Discussions`` page.
+For example, to ask a question about a PyMAPDL development practice, you would
+create a discussion on the `PyMAPDL Discussions <https://github.com/pyansys/pymapdl/discussions>`_
 page. It is possible for discussions to lead to the creation of issues.
 
 .. note::
-    Because the ``Discussions`` page is still a beta feature on GitHub, usage
+    Because the ``Discussions`` page is still a GitHub beta feature, usage
     may change in the future.
 
 Cloning the Source Repository
 -----------------------------
 As mentioned earlier, specific instructions for cloning a source
 repository from GitHub appear on the ``Contributing`` page in the
-respective library's documentation. In the following code for cloning and
+respective repository's documentation. In the following code for cloning and
 installing the latest version of a PyAnsys repository, ``<pyansy-repository>``
 is a placeholder for the name of the repository.
 
@@ -119,7 +118,7 @@ you would run the following:
     cd pymapdl
     pip install -e .
 
-If you want to eventually push a contribution to the official
+If you want to eventually push a contribution to a
 PyAnsys repository, consider creating a `fork <https://docs.github.com/en/get-started/quickstart/fork-a-repo>`_
 of the repository. For information on how to contribute through
 GitHub, see :ref:`development_practices`, paying particular attention to :ref:`branch_naming`
@@ -128,8 +127,8 @@ when you are ready to create a pull request.
 Licensing
 ---------
 All contributed code will be licensed under the MIT License. For more information, see
-:ref:`license_file`. The ``LICENSE`` file with the MIT License must be included in
-the root directory of the repository for a PyAnsys library.
+:ref:`license_file`. The ``LICENSE`` file containing the MIT License must be included in
+the root directory of a PyAnsys repository.
 
 If you did not write the code that you are contributing yourself, it is your
 responsibility to ensure that the existing license for this code is compatible and