Tiny Docs

Lightweight autodoc for Python
Creates an entire documentation into a single Markdown file
Perfect for creating READMEs

Are you in need of a simple and efficient solution for documenting your Python code, without the hassle of setting up and maintaining a full-fledged documentation website like readthedocs? Do you want something that can quickly and easily be integrated into GitHub, allowing your team to quickly access the documentation for a few classes and helper functions? Look no further!

Tinydocs is right for you!

readthedocs automatically generates the documentation of your .py files in a small elegant way that fits in a simple README.md. Check out the example function below or the example directory.

Contents

• Installation
• Example
• Syntax
• Basic Usage
• Github Workflow

Installation

Best way to install tinydocs is through pip:

pip install tinydocs

Example

The following is the documentation generated for an example function. You can find how tinydocs handles and entire directory by checking the example directory.

Function

module.function(var1, var2, long_var_name=None, *args)

Warning Deprecation: function will be removed in version 2.0.0, it is replaced by better_function because the new one is blazingly fast.

This is an example documentation. Several sentences providing an extended description. Refer to variables using back-ticks, e.g. var. Look at this really big equation that I took from ¹

$$( \sum_{k=1}^n a_k b_k )^2 \leq ( \sum_{k=1}^n a_k^2 ) ( \sum_{k=1}^n b_k^2 )$$

 Parameters

• var1: array_like
   Array_like means all those objects -- lists, nested lists, etc. -- that can be converted to an array. We can also refer to variables like `var1`.
• var2: int
   The type above can either refer to an actual Python type (e.g. ``int``), or describe the type of the variable in more detail, e.g. ``(N,) ndarray`` or ``array_like``.
• long_var_name: {'hi', 'ho'}, optional
   Choices in brackets, default first when optional.
• *args: iterable
   Other arguments.

 Returns

• var3: int
   Returns `var3` which is of type ``int``.

 Examples

These are written in doctest format, and should illustrate how to use the function.

>>> a = [1, 2, 3]
>>> b = deprecated_function(a)
>>> print(b)
[4,5,6]

Syntax

Currently tinydocs only supports NumpyDoc syntax. This might change in the future. For a detailed guide check out numpy's style guidelines you can also check-out the example directory of this project.

Here is the docstring that generates the documentation on the example above, taken mostly from numpydoc's example.

def function(var1, var2, long_var_name=None, *args):
    """This is an example documentation.

    Several sentences providing an extended description. Refer to
    variables using back-ticks, e.g. `var`.

    Parameters
    ----------
    var1 : array_like
        Array_like means all those objects -- lists, nested lists, etc. --
        that can be converted to an array.  We can also refer to
        variables like `var1`.
    var2 : int
        The type above can either refer to an actual Python type
        (e.g. ``int``), or describe the type of the variable in more
        detail, e.g. ``(N,) ndarray`` or ``array_like``.
    long_var_name : {'hi', 'ho'}, optional
        Choices in brackets, default first when optional.
    *args : iterable
        Other arguments.

    Returns
    -------
    var3 : int
        Returns `var3` which is of type ``int``.

    Notes
    -----
    Look at this really big equation that I took from [1]_

    $$( \sum_{k=1}^n a_k b_k )^2 \leq ( \sum_{k=1}^n a_k^2 ) ( \sum_{k=1}^n b_k^2 )$$

    Warnings
    --------
    Deprecation Warning: `deprecated_function` will be removed in version 2.0.0, it is
     replaced by `better_function` because the new one is blazingly fast.

    References
    ----------
    .. [1] Trager, Scott. "The Earth's atmosphere: seeing, background, absorption &
    scattering" (PDF). S.C. Trager. Retrieved 31 May 2022

    Examples
    --------
    These are written in doctest format, and should illustrate how to
    use the function.

    >>> a = [1, 2, 3]
    >>> b = deprecated_function(a)
    >>> print(b)
    [4,5,6]
    """
    pass

Basic Usage

tinydocs can be run directly from the command line using:

tinydocs <options>

Note By design --tinydocs only looks at .py files and skips over hidden directories and will ignore any opbject (files, functions or methods) that start with _(underscore).

• --dir: Directory to document. Defaults to working directory.
• --output: Output path and name of documentation file. Defaults to --dir/TINYDOCS.md when not supplied.
• --exclude-dirs: List of directories to exclude entirely from the documentation.
• --exclude-files: List of files to exclude individually from the documentation.
• --help: Help will always be given to those who ask for it.

Github Workflow

tinydocs incorporates very well with automatic deployment allowing you to update your documentation on every push. Here's an example workflow on .github/workflows/tinydocs.yaml:

name: Update TINYDOCS.md

on:
  push:
    branches:
      - "*"

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Setup Python
        uses: actions/setup-python@v2
        with:
          python-version: 3.10

      - name: Install tinydocs
        run: pip install tinydocs

      - name: Run tinydocs
        run: tinydocs

      - name: Commit and push TINYDOCS.md
        run: |
          git config --local user.email "[email protected]"
          git config --local user.name "GitHub Actions"
          git add TINYDOCS.md
          git commit -m "Update TINYDOCS.md"
          git push

Footnotes

1. Trager, Scott. "The Earth's atmosphere: seeing, background, absorption & scattering" (PDF). S.C. Trager. Retrieved 31 May 2022 ↩