https://github.com/interlinked1/astdocgen
Asterisk HTML documentation generator
https://github.com/interlinked1/astdocgen
asterisk
Last synced: 4 months ago
JSON representation
Asterisk HTML documentation generator
- Host: GitHub
- URL: https://github.com/interlinked1/astdocgen
- Owner: InterLinked1
- License: apache-2.0
- Created: 2021-11-26T13:30:17.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2025-02-20T03:12:13.000Z (over 1 year ago)
- Last Synced: 2025-06-25T09:43:42.351Z (12 months ago)
- Topics: asterisk
- Language: PHP
- Homepage:
- Size: 34.2 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# astdocgen
`astdocgen` generates HTML documentation from an installed version of Asterisk. Nothing more, nothing less.
We already have the Asterisk Wiki, you may ask. Indeed, [that's what inspired this project](https://web.archive.org/web/20230531205235/https://wiki.asterisk.org/wiki/display/AST/Asterisk+18+Command+Reference) (the Asterisk Wiki has since been replaced by the Asterisk Docs: https://docs.asterisk.org/Latest_API/API_Documentation/)
However, the official Asterisk documentation only documents things that *are in the official Asterisk source tree*. That's great if all of your modules are in the tree, but it doesn't help you if they aren't. Wouldn't it be great if you get that same great documentation for *any* module?
Now, you can easily generate wiki-style HTML documentation for your own custom modules.
> [!NOTE]
> This tool was written prior to the Asterisk project's move away from Atlassian tools, when there was no existing way to generate web-based documentation from a custom Asterisk source. It thus predates the current documentation generator created by the project to generate documentation (https://github.com/asterisk/documentation). You may want to consider checking that out as well, as it can also be used with a custom Asterisk source to generate documentation. `astdocgen` is quite a bit simpler and generates all documentation in a single HTML file, as opposed to the richer multi-page documentation generated by the project. The style of the documentation generated by `astdocgen` also continues to mimic that of the original Asterisk Wiki, not the current Asterisk Docs.
## Supported Platforms
- Linux/BSD. We primarily test on Debian 12.
- Requires a modern version of PHP (>= 7.3, ideally >= 8.0)
## Example
The PhreakNet Asterisk documentation is generated using `astdocgen`:
https://asterisk.phreaknet.org
Your resulting webpage may be different if your Asterisk source contains different modules. This example uses PhreakNet Asterisk (installed by PhreakScript).
## Usage
### Automated Usage
Use [PhreakScript](https://github.com/InterLinked1/phreakscript) - simply run `phreaknet docgen`. It will automatically install any pre-requisites and generate documentation using the latest version of `astdocgen`.
### Manual Usage
Run the following commands from the Asterisk source directory:
1. Install a supported version of PHP if you don't have one already. `astdocgen` is not tested on PHP < 7.3.
2. Generate HTML documentation from the XML documentation:
`./astdocgen.php -f doc/core-en_US.xml > doc/index.html`
The result is a static HTML webpage with in-page CSS documenting all the applications, functions, and AMI actions in your installed version of Asterisk.
## Limitations
One thing to be aware of is the generated HTML contains all the CSS needed, but currently this does not come with the logo or font resources (heh, maybe there are good legal reasons for this...). You can find the CSS resources on your own by poking around the Asterisk Wiki. Put the fonts and Asterisk logo in the `fonts` folder (and a favicon in the root folder if you wish), and you're good to go.
Currently, `astdocgen` supports:
- Applications
- Functions
- AMI Actions
- AGI Commands
- Modules
- Config files (for the most part, see below)
Currently, `astdocgen` does not support:
- xpointer, i.e. references to other XML files for documentation generation. As a result, some documentation, especially for modules, is sparser than in the Wiki.
- AMI manager events, because the documentation for these solely consists of xpointers.
- Config files: Type, Default Value, and Regular Expression columns aren't processed
- Info, which is mainly tech-specific `CHANNEL` function documentation.
## Bug Reporting
It is very likely that there are some bugs in this software. **THIS SOFTWARE COMES WITH NO WARRANTY OR GUARANTEES.** If you notice an inconsistency between the way documentation is generated on the Asterisk wiki versus this tool, please report it. Pull requests are also welcome.
The preferred issue reporting procedure is by cutting us a ticket at InterLinked Issues: https://issues.interlinked.us/
Choose "PhreakScript" as the category, and start the subject with "astdocgen".