RAIDOC

Notebook-based markdown-powered documentation pages for RAIMAD.

This repository contains the source code for RAIDOC. If you just want to read the docs, please visit https://tifuun.github.io/raidoc/.

RAIMAD version

RAIDOC builds docs for whatever version of RAIMAD is currently installed. So you must have some version installed with pip.

Building (without docker)

First, you need to go and install graphviz. You can check that it works by running the dot command:

$ dot --version
dot - graphviz version 10.0.1 (0)

Then, you need to go and install goat:

go install github.com/blampe/goat/cmd/goat@v0.2.0

Go puts executables into ~/go/bin, so you might have to update your $PATH accordingly:

export PATH="$PATH:$HOME/go/bin"

After you have dot and goat working, install RAIDOC like any other Python package by cloning this repository:

git clone https://github.com/maybeetree/raidoc.git
cd raidoc
python -m pip install -e .

If you're on a non-glibc system (e.g. Alpine Linux), you will also need to install gcc, g++ and some headers so that pip can compile the dependencies of this project:

apk add gcc g++ python3-dev musl-dev linux-headers

See also the discussion on libsass-python about musl wheels

You can then build the documentation like this. The command MUST be run from the root of the repo.

python -m raidoc build

The output is written to the build directory. Currently, there is no incremental compilation; the above command rebuilds EVERYTHING.

Building (with docker)

You can also build raidoc with Docker (or podman). First, either pull or build the image locally and tag it as raidoc.

To pull the latest image from github:

docker pull ghcr.io/tifuun/raidoc/raidoc:latest
docker tag ghcr.io/tifuun/raidoc/raidoc raidoc

Or, to build locally:

docker build . --tag raidoc

We want the image to be a complete archive of all of RAIDOC's dependencies, in case they ever go down from the internet. Therefore, the image is quite chubby (around 1GB).

Once the image is available, it can be used to build RAIDOC. To build RAIDOC for the latest version of RAIMAD available on pip, you can pip install raimad within the contianer:

docker run --rm \
    -v .:/pwd \
    --workdir /pwd \
    raidoc \
    '/venv/bin/pip install raimad && /venv/bin/pip -m raidoc build'

Or, alternatively, you can forward a locally clone of the RAIMAD repo into the container:

docker run --rm \
    -v /path/to/raimad/repo/src/raimad:/venv/lib/python3.14/site-packages/raimad \
    -v .:/pwd \
    --workdir /pwd \
    raidoc \
    /venv/bin/python -m raidoc build

The output will be available in ./build.

Dependency cache

RAIDOC can cache the dependencies it downloads from the internet (fonts, javascript, etc.), but you have to tell it where:

python -m raidoc build --cache /var/cache/raidoc-dep

GitHub Actions

The pages site is automatically built and deployed on every git tag pushed to this repo. The RAIMAD version that is used to build the docs is specified in ./raimad.requirement.txt in pip's requirements.txt format (so it could be changed to a git commit instead of a PyPI version, for example)

Viewing the built website

Once you've built raidoc, all you need to do to view your local copy is a http static file server to serve the contents of the build directory. The easiest way to do this is with python's built-in http.server module. Simply run

python -m http.server -d build

in the root of th repo and then navigate to localhost:8000 in your web browser.

This will work regardless of whether you built raidoc natively or in docker, since we're just using python as a static file server.

TODO

• Capabilities of RAIMARK
  • Lint references
  • incremental compilation
  • references to specific labels or headings
  • Frontmatter parsing
    • "next" link through frontmatter
    • "previous" link automatic
    • display journey TOC
  • API reference generation
    • classes
    • functions
    • files/modules??
    • "Example" section of docstrings gets evaluated??
    • "See also" section are actual links
  • hayagriva/biblatex citations??
  • browser history API for back button
• RAIDOC Content
  • Deepdive on proxies
  • Demos of various raimad designs
    • vialess MSL
    • toy deshima
  • ...potentially others?
  • Documentation for maintaining raimad
  • Documentation for maintaining radoc/raidoc/raimark

License

Copyright 2026 maybetree

Documentation

The documentation files in this repository (i.e. files ending with .md under the doc/pages directory) are licensed under the GNU Free Documentation License (FDL).

Code

The code files in this repository, including all Python code, CSS and HTML templates, are licensed under the GNU General Public License (GPL).

Code snippets

The code snippets presented in the documentation pages are licensed under the CC0 License, allowing you to freely use them in your own projects.