Template Tutorial (STEAL ME)

Tutorial B. Author¹, and Darrin M. York¹

¹Laboratory for Biomolecular Simulation Research, Institute for Quantitative Biomedicine and Department of Chemistry and Chemical Biology, Rutgers University, Piscataway, NJ 08854, USA

Learning objectives

Understand the basic structure of a tutorial in this repository.
Learn how to navigate through the tutorials.

Relevant literature

Catalytic mechanism and pH dependence of a methyltransferase ribozyme (MTR1) from computational enzymology[McCarthy, Nucleic. Acids Res. (2023) 51, 4508-4518]

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.

Main Heading
===========

Subheading
----------

Sub-subheading
~~~~~~~~~~~~~~

Lists: Use - or * for bullet points, and numbers for ordered lists.
- 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.
`Inline code example <https://www.rutgers.edu.edu>`_ :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, Template Tutorial Repository, links to another documentation file within the same project, allowing you to navigate easily between related topics.

The third, 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, 1.2 Using Sphinx for Documentation, 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:: python def my_function(): print("Hello, World!")
This will render the code block with proper formatting, making it easy to read and understand.
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:
.. 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:
.. warning:: A warning will show up like this.
Warning

A warning will show up like this.

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:

pip install sphinx

Install the sphinx RTD theme:
pip install sphinx_rtd_theme
Go to the docs directory.
cd Tutorials/docs
Make the HTML documentation
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

numpy

This will create a link to the NumPy module, allowing users to easily navigate to its documentation. As is the case for numpy, which links to the NumPy module documentation.

Or you can link to a specific function within a module:

: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 numpy.array().

Lastly, if you add the path to the library to conf.py in the docs directory as:

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.

.. 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:

.. autofunction:: numpy.array

numpy.array()

array(object, dtype=None, *, copy=True, order=’K’, subok=False, ndmin=0,: like=None)

Create an array.

Parameters:

object (array_like) – An array, any object exposing the array interface, an object whose __array__ method returns an array, or any (nested) sequence. If object is a scalar, a 0-dimensional array containing object is returned.
dtype (data-type, optional) – The desired data-type for the array. If not given, NumPy will try to use a default dtype that can represent the values (by applying promotion rules when necessary.)
copy (bool, optional) – If true (default), then the object is copied. Otherwise, a copy will only be made if __array__ returns a copy, if obj is a nested sequence, or if a copy is needed to satisfy any of the other requirements (dtype, order, etc.).

order ({'K', 'A', 'C', 'F'}, optional) –

Specify the memory layout of the array. If object is not an array, the newly created array will be in C order (row major) unless ‘F’ is specified, in which case it will be in Fortran order (column major). If object is an array the following holds.

order	no copy	copy=True
’K’	unchanged	F & C order preserved, otherwise most similar order
’A’	unchanged	F order if input is F and not C, otherwise C order
’C’	C order	C order
’F’	F order	F order

When copy=False and a copy is made for other reasons, the result is the same as if copy=True, with some exceptions for ‘A’, see the Notes section. The default order is ‘K’.

subok (bool, optional) – If True, then sub-classes will be passed-through, otherwise the returned array will be forced to be a base-class array (default).
ndmin (int, optional) – Specifies the minimum number of dimensions that the resulting array should have. Ones will be prepended to the shape as needed to meet this requirement.
like (array_like, optional) –
Reference object to allow the creation of arrays which are not NumPy arrays. If an array-like passed in as like supports the __array_function__ protocol, the result will be defined by it. In this case, it ensures the creation of an array object compatible with that passed in via this argument.

Added in version 1.20.0.

Returns:

out – An array object satisfying the specified requirements.

Return type:

ndarray

Template Tutorial (STEAL ME)

Learning objectives

Relevant literature

Tutorial

1.1 The RST File Format

1.2 Using Sphinx for Documentation

1.3 Linking to Other Packages

1.3.1 Example of Linking to an External Module

1.1 The RST File Format 

1.2 Using Sphinx for Documentation 

1.3 Linking to Other Packages 

1.3.1 Example of Linking to an External Module 