Documentation source for

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 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.

It looks like the source for pages like Dial - Asterisk Documentation lives in the source code in the asterisk/asterisk repo, and not the documentation repo in asterisk/documentation. For example I found what looks like the source of Dial - Asterisk Documentation in a comment in app_dial.c: asterisk/apps/app_dial.c at master · asterisk/asterisk · GitHub Is that correct?

It’s early and I haven’t fully mentally processed documentation/ at main · asterisk/documentation · GitHub yet, I’m assuming the build system in asterisk/documentation parses those comments in the asterisk/asterisk source into the site?

Where do pages like this this parallel documentation come into play? documentation/docs/Configuration/Applications/ at main · asterisk/documentation · GitHub

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.

Okay, thanks. And I see that documentation/docs/Configuration/Applications/ at main · asterisk/documentation · GitHub is Dial Application - Asterisk Documentation

Re-reading the documentation repo Makefile I think I understand the workflow. I’ll get that build system set up and see if I have any more questions.

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

ASTERISK_XML_FILE := <somepath>/asterisk/doc/core-en_US.xml
ASTERISK_ARI_DIR := <somepath>/asterisk/doc/rest-api

But the default valued don’t seem to match the Makefile defaults:

  ASTERISK_XML_FILE := $(BRANCH_DIR)/source/asterisk-docs.xml

Which has me a bit confused as I can’t find either of those XML files in either repo:

asterisk/asterisk $ git log -1 | head -n 3
commit ea3b520bedfc57e171051567a70411c2bbd60c6c
Author: Naveen Albert <>
Date:   Sun Jan 28 08:57:47 2024 -0500

asterisk/documentation $ git log -1 | head -n 3
commit c1cfbab84a5b3914f69a2e34927fdd37d1248e91
Author: Joshua C. Colp <>
Date:   Mon Jan 29 09:56:03 2024 -0400

asterisk $ for f in rest-api core-en_US.xml asterisk-docs.xml; do find ./ -iname $f; done

So based on this ASTERISK_ARI_DIR should be [asterisk repo checkout]/rest-api, but what about ASTERISK_XML_FILE?

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.

Standby. I’m reading the thread and will get you more info in a bit. Sorry for the delay.

The contents of come from 3 places…

  • 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
  • If you’ve made XML fragment changes, set
    ASTERISK_XML_FILE := /tmp/asterisk-docs.xml
    (or wherever you saved the xmldoc dump to) in
  • You only generated the documentation for the asterisk master branch but we don’t build master branch documentation for 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…
but some navigation things aren’t going to work. To get the same experience you’d get from visiting, 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.

Thank you for the detailed answer. I think I understand the process now. I’ll try it out and report back.

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.