mirror of
https://github.com/marian-nmt/marian.git
synced 2024-09-17 09:47:34 +03:00
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>
70 lines
2.1 KiB
Markdown
70 lines
2.1 KiB
Markdown
# 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](https://www.sphinx-doc.org/en/master/usage/quickstart.html) +
|
|
[Breathe](https://breathe.readthedocs.io/en/latest/directives.html) +
|
|
[Doxygen](http://www.doxygen.nl/manual/docblocks.html) +
|
|
[Exhale](https://exhale.readthedocs.io/en/latest/usage.html).
|
|
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](src/doc_guide.rst) 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
|
|
|