Documentation plays a crucial role in the process of technology adoption, providing the resources necessary to enable individuals to be successful when using a new library, program, or gadget. This can sound trivial, but it is often easier said than done; whether we're talking about open source projects or products, keeping up-to-date and comprehensive documentation is not an easy task at scale.
When we started building our first container images back in 2022, it didn't take long to realize we'd have a lot of work to do in order to document all the details about these images and how to use them. It was also clear that our inventory would grow exponentially, eventually creating a significant amount of documentation debt. With a small team and a big dream, we started drafting what would eventually become our images documentation factory, powered by PHP (yes, you heard it right!) and GitHub Actions. Read on to learn more about how you can take advantage of our open source tooling.
Autodocs is born
As some of you may already know, Chainguard Images are built in a declarative way, with YAML files that define how an image is created, including which packages to install and which user accounts to create. These source files provide rich metadata about images, in a known format that can be parsed relatively easily. Images also have dedicated README files with basic info on how to use them. Combining all this data to generate comprehensive and aesthetically pleasant documentation files was challenging, but worth the effort!
The pipeline
The Autodocs MVP extracted image information directly from the source YAML files. Although this worked fine at first, as the Chainguard Images project scaled up, a lot of the config used to build images was moved into CI with Terraform. The Chainguard Registry and “chainctl” became the source of truth, and that required a large refactoring to make Autodocs more decoupled from its data sources. With the new workflow, data was pulled and cached into JSON files, which would then feed the Autodocs application to build the docs. README files are still consumed to generate overview pages, since each image has its own custom usage instructions.
With approximately 500 Chainguard Images in our inventory, Autodocs generates about 1,600 markdown pages at each run.
Why PHP
Oftentimes, the best language for a project is the one you are most comfortable with. What many people don't realize is that PHP is a formidable language for the command line, providing all the amenities of a modern object-oriented language, but with shell script vibes. Because I already had quite a few PHP open source libraries that I could leverage for this project, as a long-term PHP developer, it was an easy choice. Autodocs runs on PHP 8.2+.
Open sourcing Autodocs
Because open source is core to everything we do at Chainguard, we decided to extract most of the generic implementation of Autodocs to its own separate project, which users can leverage to build their own documentation factories. The Autodocs library provides a layer of abstraction that you can use to build from 1 to 1000’s of docs, with a decoupled architecture based on JSON data feeds and markdown templates.
The project is available on GitHub, where you can find more details and basic documentation. A detailed tutorial is also available on DEV if you want to get started right away.
If you have any questions, please reach out on X!
