Doc Strings

All public (not _private) classes and functions must have doc strings. Most _private classes and functions should still be documented for other developers. NumPy’s style guide is the standard used for MontePy doc strings.

Mandatory Elements

1. One line descriptions.

2. Type annotations in the function signature

3. Description of all inputs.

4. Description of return values (can be skipped for None).

5. .. versionadded::/ .. versionchanged:: information for all new functions and classes. This information can be dropped with major releases.

6. Example code for showing how to use objects that implement atypical __dunders__, e.g., for __setitem__, __iter__, etc.

7. Type hints on all new or modified functions.

Note

Class __init__ arguments are documented in the class docstrings and not in __init__.

Note

MontePy is in the process of migrating to type annotations, so not all functions will have them. Eventually MontePy may use a type enforcement engine that will use these hints. See #91 for more information. If you have issues with circular imports add the import: from __future__ import annotations, this is from PEP 563.

Highly Recommended

1. A class level .. seealso: section referencing the user manuals.

2. An examples code block. These should start with a section header: “Exampes”. All code blocks should use sphinx doctest.

Note

MontePy docstrings features custom commands for linking to MCNP user manuals. These in general follow the :manual62:, :manual63:, :manual631: pattern.

The MCNP 6.2.0 manual only supports linking to a specific page, and not a section, so the argument it takes is a page number: :manual62:`123`: becomes MCNP 6.2 manual p. 123.

The MCNP 6.3 manuals do support linking to section anchors. By default the command links to a \\subsubsection, e.g., :manual63:`5.6.1` becomes: MCNP 6.3.0 manual § 5.6.1. For other sections see: doc/source/conf.py.

Example

Here is the docstrings for Cell.

class Cell(Numbered_MCNP_Object):
    """Object to represent a single MCNP cell defined in CSG.

    Examples
    ^^^^^^^^

    First the cell needs to be initialized.

    .. testcode:: python

        import montepy
        cell = montepy.Cell()

    Then a number can be set.
    By default the cell is voided:

    .. doctest:: python

        >>> cell.number = 5
        >>> print(cell.material)
        None
        >>> mat = montepy.Material()
        >>> mat.number = 20
        >>> mat.add_nuclide("1001.80c", 1.0)
        >>> cell.material = mat
        >>> # mass and atom density are different
        >>> cell.mass_density = 0.1

    Cells can be inverted with ``~`` to make a geometry definition that is a compliment of
    that cell.

    .. testcode:: python

        complement = ~cell

    See Also
    --------

    * :manual631sec:`5.2`
    * :manual63sec:`5.2`
    * :manual62:`55`


    .. versionchanged:: 1.0.0

        Added number parameter

    Parameters
    ----------
    input : Union[Input, str]
        The Input syntax object this will wrap and parse.
    number : int
        The number to set for this object.
    """

    # snip

    def __init__(
        self,
        input: InitInput = None,
        number: int = None,
    ):

Adding New Objects to the Website

The Sphinx website uses autosummary. Each class or module must be pointed to in doc/source/api/modules.rst, it is preferable to point to the classes themselves, and not the modules.