|
||
---|---|---|
.. | ||
_static/css | ||
images | ||
.gitignore | ||
conf.py | ||
contributing.rst | ||
doc_guide.rst | ||
factors.md | ||
graph.md | ||
index.rst | ||
layer.md | ||
make.bat | ||
Makefile | ||
operators.md | ||
README.md | ||
references.bib | ||
requirements.txt | ||
structure.md |
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.rst
and.md
files 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