RiboKit : Doc Standards

Internal Guideline on Writing Standards

Text Format


Markdown (Jekyll / Tutorial)

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

Here are some best practices:

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.

"""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 }``.
"""
"""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**.
"""
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))``.
"""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.

Built with Jekyll using a RiboKit Theme . Hosted on GitHub Pages.