61A Documentation

This app generates documentation for all 61A apps. If you need any help or have questions at any point during the process, please message {{ docs_in_charge }}!

Setup

1. Clone the repo and switch into the docs directory.
2. Create a new branch for your project using git checkout -b docs/app-name, where app-name is the name of the app you're documenting (use hyphens if the name is multiple words). If someone has already created this branch, omit the -b flag.
3. Set up the Python environment using python3 -m venv env and env/bin/pip install -r requirements.txt, or simply sicp venv if you have sicp installed.
4. Run the Sphinx autobuilder using env/bin/sphinx-autobuild -b dirhtml .. _build
5. Visit http://localhost:8000 to see the docs.

Alternatively, to compile all docs once, run env/bin/sphinx-build -b dirhtml .. _build. This will generate an output folder _build containing the compiled documentation. Useful for when you don't want to run the file watcher.

Writing Documentation

To write documentation for an app, we use a combination of reStructuredText and MyST. MyST allows us to write Sphinx documentation in a markdown equivalent of reStructuredText. The documentation for MyST should help you write the index and README files, but we'll cover some examples and tips below anyway. The documentation for reStructuredText will help you write the inline Python documentation.

Text Editor Setup

First thing you should do is set up your text editor's vertical ruler to let you know when you're hitting an 80-character limit (this is a standard, but not a rule). In Visual Studio Code, this can be achieved by adding the following to your settings.json:

"editor.rulers": [
    {
        "column": 80,
        "color": "#555"
    },
]

Creating the README

We will use [MyST](https://myst-parser.readthedocs.io/en/latest/) for the
README.

Then, for whichever app you want to document, create a README.md under the directory for that app, and set it up like so:

# App Name

A brief description of what the app is meant to do.

## Setup

Include some steps to tell people how to develop this app locally.

## Other Sections

Include details that could help people develop or use the app.

Creating the Index

We will use [MyST](https://myst-parser.readthedocs.io/en/latest/) for the
index.

In order to place this app on the navbar, create an index.md under the same directory, and set it up like so:

```{include} README.md
```

## Code Segment 1

```{eval-rst}
.. automodule:: app_directory.module_name
    :members:
```

Where app_directory.module_name is the path to the file you're including, such as common.db.

Code segments like the one at the end of the example will auto-include the code documentation for the various components of the app.

Documenting Code

We will use
[reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html)
for inline Python documentation.

To document a method in a Python file, format it like so:

def function(param1: str, param2: int = 2):
    """Description of the function.

    Can span multiple lines or paragraphs, if needed!

    :param param1: one line about the first parameter
    :type param1: str
    :param param2: one line about the second parameter
    :type param2: int

    :return: one line about the return value (including type)
    """
    # function body is here

Where str and int should be replaced with the actual type of the parameter.

The type annotations go in two places: the function dignature, as well as the
body of the docstring.

This will result in the following rendered documentation:

.. py:function:: function(param1: str, param2: int = 2)

   Description of the function.

   Can span multiple lines or paragraphs, if needed!

   :param param1: one line about the first parameter
   :type param1: str
   :param param2: one line about the second parameter
   :type param2: int

   :return: one line about the return value (including type)

Documenting rpc Methods

You do not have to write documentation for methods that are bound to RPC. For example, if you're documenting howamidoing, when you get to upload_grades, you can simply write the following (see emphasized line):

.. code-block:: python
    :emphasize-lines: 4

    @rpc_upload_grades.bind(app)
    @only("grade-display", allow_staging=True)
    def upload_grades(data: str):
        """See :func:`~common.rpc.howamidoing.upload_grades`."""
        with transaction_db() as db:
            set_grades(data, get_course(), db)

Linking to Other Documentation

If you mention another function, method, or class, please include a link to the documentation for such. If this is in a MyST file, you can do this as follows:

{func}`common.shell_utils.sh`
{meth}`common.hash_utils.HashState.update`
{class}`~subprocess.Popen`

This will appear as {func}common.shell_utils.sh, {meth}common.hash_utils.HashState.update, and {class}~subprocess.Popen.

If this is in a Python file (using rST), you can do this as follows:

:func:`common.shell_utils.sh`
:meth:`~common.hash_utils.HashState.update`
:class:`subprocess.Popen`

This will appear as {func}common.shell_utils.sh, {meth}~common.hash_utils.HashState.update, and {class}subprocess.Popen.

Per the examples above, if you insert a `~` before the path to the
documentation, Sphinx will render the link using only the name of the object
itself, and will drop the path itself. This is desirable for cleanliness, so
use this whenever linking to a document.

If you want to refer to something that is documented outside of this project, the Python docs, and the Flask docs, message {{ docs_in_charge }} with what you're trying to document, as well as a link to the documentation for the relevant project. He will then add it to intersphinx_mapping dictionary in the configuration, so that you can link to it as you would anything else. As an example, to link to Flask's redirect function, you can use {func}`~flask.redirect` . This will render as {func}~flask.redirect.

Full Example

Sample README

Here's what the common README file looks like:

.. literalinclude:: ../common/README.md
    :language: markdown

Sample Index

Here's what the common index file looks like:

.. literalinclude:: ../common/index.md

Sample Code Documentation

Here's what the {func}common.db.connect_db docs look like:

.. literalinclude:: ../common/db.py
    :pyobject: connect_db

Here's what the {func}common.shell_utils.sh docs look like:

.. literalinclude:: ../common/shell_utils.py
    :pyobject: sh