Google Git
Sign in
apache / mxnet / refs/heads/conan / . / docs
tree: 4133cf032e97f07df2647c8e1e5098fe8edd8190 [path history] [tgz]
  1. _static/
  2. api/
  3. architecture/
  4. build_version_doc/
  5. community/
  6. faq/
  7. gluon/
  8. install/
  9. model_zoo/
  10. tutorial_utils/
  11. tutorials/
  12. .dockerignore
  13. .gitignore
  14. conf.py
  15. Dockerfile
  16. Doxyfile
  17. index.md
  18. Jenkinsfile
  19. Jenkinsfile-dev
  20. Makefile
  21. mxdoc.py
  22. README.md
  23. settings.ini
docs/README.md

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 SPHINXOPTS=-W

OpenMP speeds things up and will work on Ubuntu if you used the setup_docs_ubuntu.sh script. 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:

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.