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
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
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:
- Layout templates and landing page html file are under
_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
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
- 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 build it followed up with
restricted website publish which 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 clean and then