raspberrypi/documentation: the source tree behind the official Raspberry Pi docs

What raspberrypi/documentation actually is

The repository contains the source and tools used to build the Raspberry Pi Documentation site. That sentence from the README is the whole scope. It is not a library you import, and it is not a doc generator that scans your codebase. It is the content tree for one vendor's documentation plus the machinery that turns that content into a static site.

The audience follows from that. Contributors who want to fix a typo or expand a page about the camera stack or the Pico need to work here. People who want to run the official docs offline, or study how a hardware company structures reference material, also have a reason to clone it. Everyone else should read the published site instead. Cloning a documentation repository to read documentation is more work than reading the documentation.

The topics list tells you what the content covers: asciidoc, documentation, raspberry-pi, raspberry-pi-camera, raspberry-pi-pico. So the prose is about Pi hardware and the Pico SDK, and the formats are AsciiDoc as the source and HTML as the output.

The Makefile, Ninja and Jekyll pipeline

The build is a Makefile that shells out to Ninja, Doxygen and Jekyll. The Makefile names the source directory as documentation/asciidoc and the HTML output as documentation/html, with images in documentation/images. The default goal is html, so running make with no target builds the site.

The interesting part is the generated reference material. The Makefile defines PICO_SDK_DIR as lib/pico-sdk and PICO_EXAMPLES_DIR as lib/pico-examples, both of which are git submodules. Doxygen is pointed at the pico-sdk build, and its XML output lands in build-pico-sdk-docs/combined/docs/doxygen/xml. A helper directory, lib/doxygentoasciidoc, converts that XML into AsciiDoc, which is written into documentation/asciidoc/pico-sdk. The Makefile carries a comment that the pico-sdk here needs to match the from_json entry in index.json. That is a coupling you have to respect: the generated API pages and the index that links them are versioned together.

Autogenerated Ninja rules go into build/autogenerated.ninja, and AsciiDoc includes into build/adoc_includes. Jekyll is invoked as bundle exec jekyll, so the Ruby side comes from the Gemfile and Gemfile.lock, not from requirements.txt. That split is easy to miss. requirements.txt lists only pyyaml, lxml and beautifulsoup4, which are the Python helpers for the conversion scripts, not the site builder.

Building the docs locally

The repository ships BUILD.md, which is where the project documents its own build steps; the README points contributors at CONTRIBUTING.md instead. What the Makefile shows is the sequence: submodules first, because the Doxygen targets depend on files inside lib/pico-sdk and lib/pico-examples, then the build itself.

Start by initialising the submodules. The Makefile does this through a rule that runs git submodule update --init on the pico-sdk directory and then inside it, because pico-sdk has submodules of its own.

git submodule update --init lib/pico-sdk
git -C lib/pico-sdk submodule update --init
git submodule update --init lib/pico-examples

After that, the Python dependencies for the conversion scripts are installed from requirements.txt.

pip install -r requirements.txt

Then run the default goal. This builds the HTML output into the build tree.

make

The Makefile also defines a serve_html target that wraps the Jekyll command, which is the one you want for local preview rather than a one-shot build.

make serve_html

The Ruby side must already be satisfied before any of this works, since the site is assembled with bundle exec jekyll. If make fails early, check that the submodule directories are populated and that Bundler can resolve the Gemfile, in that order.

The Doxygen bridge is the fragile part

Generating pico-sdk reference pages means running Doxygen over a C SDK, converting the XML to AsciiDoc, and feeding the result into the same Jekyll build as hand-written prose. That bridge is where a documentation repository stops being a folder of text files.

The Makefile comment about matching the pico-sdk to the from_json entry in index.json is the clearest signal of the cost. Generated pages are not free-standing; they are addressed by an index that has to agree with the SDK revision you checked out. Bump the submodule without touching the index and the build can still succeed while producing links that point at the wrong API surface. Nothing in the Makefile validates that agreement for you.

The Doxygen XML path is long and specific: build-pico-sdk-docs/combined/docs/doxygen/xml. That path comes from the pico-sdk's own Doxygen configuration, which means a change on the SDK side can move it. The Makefile hardcodes it. This is a normal consequence of generating reference docs from someone else's build system, but it is a coupling worth knowing about before you assume the pipeline is self-contained.

Where this repository is the wrong tool

If you arrived looking for a documentation generator for your own project, this is not it. There is no configuration file that points at your source tree, no plugin interface, no theme you can drop in. The AsciiDoc directory is Raspberry Pi's content. The Doxygen step is wired to the Pico SDK. The Jekyll configuration in _config.yml is for one site.

A second limitation is weight. Building the full site pulls in two C submodules, a Doxygen run and a Jekyll environment. That is a lot of machinery for someone who only wants to correct a sentence. For a single prose fix, editing the AsciiDoc file and opening a pull request against the upstream repository is the proportionate move; reproducing the whole toolchain locally is only worth it if you are changing structure, includes or generated content.

The third is licensing asymmetry, covered below: the prose and the tools are under different licences, so "can I reuse this" has two different answers depending on which directory you mean.

Alternatives and how they differ

The obvious alternative is Sphinx with reStructuredText or Markdown, which is what a great many hardware and Python projects use. The difference in approach is where the reference material comes from. Sphinx generates API documentation from docstrings in the source it is pointed at, through autodoc, so the docs and the code live in one build. This repository instead treats the SDK as an external submodule, runs Doxygen over it, and converts the XML into AsciiDoc. If your project is Python and your API docs can come from docstrings, Sphinx removes the Doxygen-to-AsciiDoc step entirely.

A second alternative is a docs-as-code setup built on MkDocs, where Markdown files and a single YAML config produce a site with no Ruby toolchain. That is lighter to install and easier for occasional contributors. The trade-off is that MkDocs has no equivalent of the pico-sdk Doxygen bridge in this repository, so you would be assembling C API reference generation yourself.

The honest comparison: this repository is a purpose-built pipeline for one vendor's hardware documentation. Its value to an outsider is as a worked example of combining hand-written AsciiDoc with generated C reference pages, not as a framework to adopt wholesale.

Licence split and upgrade cost

The licensing is split, and the README states it plainly. The Raspberry Pi documentation content is licensed under Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA). The documentation tools, meaning everything outside the documentation/ subdirectory, are licensed under BSD 3-Clause. The repository's LICENSE.md is the file to read for the exact terms; this is a description of what the README says, not legal advice.

ShareAlike has a practical consequence for anyone mirroring or adapting the content: derivative works of the documentation carry the same licence forward. The tooling under BSD 3-Clause does not. If you are only borrowing the build scripts, you are in the second category; if you are republishing pages from documentation/, you are in the first.

On upgrades, the last push to the default branch was on 2026-09-22, and the repository is not archived. The only listed release is docs-ng (Next Generation Documentation) from 2021-08-09, which is old enough that it does not describe the current tree; the Makefile, build.ninja and the submodule layout are the current state. Upgrading means tracking master and re-running the submodule initialisation, and the main recurring cost is the index.json and pico-sdk revision pairing described earlier. There is no documented rollback procedure in the README for a build that goes wrong after a submodule bump, so keep the submodule revisions you last built against.

Editorial conclusion

Adopt this repository if you are contributing to or mirroring the official Raspberry Pi documentation, or if you want to see how a Makefile, Ninja, Doxygen and Jekyll pipeline is wired together for a hardware vendor's docs. Do not adopt it as a general documentation framework for your own product: the pico-sdk and pico-examples submodules, the Doxygen-to-AsciiDoc conversion and the index.json wiring are specific to Raspberry Pi content. Before you build, confirm that git submodule update --init completes for both lib/pico-sdk and lib/pico-examples, since the Makefile's Doxygen targets depend on files inside them, and check that your Ruby environment satisfies the Gemfile rather than assuming the Python requirements.txt is the whole story.

Frequently asked questions

Official sources

1. License: CC-BY-SA-4.0
2. Project website
3. raspberrypi/documentation on GitHub
4. README
5. Releases