MXNet Documentation Website is built with sphinx 1.5.1.
A built version of document is available at http://mxnet.io
To build the documents locally, we need to first install docker. Then use the following commands to clone and build the documents.
git clone --recursive https://github.com/apache/incubator-mxnet.git mxnet cd mxnet && make docs
In case docker method is not available, there is an alternate method:
sudo pip install sphinx==1.5.1 CommonMark==0.5.4 breathe mock==1.0.1 recommonmark pypandoc cd mxnet/docs && make html USE_OPENMP=0
The results will be available at
make cleanand rebuild.
_static/mxnet.csscontains all MXNet website styles.
Sphinx converts markdowns files to html. Page contents are markdown files. Each content folder contains an index file as landing page.
There are some utility scripts to help building website, such as
build_version_doc/. They are used to manipulate website contents during building.
Apache Jenkins MXNet website building job is used to build MXNet website. There are two ways to trigger this job. First is nightly build for master branch. Second is manually trigger job when a new version is released. This will build for new version.
make docs doesn't add any version information. Version information is added by Apache Jenkins MXNet website building job. Landing page will point to the latest released version. Older versions and master version are placed under versions folder. After completing website update and testing it locally, we also need to build and test versioning website.
Python Beautifulsoup is the dependency:
sudo pip install beautifulsoup4
The essenitial part of adding version is to use
AddPackageLink.py to add Apache source packages and
AddVersion.py to update all version related information on website. These two scripts are used in
build_doc.sh is used by Apache Jenkins MXNet webiste building job to incremental adding version. We don't need it for local website development.
build_all_version.sh is to rebuild versioning website locally and is useful to verify versioning website locally. We need to specify which versions to be built. This can be set in
tag_list variable at the beginning of the script. Version order should be from latest to oldest and placing master at the end. We may also want to modify
mxnet_url variable to our own repository for local testing. Another use case is to completely rebuild website with specific versions. Although this will not happen often, we can use it to rebuld whole website and push to host repo.
AddVersion.py depends on Beautiful library, which requires target html files to have close tags. Although open tag html can still be rendered by browser, it will be problematic for Beautifulsoup.
AddPackageLink.py manipulates contents for website. If there are layout changes, it may break these two scripts. We need to change scripts respectively.