Building and Updating MXNet Documentation

The website is hosted at http://mxnet.incubator.apache.org/. http://mxnet.io redirects to this site and advised to use links with http://mxnet.incubator.apache.org/ instead of http://mxnet.io/.

MXNet Documentation Website is built with Sphinx and a variety of plugins including pandoc, recommonmark, a custom Sphinx plugin (mxdoc.py).

How to Build the MXNet Website for Development and QA

Using make docs from the MXNet root is the quickest way to generate the MXNet API docs and the website, as long as you already have all of the dependencies installed. This method automatically generates each API, except the Perl and R APIs.

Easy docs setup for Ubuntu: Run the following on Ubuntu 16.04 to install all MXNet and docs dependencies and to build MXNet from source. Then issue the make docs command from the source root to build the docs.

git clone --recursive https://github.com/apache/incubator-mxnet.git mxnet
cd mxnet/docs/build_version_doc
./setup_docs_ubuntu.sh
cd ../../
make docs USE_OPENMP=1

For more information on each API's documentation dependencies, how to serve the docs, or how to build the full website with each legacy MXNet version, refer to the following links:

• Dependencies - required before you build the docs
• Developer Build Instructions - build your local branch
• Full Site Build Instructions - build the latest commits to the official branches

File Structure

• Static files such as css, javascript and html templates are under the _static folder:

  • Javascript files are under _static/js folder
  • Layout templates and landing page html file are under _static/mxnet-theme folder
  • _static/mxnet.css contains all MXNet website styles

• Page contents originate as markdown files. Sphinx converts markdown files to html through an rst intermediate format. Each content folder should contain an index file as landing page.

• There are some utility scripts to help building website, such as mxdoc.py and build_version_doc/. They are used to manipulate website contents during building. Refer to Developer Build Instructions for more information.

Production Website Deployment Process

Apache Jenkins MXNet website building job is used to build MXNet website.

The Jenkins docs build job will fetch MXNet repository, build MXNet website and push all static files to host repository. The host repo is hooked with Apache gitbox to host website.

Process for Running the Docs Build Job

1. Login to Jenkins.
2. View the pipeline currently called restricted website build.
3. Click Build with Parameters.
4. Use the defaults, or change the domain to be your staging server's IP/DNS web address.
5. Wait about 20-30 minutes while it builds the full site.
6. On your staging server, clone the mxnet site repo.
7. When you ran restricted website build it followed up with restricted website publish which pushed the changes to the incubator-mxnet-site repo.
8. Make sure you git pull if you had already cloned the site repo before this first run-through.
9. Copy the files to your webroot. For more info on this see the developer instructions for docs build.
10. Preview the site on your staging server. Note, use the domain default before you try to use this for production, but using your own is helpful for QA'ing the site.

Build Versioning Website

IMPORTANT: Refer to Full Site Build Instructions for a working site build with the versions dropdown in the UI.

Other Build Processes

• Perl API docs are maintained separately at metacpan.
• R API docs building must be triggered manually. The function for generating these automatically was disabled in the nightly builds. You may run the R docs build process in a local docs build by uncommenting the function call in mxdoc.py.

Troubleshooting

• If C++ code has been changed, remove the previous results to trigger the rebuild for all pages. To do this, run make clean_docs.
• If C++ code fails to build, run make clean.
• If CSS or javascript are changed, clear the cache in the browser with a forced refresh.
• If search doesn't work, run make clean and then make docs.