docs

Documentation

OCP node documentation. It does document node specific topics like DML language and WAMP api. No general OCP documentation is provided here, that is in the documentation repository. The documentation tool of choice is sphinx, and hence all documentation is written in restructured text.

Toolchain

The docs are partially handwritten (see folder ocpsource) and partially autogenerated from the source via the docgen executable. This allows to have API documentation rigth where it is implemented, and hence is way easier to keep up to data. Compiling and running the docgen extracts all marked source file comments into .rst files according to the comment instructions. Those generated .rst files are included in the handwritten files. Note that generated files are not added to git and must be created everytime one wants to generate the documentation

• Source comments with the "+extract" tag are added to packagename.rst. If a custom filename should be used one can specify it via target:name
• ordering of comments in a file can be manipulated by adding prio:num (same prio comments are ordered by order of encounter)
• adding indent in the source file can be achieved by indent:num (num being the number of tabs)

Generate docs

For previewing the OCP node docs one can generate them directly with a basic layot using sphinx

go run docgen.go 
make html

The result can be viewed via build/html/index.html. Of course all other sphinx outputs like epub are suported.

Automation

The purpose of this documentation is to be integrated into the general OCP documentation, as there should be only a single documentation resource in the end. Therefore a github action is setup to automatically generate all source files and pushes them into the OCP documentation repository. This happens on every push to the github master.