Content in RST files#

reStructuredText, a plaintext markup language, uses simple and intuitive constructs to indicate the structure of a document. You use reStructuredText (RST) files to define the hierarchy of your documentation and provide manually authored content.

This page describes the setup of RST files for PyAnsys documentation. It also describes the option for using either a RST or Markdown (MD) file as the README for the GitHub repository of a PyAnsys project.

For resources related to RST and MD files, see Style and formatting resources. To learn how RST files for PyAnsys libraries are formatted, see RST file formatting.

RST file setup#

In a repository, the doc directory contains an index.rst file that defines the overall hierarchy (major sections) of the documentation. Each referenced child directory has its own index.rst file. Its first-level heading is the name of the documentation section. Documentation for a PyAnsys client library generally has five sections:

  • Getting started

  • User guide

  • API reference

  • Examples

  • Contribute

In addition to providing the section name, the index.rst file includes the toctree directive to specify how to build and display the content for this section.

Note

A directive is a generic block of explicit markup that sets off a specific block of text. For more information, see Directives in the Sphinx documentation.

For example, here is the toctree directive in the index.rst file for this Content in RST files section:

.. toctree::
   :maxdepth: 3
   :hidden:

   rst-file-formatting
   rst-format-rules
   notices
   doc-links
   code-blocks
   images
   tables
   cards
   tab-sets
   collapsible-sections

The maxdepth attribute of the toctree directive specifies the maximum number of heading levels to show in the documentation’s right pane, labeled On this page. In this guide, the maxdepth attribute is set to 3 for all sections. The toctree directive then includes an ordered list of the RST files to show in the Section Navigation pane. The RST extensions for the files in this list are omitted.

Note

In the doc/source directory, folder and file names should use hyphens as space delimiters for search optimization of the generated HTML documentation. For example, rst-file-formatting.rst.

To see the toctree directives for the other sections in this guide, in the project’s repository, go to the doc/source directory and look at the index.rst files in the child directories for the documentation sections.

For more information on RST file setup, see reStructuredText files and Getting Started in the Sphinx documentation.

README.rst files#

Each PyAnsys repository has a README file in its root directory that explains the project and points readers to the documentation. The README file can be an RST file or a GitHub Flavored Markdown (MD) file. While RST and MD files are similar, the syntax differs. If the README file in your repository is an MD file, see GitHub Flavored Markdown Spec and Using Markdown and Liquid in GitHub Docs for syntax information.

If your README file is an RST file, you can reuse content in it in within the main index.rst file for the library’s documentation or in the index.rst file for its “Getting started” section. However, if your README file is an MD file, you cannot reuse the content in it. Thus, the disadvantages of having to use a different syntax in the MD file and the inability to reuse content in it in your documentation may influence you to use an RST file for your README file.

To reuse all content in a README.rst file in the main index.rst file for your documentation, use the include directive:

.. include:: ../../README.rst

To reuse only a portion of the content in a README.rst file, use this directive’s start-line and end-line attributes:

.. include:: ../../README.rst
   :start-line: 4
   :end-line: 72

Because using the preceding attributes necessitates having to change the line numbers if content is later added to or removed from the README.rst file, you might want to use this directive’s start-after attribute instead. It allows you to reuse content from a given point to the end of the file.

You first insert a target in the README.rst file where you want to start the reuse. For example, assume that the README.rst file has an “Overview” section where you want the reuse to begin. Before this section, insert an explicit target name like this, followed by a blank line:

.. reuse_start

In the main index.rst file for your library’s documentation, now insert an include directive with a start-after attribute that specifies this explicit target name:

.. include:: ../../README.rst
   :start-after: .. reuse_start

If your README.rst file has links to sections or pages in the library’s documentation, you must use either URLs or insert explicit targets at the bottom of the README.rst file that you can then use in this file. If your project has a central links.rst file in the doc/source directory, you might be tempted to simply use the explicit target names named defined in it in the README.rst file. However, the GitHub renderer is unaware of the links.rst file. For more information, see External links.