Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Rework the contribution guide and style guide. #156

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 17, 2025
Merged

Rework the contribution guide and style guide. #156

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 11 additions & 4 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
#
# NOTE: For readability, two space characters are used to
# indent the contents of make ifeq/ifneq statements.
# Don;y confuse these with tabs used to indent rule
# Don't confuse these with tabs used to indent rule
# recipies.
#

Expand All @@ -10,10 +10,17 @@ DEPLOY_BRANCH ?= gh-pages
BUILD_DIR ?= ./temp
GH=gh
JOB_DATE ?= $(shell date +%F)
SERVE_OPTS ?= -a [::]:8000
BRANCHES ?=
BRANCH ?=

include Makefile.inc
ifneq ($(BRANCH),)
-include Makefile.$(BRANCH).inc
-include Makefile.inc

ifneq ($(BRANCHES),)
COMMA := ,
BB := $(subst $(COMMA), ,$(BRANCHES))
includes := $(foreach b,$(BB),Makefile.$(b).inc)
-include $(includes)
endif

# 'make' has a realpath function but it only works on
Expand Down
226 changes: 3 additions & 223 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,228 +1,8 @@
# Description

This repository contains the Asterisk Documentation project.
This repository contains the documentation for the [Asterisk](https://github.com/asterisk/asterisk) project.

# Recent Changes
## Recent Changes

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 instructions formerly in this page for contributing to this repository have moved to the [Contributing to the Documentation](https://docs.asterisk.org/Contributing-to-the-Documentation) page on the live website.

# Static Documentation

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.

## Markdown Flavor
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.

> [!NOTE]
> The conversion process that moved the documentation from the Confluence Wiki used equals signs `=====` and dashes `----` to denote headers. The new infrastructure renders those correctly but they do not get added to the page's table of contents. Going forward, you should always use hash signs `#`, `##`, `###`, etc to denote headers.

### PyMdown Extensions

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:

```
/// warning | Don't Do This
Don't do this in your code!!!
'''
free(NULL);
'''
///
```

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:

```
betterem
blocks.admonition
blocks.definition
caret
critic
details
emoji
highlight
inlinehilite
keys
mark
saneheaders
smartsymbols
snippets
superfences
tabbed
tilde
```

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

# Dynamic Documentation

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.

# Build/Test Dependencies

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

```
$ pip3 install -r requirements.txt
```

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

```
$ python -m venv ./.venv
$ source .venv/bin/activate
(.venv)$ pip3 install -r requirements.txt
# run `deactivate` when done
(.venv)$ deactivate
$
```

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.

> [!NOTE]
> The documentation build process no longer uses the `mike` python package.

# Building and Testing the Documentation

## Prepare

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.

```
$ git clone -b main https://github.com/asterisk/documentation
$ cd documentation
```

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

```
# BUILD_DIR := <somepath> # Defaults to ./temp

# MkDocs needs to know the base URL for the documentation site
# to properly handle links and navigation.
# If you're going to deploy the site locally, use the
# URL of your local server.
# The default is https://docs.asterisk.org which is
# probably not what you want.
# NOTE: You MUST use the export keyword for this variable.
# export SITE_URL := <your_local_server>

# The following 2 DEPLOY_ variables are only needed if you
# need to deploy the built site to some other repo.
# The nightly job uses this to publish the site to
# GitHub pages.
# DEPLOY_REMOTE := <git_remote>
# DEPLOY_BRANCH := <gh pages branch> # Defaults to gh-pages

# The comma-separated list of branches for which dynamic
# documentation should be built when doing a `make` without
# specifying BRANCH=<branch>.
# BRANCHES := 20,21,22

# If you don't want to build the static documentation at all...
# NO_STATIC=yes

# If you don't want the resulting HTML minified, set NO_MINIFY.
# Minification can reduce the space required to host the full
# site by about 30% but it does take over double the time to
# generate the site.
# NO_MINIFY=yes

# If you want to serve the resulting site with mkdocs serve,
# you can specify any additional options to pass to it here:
# SERVE_OPTS := -a [::]:8000
```

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

```
# If you want to use a local XML file to generate the
# AGI, AMI, Dialplan and Module_Configuration documentation,
# specify it here.
# ASTERISK_XML_FILE := <somepath>/asterisk/doc/core-en_US.xml
#
# If you want to use local markdown files for the ARI
# documentation, specify a path to a directory containing
# the markdown generated by "make ari-stubs".
# ASTERISK_ARI_DIR := <somepath>/asterisk/doc/rest-api
#
# If you want to use local XML but skip processing ARI
# altogether, set this variable to "yes".
# SKIP_ARI := yes

# If either ASTERISK_XML_FILE or ASTERISK_ARI_DIR are not set,
# that documentation source will be downloaded from the
# CreateDocs job.
```

## Build and Deploy

### To build the entire site:

```
$ make
```

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.

### To build just the static pages

```
$ make BRANCHES=
```

### To build just 2 branches

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

```
$ make BRANCHES=18,20
```

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

```
$ make BRANCHES=18,20 NO_STATIC=yes
```

### To build just 1 branch

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:

```
ASTERISK_XML_FILE := <path>/core-en_US.xml
ASTERISK_ARI_DIR := <path>/rest-api
BRANCHES := 20
NO_STATIC := yes
```

And just run `make`.
2 changes: 1 addition & 1 deletion docs/.pages
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,4 +19,4 @@ nav:
- Certified-Asterisk_20.7_Documentation
- Test-Suite-Documentation
- Historical-Documentation

- Contributing-to-the-Documentation.md
Loading