Text Format

Markdown (Jekyll / Tutorial)

A simple guide on how to use Markdown syntax is here.

Here are some best practices:

Only <h1> and <h2> level headers are registered to the side navbar by Jekyll.
Always use syntax highlighting for code blocks.
Use blockquotes > for advanced tips and explanations.
Always separate sections with <hr/>.
URL Links are case sensitive!

An example of tutorial made by Markdown is hitrace, see here.

Docstring (Python / Sphinx Docs)

The .html files made by Sphinx should be using the RiboKit Theme. Please see more details on configurations here: Sphinx Integration.

For basic Python docstring standards, see PEP 257. When using sphinxcontrib-napoleon, see this example and module for Google Style writing.

The docstring is based on reStructuredText, see tutorials here and here.

To color label the “Parameters” and “Attributes”, use : for separation and double ` for type (<code>) label. For example:

"""Result of a ``primerize.Primerize_1D.design()`` run.

Args:
    init_dict: A ``dict`` with the following keys:

    sequence: ``str``: Sequence of assembly design.
    name: ``str``: Construct prefix/name.
    is_success: ``bool``: Flag for whether ``primerize.Primerize_1D.design()`` run successfully found a solution.
    primer_set: ``list(str)``: List of primers for assembly.
    params: ``dict``: Dictionary of parameters used for this result.
    data: ``dict``: Dictionary of result data.

Attributes:
    sequence: ``str``: Sequence of assembly design.
    name: ``str``: Construct prefix/name.
    is_success: ``bool``: Flag for whether a solution is found.
    primer_set: ``list(str)``: Strings of solution primers.
    _params: Input parameters, in format of ``dict: { 'MIN_TM': float, 'NUM_PRIMERS': int, 'MIN_LENGTH': int, 'MAX_LENGTH': int, 'N_BP': int, 'COL_SIZE': int, 'WARN_CUTOFF': int }``.
    _data: Data of assembly solution, in format of ``dict: { 'misprime_score': [str, str], 'warnings': list(list(int)), 'assembly': primerize.util.Assembly }``.
"""

It is recommended to use double ` around values and class instances. Use ** around arguments for color matching:

"""Get result parameters.

Args:
    key: ``str``: Keyword of parameter. Valid keywords are ``'MIN_TM'``, ``'NUM_PRIMERS'``, ``'MIN_LENGTH'``, ``'MAX_LENGTH'``, ``'COL_SIZE'``, ``'WARN_CUTOFF'``, ``'WARNING'``, ``'PRIMER'``, ``'MISPRIME'``; case insensitive.

Returns:
    value of specified **key**.

Raises:
    AttributeError: For illegal **key**.
"""

Exception classes will be colored red.
When you need a block, end the line with :::

Attributes:
    ...
    _data: Data of assembly solution, in format of ::

            dict: {
                'constructs': primerize.util.Construct_List,
                'plates': list(list(primerize.util.Plate_96Well)),
                'assembly': primerize.util.Assembly,
                'illustration': { 'labels': list(str), 'fragments': list(str), 'lines': tuple(str) }
            }

        For ``primerize.Primerize_2D.design()`` results, it also has ``'bps': list(tuple(int, int))``.

For Optional arguments, italicize with `(Optional)`:

"""Print result in rich-text.

Args:
    ref_primer: ``list(str)``: `(Optional)` List of Wild-type **primer_set** for highlighting. If nonspecified, highlighting is disabled.

Returns: 
    ``str``
"""

An example of Python documentation made by Sphinx is primerize, see here.