From b4b2cbfef6c314f7336b8308b8b388e04277d833 Mon Sep 17 00:00:00 2001 From: Kathy Pippert Date: Mon, 14 Feb 2022 13:24:15 -0500 Subject: [PATCH] doc/edits to fix generation of ToC for PDF of doc --- README.rst | 42 +-------------------- doc/source/guidelines/doc_practices.rst | 36 +++++++++++++----- doc/source/guidelines/index.rst | 16 ++++---- doc/source/library_description/index.rst | 22 ++--------- doc/source/library_description/template.rst | 22 +++++++++++ doc/source/overview/administration.rst | 6 +-- doc/source/overview/basic.rst | 37 +++++++++++++++++- doc/source/overview/contributing.rst | 27 ++++++++----- doc/source/overview/index.rst | 32 +--------------- 9 files changed, 116 insertions(+), 124 deletions(-) create mode 100644 doc/source/library_description/template.rst diff --git a/README.rst b/README.rst index 516df8a8c..9d6635747 100644 --- 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 `_. - A PDF version of this guide can be found in the release notes in `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 index 1367c47eb..319bace1f 100644 --- 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 `_ 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. +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,14 +362,25 @@ 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:: @@ -377,7 +388,7 @@ that the full library is installed. .\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 `_ 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 index 7f171c51d..59e9aabbc 100644 --- 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 index c658b4a4b..f7c6ce95b 100644 --- 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 `_, there -is a `template repository `_ -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 new file mode 100644 index 000000000..402a53f64 --- /dev/null +++ b/doc/source/library_description/template.rst @@ -0,0 +1,22 @@ +################ +Library Template +################ + +Within the `PyAnsys Organization `_, there +is a `template repository `_ +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 index 421e766a6..d6afd25ef 100644 --- 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 `_. 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 `_ +* `PyMAPDL`_ +* `PyAEDT`_ +* `DPF-Core `_ +* `DPF-Post `_ +* `Legacy PyMAPDL Reader `_ + +If you want to create, develop, or contribute to a PyAnsys library, +visit these links: + +* `PyAnsys Project Developer's Guide `_ +* `PyAnsys Sphinx Theme Documentation `_ +* `gRPC Hello-world Example `_ +* `Material Example Data `_ + +Using the following tools, developers generate library packages from +PROTO files, create coverage reports, and report on system coverage: + +* `pyansys-protos-generator `_ +* `example-coverage `_ +* `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 index f74d95ccf..fb2126c11 100644 --- a/doc/source/overview/contributing.rst +++ b/doc/source/overview/contributing.rst @@ -1,6 +1,6 @@ -============ +############ Contributing -============ +############ Ansys welcomes all PyAnsys code contributions and wants you to understand how to contribute. While we maintain PyAnsys libraries @@ -18,8 +18,9 @@ respository's documentation, including: - Instructions for cloning the source repository from GitHub - URL to the repository's ``Issues`` page + Creating Issues ---------------- +=============== You create issues to submit questions, report bugs, and request new features. When you create an issue, ensure that you provide sufficient context, such as application versions and reproduction steps. Also use @@ -45,8 +46,9 @@ public Ansys repositories: - `PyMAPDL Issues `_ - `PyMAPDL-Reader Issues `_ + Submitting Questions -~~~~~~~~~~~~~~~~~~~~ +-------------------- 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 @@ -54,7 +56,7 @@ 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 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 @@ -63,7 +65,7 @@ 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 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. @@ -75,7 +77,7 @@ 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 PyAnsys development is @@ -83,8 +85,11 @@ When you are ready to start contributing code, see: - :ref:`best_practices` for information on how to style and format your code to adhere to PyAnsys standards + +All pull requests are reviwed before they can be merged. + Starting Discussions --------------------- +==================== For general questions about development practices, you should create 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 @@ -96,7 +101,7 @@ page. It is possible for discussions to lead to the creation of issues. 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 repository's documentation. In the following code for cloning and @@ -109,6 +114,7 @@ is a placeholder for the name of the repository. cd pip install -e . + For example, to clone and install the latest version of PyMAPDL, you would run the following: @@ -118,6 +124,7 @@ you would run the following: cd pymapdl pip install -e . + If you want to eventually push a contribution to a PyAnsys repository, consider creating a `fork `_ of the repository. For information on how to contribute through @@ -125,7 +132,7 @@ GitHub, see :ref:`development_practices`, paying particular attention to :ref:`b 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 containing the MIT License must be included in the root directory of a PyAnsys repository. diff --git a/doc/source/overview/index.rst b/doc/source/overview/index.rst index d2339f110..5af2725e0 100644 --- a/doc/source/overview/index.rst +++ b/doc/source/overview/index.rst @@ -1,3 +1,4 @@ +######## Overview ######## @@ -31,36 +32,7 @@ ecosystem. Examples include: .. note:: If you are new to GitHub, we suggest that you visit `The ReadMe Project `_. It is a dedicated platform for highlighting the best from the open source software community. - Monthly newletters provide feature articles, developer stories, guides, and podcasts. - -Project Organization -~~~~~~~~~~~~~~~~~~~~ -The PyAnsys project is hosted on GitHub at `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 `_ -* `PyMAPDL`_ -* `PyAEDT`_ -* `DPF-Core `_ -* `DPF-Post `_ -* `Legacy PyMAPDL Reader `_ - -If you want to create, develop, or contribute to a PyAnsys library, -visit these links: - -* `PyAnsys Project Developer's Guide `_ -* `PyAnsys Sphinx Theme Documentation `_ -* `gRPC Hello-world Example `_ -* `Material Example Data `_ - -Using the following tools, developers can generate library packages from -PROTO files, create coverage reports, and report on system coverage: - -* `pyansys-protos-generator `_ -* `example-coverage `_ -* `system-reporting-tool `_ + Each monthly newletter provides links to feature articles, developer stories, guides, and podcasts. .. toctree:: :hidden: