I’m working on a somewhat complex dialplan after not touching Asterisk for many years, so I’m approaching the system with fresh eyes. I’ve found https://docs.asterisk.org to be a great resource, but I’ve noticed some stale and incomplete data. I’d like to contribute some improvements back, and I’d like to confirm where those commits would go.
Everything under “Asterisk Documentation / API Documentation” comes from the Asterisk repo. Everything else is in the docs directory of the documentation repo. The deploy process brings it all together into a coherent site as HTML.
I’m not clear on how to run the documentation build pipeline from local checkouts. Reading the README I see it will default to using the gh app to pull bits from Github, which matches what my build environment is doing.
The README says to set the following in Makefile.inc:
Ping. I’m about 70% done with my rebuild project and am already starting to forget the things I wanted to update. If I don’t get the build pipeline figured out soon the window on my end to make useful contributions will pass.
The “docs” directory in the documentation repository. This directory contains the static markdown files that get converted to HTML and become everything that’s NOT under the “Asterisk XX Documentation/API Documentation” sections on the website.
The XML fragments embedded in the code source files in the Asterisk repository, like in apps/app_dial.c. These become the “AGI Commands”, “AMI Actions”, “AMI Events”, Dialplan Applications", “Dialplan Functions”, “Module Configuration” and “Module” sections under “Asterisk XX Documentation/API Documentation” .
The JSON files in the Asterisk repository under rest-api/api-docs. These become everything under the “Asterisk REST Interface” section under “Asterisk XX Documentation/API Documentation” .
The process depends on whether you’re trying to change the static documentation located in the documentation repo under the docs directory or the documentation generated from the Asterisk source code itself.
Normally, those files are created by a nightly job in the Asterisk repo that collects all the XML fragments into a single XML file and converts the json files under rest-api/api-docs into markdown files. When you run make in the documentation repo, the Makefile downloads those files into the local ./temp directory, converts the XML to markdown, then merges the static documentation from the docs directory, the markdown converted from the XML and the markdown converted from the JSON files together and runs mkdocs to convert the whole thing to HTML.
If you’re only modifying the the static documentation in the docs directory, you should not set either the ASTERISK_XML_FILE and ASTERISK_ARI_DIR variables yourself. The Makefile will set them to where it downloaded the files from the Asterisk nightly job to.
If you ARE modifying the XML fragments or the JSON files in the Asterisk repo and you want to see what they’ll look like when they make it to the documentation site, you’ll need to set those variables but you’ll have to perform some steps in the Asterisk repo first…
In your local checkout of the asterisk repository (let’s assume it’s in /usr/src/asterisk/asterisk)…
Checkout the master branch and make your changes.
Configure, build and install asterisk as you normally would.
If you’ve changed the JSON files in res-api/api-docs, run make ari-stubs. This will create markdown files in the doc/rest-api directory.
If you’ve change any of the XML fragments in the source files, you’ll need to actually start asterisk (using just the sample config files is fine) and run the following command from the asterisk CLI: xmldoc dump /tmp/asterisk-docs.xml. You can then stop asterisk. The filename doesn’t matter as long as you can get to it. NOTE: If you make additional changes to the embedded XML, you will need to re-build and re-install asterisk before running the xmldoc dump command again.
Back in the documentation repo (let’s assume it’s /usr/src/asterisk/documentation)…
Update the repo from the latest main branch. I just pushed up a fix to the Makefile.
Make sure you’ve followed the instructions in the README to set up the environment.
If you’ve made JSON changes, set ASTERISK_ARI_DIR := /usr/src/asterisk/asterisk/doc/rest-api
in Makefile.inc
If you’ve made XML fragment changes, set ASTERISK_XML_FILE := /tmp/asterisk-docs.xml
(or wherever you saved the xmldoc dump to) in Makefile.inc
You only generated the documentation for the asterisk master branch but we don’t build master branch documentation for docs.asterisk.org so you need to set BRANCHES := 21 as a workaround.
Now just run make. When it completes, the full documentation will be available in the temp/site directory.
You can browse the site directory locally from your browser with… file:///usr/src/asterisk/documentation/temp/site/
but some navigation things aren’t going to work. To get the same experience you’d get from visiting docs.asterisk.org, you’ll need to set up a local web server whose document root points to /usr/src/asterisk/documentation/temp/site/ or you can run make serve which will start the internal mkdocs web server and visit http://localhost:8000/.
If these instructions work well for you, I’ll update the README file with them. If not, let me know and I’ll see if I can clarify.