doc/edits to fix generation of ToC for PDF of doc (#47)

PipKat · web-flow · commit cf531e475a83 · 2022-02-14T19:43:12.000+01:00
diff --git a/README.rst b/README.rst
@@ -1,3 +1,4 @@
+#########################
 PyAnsys Developer's Guide
 #########################
 
@@ -9,48 +10,7 @@ This guide serves as the central document for:
 - Anyone who is interested in learning more about the PyAnsys 
   project and libraries
 
-
 Web-based documentation can be found in `PyAnsys Developer's Guide <https://dev.docs.pyansys.com>`_.
 
-
 A PDF version of this guide can be found in the release notes in `Releases
 <https://github.com/pyansys/about/releases>`_.
-
-
-Generate Documentation
-----------------------
-To generate this documentation locally, you can install the requirements into
-your Python environment with:
-
-.. code::
-
-   pip install -r requirements_docs.txt
-
-or if you want to configure and activate a Python virtual environment with the
-required packages:
-
-.. code::
-    
-   configure_venv
-
-Then, depending on your operating system, generate the documentation.
-
-On Windows, generate with:
-
-.. code::
-
-   cd doc
-   make.bat html
-
-On Linux, generate with:
-
-.. code::
-
-  make -C doc html
-
-
-Contributing
-------------
-To contribute to this guide, either create a branch and
-contribute directly or fork and submit a pull request.  All 
-pull requests are reviewed before they can be merged.
diff --git a/doc/source/guidelines/doc_practices.rst b/doc/source/guidelines/doc_practices.rst
@@ -344,9 +344,9 @@ Installing Build Requirements
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
 You can build documentation for the `dev_guide <https://github.com/pyansys/dev-guide>`_
 and `pyansys-sphinx-theme <https://github.com/pyansys/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.
+installing a PyAnsys library in development mode. However, for many other PyAnsys libraries, when
+you push changes that you have made in a local branch to the library's GitHub repository, CI checks
+typically require that the full library is installed.
 
 #. In Anaconda Powershell, navigate to the base directory in the library's cloned repository.
 
@@ -362,22 +362,33 @@ that the full library is installed.
 
     pip install -r requirements_docs.txt
 
-#. If you are running on a Linux/Mac OS, to build the documentation, enter:
+
+.. note::
+   If you want to configure and activate a Python virtual environment with the
+   required packages, you can use ``configure_venv``.
+
+Once build requirements are installed, you can build HTML documentation.
+
+Building HTML Documentation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
+How you build HTML documentation depends on your operating system.
+
+#. If you are running on Linux or Mac, enter:
    
    .. code::
 
     make -C doc html
 
-#. If you are running on Windows, to build the documentation, enter two
-   commands:
+
+#. If you are running on Windows, enter two commands:
    
    .. code::
   
     cd doc
     .\make.bat html
 
 
-   As Sphinx is generating HTML output in the library's ``../doc/_build/html`` directory,
+   As Sphinx generates HTML output in the library's ``../doc/_build/html`` directory,
    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.
@@ -390,8 +401,8 @@ that the full library is installed.
    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
-   all target options, enter ``make.bat``.
+   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`.
@@ -407,13 +418,18 @@ On Windows, building a PDF is a manual process that you run locally:
 
 #. Install `MiKTeX <https://miktex.org/download>`_ for Windows, selecting the
    recommended option for installing it for only your own use.
+
 #. From the Windows Start menu, start the MiKTeX Console.
+
 #. On the Welcome page, click ``Check for updates`` and install any available
    updates.
+
 #. Install the latest version of Strawbery Perl, which enables you to build
    LaTeX files, accepting the default installation location (``C:\Strawberry\``).
+
 #. In the Command Prompt window, type ``perl-v`` to test that your installation is
-   successful.  
+   successful.
+
 #. Ensure that these Perl directory locations have been added to your ``Path``
    system environment variable:
    
diff --git a/doc/source/guidelines/index.rst b/doc/source/guidelines/index.rst
@@ -1,17 +1,15 @@
+#############################
 Guidelines and Best Practices
 #############################
-This section describes and outlines several best practices that can be
-applied to PyAnsys libaries for the purpose of creating effective and
-efficient Python libraries to interface with Ansys products and
-services. These guidelines demonstrate how applications and complex
-services expose functionalities such as logging, data transfer, and
-Application APIs.
 
-Table of Contents
------------------
+This section describes several guidelines and best practices for
+creating effective and efficient Python libraries to interface
+with Ansys products and services. Topics also demonstrate how
+applications and complex services expose functionalities such as
+logging, data transfer, and application APIs.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
 
    dev_practices
    version_support
diff --git a/doc/source/library_description/index.rst b/doc/source/library_description/index.rst
@@ -1,5 +1,7 @@
+################
 Library Overview
 ################
+
 A PyAnsys library eliminates the need to share snippets of code that
 perform actions. Users can instead create workflows consisting of 
 their own Python modules and third-party libraries. This extends 
@@ -34,29 +36,11 @@ that maps the raw API into a carefully designed, object-oriented data
 model and API.
 
 
-Template
---------
-Within the `PyAnsys Organization <https://github.com/pyansys>`_, there
-is a `template repository <https://github.com/pyansys/template>`_
-where you can `create a repository from a template`_ and create a 
-PyAnsys project that follows the guidelines specified in this developer's
-guide.
-
-The template repository contains a generalized library skeleton that includes:
-
-- Library skeleton with sample classes and methods
-- Sample documentation build including customized templates
-- Sample GitHub actions specific to PyAnsys libraries
-- Licensing, example README, and setup files
-- ``.gitignore`` and other requirements files
-
-To use this template, `create a repository from a template`_.
-
-
 .. toctree::
    :hidden:
    :maxdepth: 3
 
+   template
    library_structure
    library_names
    repo_directory_structure
diff --git a/doc/source/library_description/template.rst b/doc/source/library_description/template.rst
@@ -0,0 +1,22 @@
+################
+Library Template
+################
+
+Within the `PyAnsys Organization <https://github.com/pyansys>`_, there
+is a `template repository <https://github.com/pyansys/template>`_
+where you can `create a repository from a template`_ and create a 
+PyAnsys project that follows the guidelines specified in this developer's
+guide.
+
+The template repository contains a generalized library skeleton that includes:
+
+- Library skeleton with sample classes and methods
+- Sample documentation build including customized templates
+- Sample GitHub actions specific to PyAnsys libraries
+- Licensing, example README, and setup files
+- ``.gitignore`` and other requirements files
+
+To use this template, `create a repository from a template`_.
+
+
+.. _Create a repository from a template: https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template
diff --git a/doc/source/overview/administration.rst b/doc/source/overview/administration.rst
@@ -1,5 +1,7 @@
+######################
 Project Administration
 ######################
+
 The PyAnsys project allows you to create your own workflows and 
 interfaces to Ansys products using Ansys APIs. While using PyAnsys 
 libraries requires that the relevant Ansys products are licensed 
@@ -23,7 +25,6 @@ To view this license, see the `LICENSE <https://github.com/pyansys/dev-guide/blo
 of this repository. This file must be included in the root 
 directory of the repository of every PyAnsys library.
 
-
 Project Approval
 ================
 Exposing new Ansys technologies through the PyAnsys project is subject
@@ -54,7 +55,6 @@ Each repository is expected to follow this minimum set of standards:
 
 Release Procedures and Versioning
 =================================
-
 PyAnsys library releases are managed through both automated
 and manual review processes.
 
@@ -108,7 +108,7 @@ Release Management
 A release may be a major, minor, or patch release depending on the
 features, changes, or bug fixes to be released.
 
-See :ref:`release_procedures` for the details on release management.
+For more information, see :ref:`release_procedures`.
 
 
 Product Version Matching
diff --git a/doc/source/overview/basic.rst b/doc/source/overview/basic.rst
@@ -1,5 +1,37 @@
+############################
+PyAnsys Project Organization
+############################
+
+The PyAnsys project is hosted on GitHub at `PyAnsys
+<https://github.com/pyansys>`_. It contains several repositories with 
+Python libraries that interface with Ansys products or services. 
+To try out a library, visit one of these links:
+
+* `PyAnsys Project <https://docs.pyansys.com/>`_
+* `PyMAPDL`_
+* `PyAEDT`_
+* `DPF-Core <https://github.com/pyansys/DPF-Core>`_
+* `DPF-Post <https://github.com/pyansys/DPF-Post>`_
+* `Legacy PyMAPDL Reader <https://github.com/pyansys/pymapdl-reader>`_
+
+If you want to create, develop, or contribute to a PyAnsys library, 
+visit these links:
+
+* `PyAnsys Project Developer's Guide <https://github.com/pyansys/about>`_
+* `PyAnsys Sphinx Theme Documentation <https://github.com/pyansys/pyansys-sphinx-theme>`_
+* `gRPC Hello-world Example <https://github.com/pyansys/pyansys-helloworld>`_
+* `Material Example Data <https://github.com/pyansys/example-data>`_
+
+Using the following tools, developers generate library packages from 
+PROTO files, create coverage reports, and report on system coverage:
+
+* `pyansys-protos-generator <https://github.com/pyansys/pyansys-protos-generator>`_
+* `example-coverage <https://github.com/pyansys/example-coverage>`_
+* `system-reporting-tool <https://github.com/pyansys/system-reporting-tool>`_
+
+#################
 Quick Start Guide
-=================
+#################
 
 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
@@ -48,7 +80,8 @@ project for a particular PyAnsys library.
 
    Others like requests, RPC, COM, etc.
 
-
+.. _PyAEDT: https://github.com/pyansys/PyAEDT
+.. _PyMAPDL: https://github.com/pyansys/pymapdl
 .. _pytest-cov: https://pytest-cov.readthedocs.io/en/latest/reporting.html
 .. _pyansys/template: https://github.com/pyansys/template
 .. _Creating a repository from a template: https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template
diff --git a/doc/source/overview/contributing.rst b/doc/source/overview/contributing.rst
diff --git a/doc/source/overview/index.rst b/doc/source/overview/index.rst
