Template Tutorial (STEAL ME) ============================ | Tutorial B. Author\ :sup:`1`, and Darrin M. York\ :sup:`1` | :sup:`1`\ Laboratory for Biomolecular Simulation Research, Institute for Quantitative Biomedicine and Department of Chemistry and Chemical Biology, Rutgers University, Piscataway, NJ 08854, USA Learning objectives ------------------- .. start-learning-objectives - Understand the basic structure of a tutorial in this repository. - Learn how to navigate through the tutorials. .. end-learning-objectives Relevant literature ------------------- - `Catalytic mechanism and pH dependence of a methyltransferase ribozyme (MTR1) from computational enzymology[McCarthy, Nucleic. Acids Res. (2023) 51, 4508-4518] `_ Tutorial -------- .. contents:: :local: :depth: 4 .. start-tutorial 1.1 The RST File Format ~~~~~~~~~~~~~~~~~~~~~~~ The RST (reStructuredText) file format is a lightweight markup language used for writing documentation. It is easy to read and write, making it ideal for creating tutorials. Here are some key features: - **Headings**: Use `=` for main headings and `-` for subheadings, and `~` for sub-subheadings. .. code-block:: rst Main Heading =========== Subheading ---------- Sub-subheading ~~~~~~~~~~~~~~ - **Lists**: Use `-` or `*` for bullet points, and numbers for ordered lists. .. code-block:: rst - Bullet point 1 - Bullet point 2 - Sub-bullet point 1. First item 2. Second item Which produces the output: - Bullet point 1 - Bullet point 2 - Sub-bullet point 1. First item 2. Second item - **Links**: Use backticks for inline code and `:doc:` for linking to other documentation files. .. code-block:: rst `Inline code example `_ :doc:`Template Tutorial Repository <..//splash_page>` :func:`numpy.array` :ref:`rstfiles` These are all references to other pieces of information. The first links to another website, and it provides useful resources for further reading, for instance as: `Inline code example `_ The second, :doc:`Template Tutorial Repository <../internal_guides>`, links to another documentation file within the same project, allowing you to navigate easily between related topics. The third, :func:`numpy.array`, is a reference to a specific function in the NumPy library, which is useful for users who want to learn more about that function. The fourth, :ref:`rstfiles`, is a reference to a specific section within the same document, allowing for easy navigation to that section. In this case, we linked it to this section. - **Code Blocks**: Use `::` at the end of a line to indicate that the following lines are code blocks. We've been using a lot of these already, but .. code-block:: rst .. code-block:: python def my_function(): print("Hello, World!") This will render the code block with proper formatting, making it easy to read and understand. .. code-block:: python def my_function(): print("Hello, World!") - **Directives**: Use `..` followed by the directive name for special formatting, such as `.. note::` for notes or `.. warning::` for warnings. The code below shows how to write a note: .. code-block:: rst .. note:: A note will show up like this. .. note:: A note will show up like this. The code below shows how to write a warning: .. code-block:: rst .. warning:: A warning will show up like this. .. warning:: A warning will show up like this. .. _rstfiles: 1.2 Using Sphinx for Documentation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Sphinx is a powerful documentation generator that converts RST files into HTML, PDF and other formats. To use Sphinx, follow these steps: 1. Install Sphinx using pip: .. code-block:: bash pip install sphinx 2. Install the sphinx RTD theme: .. code-block:: bash pip install sphinx_rtd_theme 3. Go to the docs directory. .. code-block:: bash cd Tutorials/docs 4. Make the HTML documentation .. code-block:: bash make html Sphinx works through a configuration file called `conf.py`, which is located in the `docs` directory. This file contains settings for the documentation, such as the theme, extensions, and other options. Each page generated roughly corresponds to a `.rst` file in the `docs` directory. You can create new `.rst` files for each tutorial or topic you want to document. 1.3 Linking to Other Packages ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To link to other packages or modules, you can use the `:mod:` directive for modules or `:func:` for functions. This allows you to reference external libraries or functions within your documentation. For example, to link to the NumPy library, you can use: .. code-block:: rst :mod:`numpy` This will create a link to the NumPy module, allowing users to easily navigate to its documentation. As is the case for :mod:`numpy`, which links to the NumPy module documentation. Or you can link to a specific function within a module: .. code-block:: rst :func:`numpy.array` This will create a link to the `array` function in the NumPy module, providing users with quick access to its documentation, as is the case for :func:`numpy.array`. Lastly, if you add the path to the library to `conf.py` in the docs directory as: .. code-block:: python import sys sys.path.insert(0, '/path/to/external/module') Then you can use the `.. autoclass::` directives and `.. autofunction::` directives to automatically generate documentation for classes and functions in that module. .. code-block:: rst .. autofunction:: numpy.array 1.3.1 Example of Linking to an External Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This section provides an example of how to link to an external module using the `.. autofunction::` directive. You can use the following syntax to automatically document the `numpy.array` function: .. code-block:: rst .. autofunction:: numpy.array .. autofunction:: numpy.array .. end-tutorial