https://github.com/nuald/adx
Produces the code's auto-generated documentation in HTML, PDF or XML.
https://github.com/nuald/adx
doxygen html jsdoc xml
Last synced: over 1 year ago
JSON representation
Produces the code's auto-generated documentation in HTML, PDF or XML.
- Host: GitHub
- URL: https://github.com/nuald/adx
- Owner: nuald
- License: unlicense
- Created: 2018-04-19T05:02:44.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2023-11-01T23:23:17.000Z (over 2 years ago)
- Last Synced: 2025-02-01T04:14:35.562Z (over 1 year ago)
- Topics: doxygen, html, jsdoc, xml
- Language: Go
- Homepage:
- Size: 450 KB
- Stars: 0
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# adx
Produces the code's auto-generated documentation in HTML, PDF or XML.
## Requirements
The tool utilizes Doxygen and JsDoc3 command line utilities, please be sure
to install those first, e.g. for macOS:
$ brew install doxygen node
$ npm i jsdoc -g
Please note the tool uses `xsltproc` utility, so be sure that it's available
in PATH.
## Installation
go get -u github.com/nuald/adx
## Usage
Please use the tool's flags to generate the corresponding output:
```
Usage: adx [-conf=(yaml-file)] -lang=(lang) [-jsconf=(jsdoc-conf)] [-src=(src-dir)]+ [-xml=(xml-file)]+ -title=(title) -out=(out.[html|pdf|xml])
Produces the code's auto-generated documentation in HTML, PDF or XML.
Flags:
-conf string
the configuration file for the custom languages
-jsconf string
the JSDoc configuration file
-lang string
the source code programming language (js, java)
-out string
the output file (the format is based on its extension)
-src value
the source code dir(s)
-title string
the document title
-xml value
the input XML file(s)
```
## Development Notes
`make` is utilized to perform various tasks related to development.
Unit-testing:
$ make tests
Local installation:
$ make install
## Custom Languages Support
Custom languages are parsed based on the configuration files. The code should be documented
in a special way as it's parsed to generate the documentation based on the rules
from the configuration.
Code sample:
```
/**
* Class: Foo
* Foo demo class
*
* @property prop The sample property.
* @constructor Build an Foo class instance.
*/
class Foo(private val prop: String) {
/**
* Method: method1
* The sample method.
*
* @param arg The sample argument.
* @return The sample return.
*/
fun method1(arg: String): Int {
}
}
```
*Class:*, *Method:* (*Static Method:*, *Constructor:*) and *Property:* (*Static Property:*) markers
are used to determine the block context. Classes may have the optional
*@constructor* tag to identify that the constructor is implicitly defined
with the *@property* list as its arguments.
The configuration file has the following YAML format (see fixtures/config.yaml as an example):
```
:
extensions: [list of extensions]
docstrings:
type: [block|line]
format: /** */
parameter: '@param (?P\w+)\s?(?P.*)'
return: '@return\s?(?P.*)'
```
Please note that `parameter` and `return` are regular expressions that should have
the *name* (not for `return`) and *description* capture groups.