include Makefile.inc

ifneq ($(BRANCH),)

-include Makefile.$(BRANCH).inc

This repository contains the Asterisk Documentation project.

The packages used to create the documentation were upgraded on February 2 2024. While there are no breaking changes, some new capabilities were added that, if used going forward, won't render correctly with the older versions. So, if you build documentation locally, you should delete your local virtualenv and re-create it using the new requirements.txt file. The new features will be documented separately.

The static documentation contained in the ./docs/ directory is written directly in markdown. The publish process uses [mkdocs](https://www.mkdocs.org) and [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) to generate the HTML web site. The directory structure is fairly straightforward so if you wish to contribute, you should fork this repository and submit pull requests against files in that directory.

All contributions are subject to the

[Creative Commons Attribution-ShareAlike 3.0 United States](LICENSE.md) license.

The docs are written in standard markdown, not GitHub Flavored markdown. There are lots of extensions available though. Most of the extensions provided by [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/reference/) are enabled except those only available to paying sponsors and a few that don't make sense in this environment.

Many extensions from the [PyMdown](https://facelessuser.github.io/pymdown-extensions/) plugin are also available. The `admonition` extension is particularly useful as a replacement for the legacy `!!! note` admonition style because it uses a trailer to mark the end of the admonition instead of just a blank line. This allows you to add things like code blocks and quotes inside admonitions.

Admonition Example:

You couldn't do that with the legacy `!!!` style admonition.

If you decide to use any of the extensions from this plugin (and you should use them where possible), don't use the legacy version in the same page. For instance, don't mix `///` admonitions with `!!!` admonitions in the same page. There's a good chance they won't render correctly.

At some point, we'll try and convert all of the existing legacy admonitions to the new style.

[PyMdown Documentation](https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/)

Enabled extensions:

See `markdown_extensions` in the [mkdocs.yml](mkdocs.yml) file for the current list.

The dynamic documentation includes the pages generated from Asterisk itself and includes:

* AGI_Commands

* AMI_Actions

* AMI_Events

* Asterisk_REST_Interface

* Dialplan_Applications

* Dialplan_Functions

* Module_Configuration

The publish process gets this information directly from the Asterisk CreateDocs job (which runs nightly) and generates markdown. For this reason, all changes to the dynamic documentation need to be made in the Asterisk source code itself.

The AGI, AMI, Dialplan and Module documentation comes from the documentation embedded in the provider modules and generated by CreateDocs running `xmldoc dump` from the Asterisk CLI. You can also use a core-en_US.xml or full-en_US.xml file generated from a local asterisk build. See below for more information.

The Asterisk_REST_Interface documentation comes from the markdown files generated by CreateDocs running `make ari-stubs`. You can also use locally generated markdown files. See below for more information.

Dependencies for documentation can be installed using the included requirements.txt file.

If you don't want to install the requirements for the current user or globally, you can create a virtual environment specific to this directory first...

The next time you want to test, you can just activate the virtual environment without needing to install the dependencies again. The `.venv` directory is already in the `.gitignore` file.

You'll also need the [`gh`](https://cli.github.com) tool to pull down the dynamic documentation from the CreateDocs job.

Everything is done from the [`documentation`](https://github.com/asterisk/documentation) repository so, if you haven't already, clone it and check out the `main` branch.

Create a `Makefile.inc` file with some configuration variables. This file must **not** be checked in. Here are the contents to use:

If you're planning on using local sources for the dynamic Asterisk documentation, you'll *also* need to create a `Makefile.<branch>.inc` file *for each branch*.

This will build the static pages and the dynamic pages for all branches listed in the `BRANCHES` variable. The fully functioning site will be created at `$(BUILD_DIR)/site`. You can serve that directory with `make serve`, which runs `mkdocs serve` or a web server of your own choosing. `mkdocs serve` rebuilds the entire site when it starts so you may want to use a standard web server if you plan on doing this a lot. If you do use `make serve`, you can use the `SERVE_OPTS` variable in Makefile.inc to add additional options to the `mkdocs serve` command line.

Building branches does need at least a skeleton static layout so `static-setup` will be built first if it hasn't already been built.

If you only want the skeleton static documentation, you can add `NO_STATIC=yes` to that command line...

If you're always going to build just 1 branch's dynamic documentation, you can skip the `Makefile.<branch>.inc` file and just place everything in the main `Makefile.inc`:

Makefile.inc:

And just run `make`.