Skip to content

Documentation for MMMAudio Repo

This repo uses mkdocs to render code documentation files from Google-style docstrings in Python and Mojo files.

Dependencies

See root/requirements-docs.txt.

What the doc_generation directory contains:

examples/: An example Python and Mojo file for how to put the in-source-file documentation into the respective language files. These shouldn't be modified, just use as a reference / style guide.

static_docs/: This directory contains any documentation files that are not generated from source code or examples. This includes things like "Getting Started" and "Contributing". To edit this content, edit these Markdown files directly. This directory also maintains the directory structure that will be copied into the docs_md/ directory. The docs_md/ directory is the actual directory the mkdocs will look to to generate HTML from Markdown files, which is to say that the directory structure of the HTML files and website comes from docs_md/ which is copied form static_docs/, so maintaining this directory structure is important. You'll notice there are index.md files, these are the "homepages" for each directory (including the site's top level directory).

static_docs/guides/: Markdown files in this directory don't get rendered to webpages themselves. These files will have the basename of either a struct or trait in MMMAudio. When that struct or trait is being rendered into an HTML document, this "guide" content is added to the webpage. These live here so that this information can exist on the documentation website, but not be displayed by the LSP when coding in a MMMAudio document. This is because these guides can be quite long, so a user doesn't want to scroll through all that when trying to use the LSP to look up some arguments for example.

templates/: Contains jinja2 templates that are used for rendering Markdown files:

  • mojo_doc_template_jinja.md: Used to inject the contents of a json generated by mojo doc (which becomes a dict in generate_docs.py) into Markdown format.
  • example_python_and_mojo_jinja.md: Template for making a page for each example in the root/examples directory. In order to render properly, this template (and the corresponding Python code in generate_docs.py expect each example to consist of two files: (1) a Python file and (2) a Mojo file with the same base name). Examples should be constructed using only two files using this convention.
  • struct.md: A partial template for rendering a Mojo struct. This partial template is "called" in mojo_doc_template_jinja.md.

init.py: Makes this directory a Python package so that the main() function of the generate_docs.py file can be called as a "hook"

generate_docs.py: Python script that creates directory structure and generates Markdown files from jinja2 templates into the docs_md directory in preparation for mkdocs to use docs_md directory to create HTML (which ends up in the root/docs directory for GitHub Pages to use).

Building Documentation / How It Works

Presented here in "chronological" order

There's really no need to build the docs locally, what is more useful is to "serve locally" (see below).

The reason one doesn't need to full-on build locally is because the docs get built by GitHub on push via GitHub Actions and deployed to GitHub Pages. When iterating on designing the docs it's easier to serve locally and inspect in a browser.

The process outlined here is also exactly (or almost exactly) what happens when the docs get built by GitHub Actions. To see more specifically the GitHub Actions script, see ./.github/workflows/pages.yml.

  1. Make sure to install dependencies:
pip install -r requirements-docs.txt

In the root directory, run mkdocs build

The mkdocs.yml file indicates that the on_pre_build hook should run, which is the main() function of generate_docs.py. This script:

  1. Clears out the contents of the docs_md directory so there are no stale documents lingering there that would unintentionally be rendered by mkdocs
  2. Copies the contents of static_docs into docs_md to establish the directory structure and provide the Markdown files that are not generated from source or examples.
  3. Finds all the Mojo files in directories that contain source files (specified in generate_docs.py with the variable HARDCODED_SOURCE_DIRS) and for each file: (a) uses mojo doc to save a json file with information about the Mojo code in that .mojo file, (b) turn that json in to dict, (c) removes information from that dict that isn't worth rendering in the documentation, such as the methods __init__ and __repr__ as well as the argument self, (d) checks if there is a "guide" in "static_docs/guides" to add more information to the json (so it renders in the HTML), (e) uses the remaining contents of the dict as context for rendering a Markdown file to document what is in the file. The Markdown file has the same basename as the Mojo file.
  4. Looks in the root/examples directory and finds all the Python files. It assumes there will be a Mojo file of the same name. The script also assumes that each example consists of just the two files and that any other code that is needed can be imported from the MMMAudio core. This correspondence simplifies file management for rendering the examples into the documentation and makes the process of editing and creating examples clearer. The two files are both pasted into a Markdown file (using example_python_and_mojo_jinja.md) which is saved to the docs_md/examples directory.

Once generate_docs.py is complete, mkdocs then build the site, putting all the HTML in the site directory.

Serve Locally

To preview the documentation locally:

Make sure to install dependencies:

pip install -r requirements-docs.txt

Then run:

mkdocs serve

The documentation will be available at http://localhost:8000.

Build PDF

A PDF version of the docs can be built when mkdocs build is run. To turn this on, remove the comment hashtags beofre the with-pdf plug-ing in the mkdocs.yml file.