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 file 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/source directory contains an index.rst file that defines the overall hierarchy (major sections) of the documentation. The child directory for each section has its own index file.

Note

While most PyAnsys libraries use index.rst as the name for a section’s index file, to optimize web searches of the generated HTML documentation, this file should have a short and descriptive name that contains keywords and uses hyphens (-) to separate words. All directory names should also use hyphens to separate words. For more information, see Optimize web searches.

In the index file for a documentation section, the first-level heading is the name of the section. Documentation for a PyAnsys client library generally has five sections with these headings:

  • Getting started

  • User guide

  • API reference

  • Examples

  • Contribute

After the section heading and any additional content, the index file includes the toctree directive to specify the pages that this section is to display.

The toctree directive for this Content in RST files page (doc/_build/html/content-writing/rst-files-writers/index.html), looks like this:

.. 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. The maxdepth attribute is set to 3 for all sections in this guide.

The toctree directive also includes an ordered list of the RST files to show in the documentation’s left pane, labeled Section Navigation. You omit the RST extensions from this list of files.

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 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 your README file is an RST file, see RST file formatting for syntax information. If your README file is an MD file, see GitHub Flavored Markdown Spec and Using Markdown and Liquid in GitHub Docs for syntax information.

You can reuse content in a README.rst file in the main index.rst file for your documentation or in the index file for its “Getting started” section. However, you cannot reuse content in a README.md file. 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 might influence you to use a README.rst 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 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 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.