cd9afea8d3
* add initial guidelines of code documentation * fix math formula not displayed in Sphinx * remove @name tags which cannot be extracted by exhale and cause function signature errors * fix markdown ref warning and update markdown parser in sphinx * more about doxygen: add Doxygen commands and math formulas * move code doc guide to a new .rst file * add formula image * Set myst-parser version appropriate for the requested sphinx version * Update documentation on how to write Doxygen comments * Add new section to the documentation index * Sphinx 2.4.4 requires myst-parser 0.14 * complete code doc guide and small fixes on reStructuredText formats * More about reStructuredText * Update badges on the documentation frontpage Co-authored-by: Roman Grundkiewicz <rgrundkiewicz@gmail.com>
2.1 KiB
Marian NMT code documentation and library API
This directory contains code documentation and library API for developers of Marian NMT.
The documentation is generated using
Sphinx +
Breathe +
Doxygen +
Exhale.
The documentation source code is written in .rst or .md files with special directives that allow
to reference to C++ source code and documentation. The source documents are then build into static
HTML pages.
Installation
On Ubuntu 20.04, install the following packages:
sudo apt-get install python3 python3-pip python3-setuptools doxygen
Then set up a Python environment and install modules:
pip3 install virtualenv
virtualenv venv -p python3
source venv/bin/activate
pip3 install -r requirements.txt
Documentation building should also work on Windows, but it has not been tested.
Generation
The documentation can be generated by running:
make html
The website will be generated into build/html and accessible by opening index.html in your
browser.
Directories:
build- automatically output directory for HTML documentationdoxygen- automatically generated Doxygen XML filesapi- automatic library API generated with Exhale.rstand.mdfiles in this directory and its subdirectories are documentation source files_static- custom CSS and JavaScript files
Writing documentation
See this section in the documentation for detailed recommendations on how to write code and user documentation in Marian.
In a nutshell, each class, struct or function should have a Doxygen comment following the basic template of:
/**
* Brief summary.
* Detailed description. More detail.
* @see Some reference
* @param <name> Parameter description
* @return Return value description
*/
std::string function(int param);
And attributes should be documented with an inline comment, for example:
int var; ///< Brief description