Building and Updating MXNet Documentation
How to Build the MXNet Website for Development and QA
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 SPHINXOPTS=-W
OpenMP speeds things up and will work on Ubuntu if you used the
-W Sphinx option enforces "warnings as errors". This will help you debug your builds and get them through CI.
CI will not let a PR through if it breaks the website. Refer to the MXNet Developer wiki's documentation guide for troubleshooting tips.
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
- Layout templates and landing page html file are under
_static/mxnet.csscontains all MXNet website styles
Page contents originate as markdown files. Sphinx converts markdown files to html through an
rstintermediate format. Each content folder should contain 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. Refer to Developer Build Instructions for more information.
Production Website Deployment Process
Apache Jenkins MXNet website building job is used to build MXNet website.
Process for Running the Docs Build Job
- Login to Jenkins.
- View the pipeline currently called
restricted website build.
Build with Parameters.
- Use the defaults, or change the domain to be your staging server's IP/DNS web address.
- Wait about 20-30 minutes while it builds the full site.
- On your staging server, clone the mxnet site repo.
- When you ran
restricted website buildit followed up with
restricted website publishwhich pushed the changes to the incubator-mxnet-site repo.
- Make sure you git pull if you had already cloned the site repo before this first run-through.
- Copy the files to your webroot. For more info on this see the developer instructions for docs build.
- 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.
- If C++ code has been changed, remove the previous results to trigger the rebuild for all pages. To do this, run
- If C++ code fails to build, run
- If search doesn't work, run
make cleanand then