marian/doc
Qianqian Zhu cd9afea8d3
Documentation about how to write code documentation (#891)
* 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>
2021-12-07 15:10:46 +00:00
..
_static/css Add documentation platform based on Sphinx+Doxygen+Breathe+Exhale (#803) 2021-02-23 16:25:30 +00:00
images Documentation about how to write code documentation (#891) 2021-12-07 15:10:46 +00:00
.gitignore Add documentation platform based on Sphinx+Doxygen+Breathe+Exhale (#803) 2021-02-23 16:25:30 +00:00
conf.py Documentation about how to write code documentation (#891) 2021-12-07 15:10:46 +00:00
contributing.rst Add documentation platform based on Sphinx+Doxygen+Breathe+Exhale (#803) 2021-02-23 16:25:30 +00:00
doc_guide.rst Documentation about how to write code documentation (#891) 2021-12-07 15:10:46 +00:00
factors.md Factor concatenation improvements and documentation (#748) 2021-09-08 14:02:21 +01:00
graph.md Documentation about how to write code documentation (#891) 2021-12-07 15:10:46 +00:00
index.rst Documentation about how to write code documentation (#891) 2021-12-07 15:10:46 +00:00
make.bat Add documentation platform based on Sphinx+Doxygen+Breathe+Exhale (#803) 2021-02-23 16:25:30 +00:00
Makefile Add documentation platform based on Sphinx+Doxygen+Breathe+Exhale (#803) 2021-02-23 16:25:30 +00:00
operators.md Documentation about how to write code documentation (#891) 2021-12-07 15:10:46 +00:00
README.md Documentation about how to write code documentation (#891) 2021-12-07 15:10:46 +00:00
references.bib Added more references 2016-10-06 10:25:53 -05:00
requirements.txt Documentation about how to write code documentation (#891) 2021-12-07 15:10:46 +00:00

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 documentation
  • doxygen - automatically generated Doxygen XML files
  • api - 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