mirror of
https://github.com/marian-nmt/marian.git
synced 2024-09-17 09:47:34 +03:00
Add documentation platform based on Sphinx+Doxygen+Breathe+Exhale (#803)
* Setup Sphinx+Doxygen+Breathe+Exhale * Remove links to modindex and search pages * Enable Doxygen autobrief
This commit is contained in:
parent
927b95a3ab
commit
f88ded2ba8
@ -8,6 +8,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
|
|||||||
|
|
||||||
## [Unreleased]
|
## [Unreleased]
|
||||||
|
|
||||||
|
### Added
|
||||||
|
- Developer documentation framework based on Sphinx+Doxygen+Breathe+Exhale
|
||||||
|
|
||||||
### Fixed
|
### Fixed
|
||||||
- Fix building server with Boost 1.75
|
- Fix building server with Boost 1.75
|
||||||
|
|
||||||
|
4
doc/.gitignore
vendored
Normal file
4
doc/.gitignore
vendored
Normal file
@ -0,0 +1,4 @@
|
|||||||
|
api
|
||||||
|
build
|
||||||
|
doxygen
|
||||||
|
venv
|
23
doc/Makefile
Normal file
23
doc/Makefile
Normal file
@ -0,0 +1,23 @@
|
|||||||
|
# You can set these variables from the command line, and also
|
||||||
|
# from the environment for the first two.
|
||||||
|
SPHINXOPTS ?=
|
||||||
|
SPHINXBUILD ?= sphinx-build
|
||||||
|
SOURCEDIR = .
|
||||||
|
BUILDDIR = build
|
||||||
|
|
||||||
|
# Put it first so that "make" without argument is like "make help".
|
||||||
|
help:
|
||||||
|
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||||
|
|
||||||
|
.PHONY: clean help Makefile
|
||||||
|
|
||||||
|
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||||
|
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||||
|
%: Makefile
|
||||||
|
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||||
|
|
||||||
|
# Clean target as recommended by Exhale
|
||||||
|
# https://exhale.readthedocs.io/en/latest/usage.html#optional-create-a-proper-clean-target
|
||||||
|
clean:
|
||||||
|
rm -rf doxygen/ api/
|
||||||
|
@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
51
doc/README.md
Normal file
51
doc/README.md
Normal file
@ -0,0 +1,51 @@
|
|||||||
|
# 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
|
||||||
|
pip 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
|
||||||
|
|
||||||
|
To be documented...
|
4
doc/_static/css/custom.css
vendored
Normal file
4
doc/_static/css/custom.css
vendored
Normal file
@ -0,0 +1,4 @@
|
|||||||
|
.wy-body-for-nav > .wy-grid-for-nav > .wy-nav-side {
|
||||||
|
border-bottom: 5px solid #28bbee;
|
||||||
|
/*background-color: #494d55;*/
|
||||||
|
}
|
118
doc/conf.py
Normal file
118
doc/conf.py
Normal file
@ -0,0 +1,118 @@
|
|||||||
|
# Configuration file for the Sphinx documentation builder.
|
||||||
|
#
|
||||||
|
# This file only contains a selection of the most common options. For a full
|
||||||
|
# list see the documentation:
|
||||||
|
# https://www.sphinx-doc.org/en/master/usage/configuration.html
|
||||||
|
|
||||||
|
# -- Path setup --------------------------------------------------------------
|
||||||
|
|
||||||
|
# If extensions (or modules to document with autodoc) are in another directory,
|
||||||
|
# add these directories to sys.path here. If the directory is relative to the
|
||||||
|
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||||
|
#
|
||||||
|
import os
|
||||||
|
import datetime
|
||||||
|
import sys
|
||||||
|
|
||||||
|
sys.path.insert(0, os.path.abspath('.'))
|
||||||
|
|
||||||
|
|
||||||
|
# -- Project information -----------------------------------------------------
|
||||||
|
|
||||||
|
project = 'Marian NMT'
|
||||||
|
copyright = '2021, Marian NMT Team'
|
||||||
|
author = 'Marian NMT Team'
|
||||||
|
|
||||||
|
# The full version, including alpha/beta/rc tags
|
||||||
|
# TODO: add GitHub commit hash to the version
|
||||||
|
version_file = os.path.join(os.path.dirname(os.path.dirname(__file__)), 'VERSION')
|
||||||
|
with open(os.path.abspath(version_file)) as f:
|
||||||
|
version = f.read().strip()
|
||||||
|
release = version + ' ' + str(datetime.date.today())
|
||||||
|
|
||||||
|
|
||||||
|
# -- General configuration ---------------------------------------------------
|
||||||
|
|
||||||
|
# Add any Sphinx extension module names here, as strings. They can be
|
||||||
|
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||||
|
# ones.
|
||||||
|
extensions = [
|
||||||
|
'sphinx.ext.imgmath',
|
||||||
|
'sphinx.ext.todo',
|
||||||
|
'breathe',
|
||||||
|
'exhale',
|
||||||
|
'recommonmark',
|
||||||
|
]
|
||||||
|
|
||||||
|
# Add any paths that contain templates here, relative to this directory.
|
||||||
|
templates_path = ['_templates']
|
||||||
|
|
||||||
|
# List of patterns, relative to source directory, that match files and
|
||||||
|
# directories to ignore when looking for source files.
|
||||||
|
# This pattern also affects html_static_path and html_extra_path.
|
||||||
|
exclude_patterns = [
|
||||||
|
'build',
|
||||||
|
'doxygen',
|
||||||
|
'venv',
|
||||||
|
'README.md',
|
||||||
|
]
|
||||||
|
|
||||||
|
|
||||||
|
# -- Options for HTML output -------------------------------------------------
|
||||||
|
|
||||||
|
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||||
|
# a list of builtin themes.
|
||||||
|
#
|
||||||
|
html_theme = 'sphinx_rtd_theme'
|
||||||
|
htmlhelp_basename = 'marian'
|
||||||
|
|
||||||
|
# Add any paths that contain custom static files (such as style sheets) here,
|
||||||
|
# relative to this directory. They are copied after the builtin static files,
|
||||||
|
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||||
|
html_static_path = ['_static']
|
||||||
|
html_css_files = ['css/custom.css']
|
||||||
|
|
||||||
|
# The base URL which points to the root of the HTML documentation
|
||||||
|
html_baseurl = 'http://marian-nmt.github.io/docs/api'
|
||||||
|
|
||||||
|
|
||||||
|
# -- Extension configuration -------------------------------------------------
|
||||||
|
|
||||||
|
breathe_projects = { 'marian': './doxygen/xml' }
|
||||||
|
breathe_default_project = 'marian'
|
||||||
|
|
||||||
|
doxygen_config = """
|
||||||
|
INPUT = ../src
|
||||||
|
EXCLUDE += ../src/3rd_party
|
||||||
|
EXCLUDE += ../src/tests
|
||||||
|
EXCLUDE_PATTERNS = *.inc *.md *.txt
|
||||||
|
ENABLE_PREPROCESSING = YES
|
||||||
|
JAVADOC_AUTOBRIEF = YES
|
||||||
|
WARN_IF_UNDOCUMENTED = NO
|
||||||
|
"""
|
||||||
|
|
||||||
|
exhale_args = {
|
||||||
|
'containmentFolder' : './api',
|
||||||
|
'rootFileName' : 'library_index.rst',
|
||||||
|
'rootFileTitle' : 'Library API',
|
||||||
|
'doxygenStripFromPath' : '..',
|
||||||
|
'createTreeView' : True,
|
||||||
|
'exhaleExecutesDoxygen' : True,
|
||||||
|
'exhaleDoxygenStdin' : doxygen_config.strip(),
|
||||||
|
}
|
||||||
|
|
||||||
|
primary_domain = 'cpp'
|
||||||
|
highlight_language = 'cpp'
|
||||||
|
|
||||||
|
# A trick to include markdown files from outside the source directory using
|
||||||
|
# 'mdinclude'. Warning: all other markdown files not included via 'mdinclude'
|
||||||
|
# will be rendered using recommonmark as recommended by Sphinx
|
||||||
|
from m2r import MdInclude
|
||||||
|
|
||||||
|
def setup(app):
|
||||||
|
# from m2r to make `mdinclude` work
|
||||||
|
app.add_config_value('no_underscore_emphasis', False, 'env')
|
||||||
|
app.add_config_value('m2r_parse_relative_links', False, 'env')
|
||||||
|
app.add_config_value('m2r_anonymous_references', False, 'env')
|
||||||
|
app.add_config_value('m2r_disable_inline_math', False, 'env')
|
||||||
|
app.add_directive('mdinclude', MdInclude)
|
1
doc/contributing.rst
Normal file
1
doc/contributing.rst
Normal file
@ -0,0 +1 @@
|
|||||||
|
.. mdinclude:: ../CONTRIBUTING.md
|
3
doc/graph.md
Normal file
3
doc/graph.md
Normal file
@ -0,0 +1,3 @@
|
|||||||
|
# Expression graphs
|
||||||
|
|
||||||
|
...
|
48
doc/index.rst
Normal file
48
doc/index.rst
Normal file
@ -0,0 +1,48 @@
|
|||||||
|
Welcome to Marian's documentation!
|
||||||
|
==================================
|
||||||
|
|
||||||
|
|buildgpu| |buildcpu| |tests| |release| |license|
|
||||||
|
|
||||||
|
Marian is an efficient and self-contained Neural Machine Translation framework with an integrated
|
||||||
|
automatic differentiation engine based on dynamic computation graphs, written entirely in C++.
|
||||||
|
|
||||||
|
This is developer documentation. User documentation is available at https://marian-nmt.github.io/docs/
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 2
|
||||||
|
:caption: Contents:
|
||||||
|
|
||||||
|
install
|
||||||
|
graph
|
||||||
|
operators
|
||||||
|
|
||||||
|
api/library_index
|
||||||
|
|
||||||
|
contributing
|
||||||
|
|
||||||
|
|
||||||
|
Indices and tables
|
||||||
|
------------------
|
||||||
|
|
||||||
|
* :ref:`genindex`
|
||||||
|
|
||||||
|
|
||||||
|
.. |buildgpu| image:: https://img.shields.io/jenkins/s/http/vali.inf.ed.ac.uk/jenkins/view/marian/job/marian-dev-cuda-10.1.svg?label=CUDAC%20Build
|
||||||
|
:target: http://vali.inf.ed.ac.uk/jenkins/job/marian-dev/
|
||||||
|
:alt: GPU build status
|
||||||
|
|
||||||
|
.. |buildcpu| image:: https://img.shields.io/jenkins/s/http/vali.inf.ed.ac.uk/jenkins/view/marian/job/marian-dev-cpu.svg?label=CPU%20Build
|
||||||
|
:target: http://vali.inf.ed.ac.uk/jenkins/job/marian-dev-cpu/
|
||||||
|
:alt: CPU build status
|
||||||
|
|
||||||
|
.. |tests| image:: https://img.shields.io/jenkins/s/http/vali.inf.ed.ac.uk/jenkins/view/marian/job/marian-regression-tests.svg?label=Tests
|
||||||
|
:target: http://vali.inf.ed.ac.uk/jenkins/job/marian-regression-tests/
|
||||||
|
:alt: Tests status
|
||||||
|
|
||||||
|
.. |release| image:: https://img.shields.io/github/release/marian-nmt/marian.svg?label=Release
|
||||||
|
:target: https://github.com/marian-nmt/marian/releases
|
||||||
|
:alt: Latest release
|
||||||
|
|
||||||
|
.. |license| image:: https://img.shields.io/badge/License-MIT-blue.svg
|
||||||
|
:target: ../LICENSE.md
|
||||||
|
:alt: License: MIT
|
3
doc/install.rst
Normal file
3
doc/install.rst
Normal file
@ -0,0 +1,3 @@
|
|||||||
|
Installation
|
||||||
|
============
|
||||||
|
|
35
doc/make.bat
Normal file
35
doc/make.bat
Normal file
@ -0,0 +1,35 @@
|
|||||||
|
@ECHO OFF
|
||||||
|
|
||||||
|
pushd %~dp0
|
||||||
|
|
||||||
|
REM Command file for Sphinx documentation
|
||||||
|
|
||||||
|
if "%SPHINXBUILD%" == "" (
|
||||||
|
set SPHINXBUILD=sphinx-build
|
||||||
|
)
|
||||||
|
set SOURCEDIR=source
|
||||||
|
set BUILDDIR=build
|
||||||
|
|
||||||
|
if "%1" == "" goto help
|
||||||
|
|
||||||
|
%SPHINXBUILD% >NUL 2>NUL
|
||||||
|
if errorlevel 9009 (
|
||||||
|
echo.
|
||||||
|
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
|
||||||
|
echo.installed, then set the SPHINXBUILD environment variable to point
|
||||||
|
echo.to the full path of the 'sphinx-build' executable. Alternatively you
|
||||||
|
echo.may add the Sphinx directory to PATH.
|
||||||
|
echo.
|
||||||
|
echo.If you don't have Sphinx installed, grab it from
|
||||||
|
echo.http://sphinx-doc.org/
|
||||||
|
exit /b 1
|
||||||
|
)
|
||||||
|
|
||||||
|
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
|
||||||
|
goto end
|
||||||
|
|
||||||
|
:help
|
||||||
|
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
|
||||||
|
|
||||||
|
:end
|
||||||
|
popd
|
3
doc/operators.md
Normal file
3
doc/operators.md
Normal file
@ -0,0 +1,3 @@
|
|||||||
|
# Graph operations
|
||||||
|
|
||||||
|
...
|
6
doc/requirements.txt
Normal file
6
doc/requirements.txt
Normal file
@ -0,0 +1,6 @@
|
|||||||
|
sphinx==2.4.4
|
||||||
|
breathe==4.13.0
|
||||||
|
exhale
|
||||||
|
sphinx_rtd_theme
|
||||||
|
recommonmark
|
||||||
|
m2r
|
Loading…
Reference in New Issue
Block a user