Detailed information on website development, continuous integration, and proposals for future projects can be found on the MXNet Wiki.
The website is built using Jekyll. You may run your own version of the static website by following the instructions on the wiki.
Each language documentation is built in a modular way, so that if you are a contributor to Julia, for example, you only need Julia-related tools to build it. Each language API has a section on installation and building along with how to build the docs locally.
You can also use the project's CI tools to emulate any changes with Docker. You can use these tools to install dependencies and run the parts of the build you want to test.
Refer to the MXNet Developer Wiki for instructions on building the docs locally.
If you plan to contribute changes to the documentation or website, please submit a pull request. Contributions are welcome!
More information on the dependencies can be found in the CI folder's installation scripts.
You can run just the Python docs by following the instructions in the Python API guide.
The docs are hosted on the website in each language API's section. You can find installation and build instructions there.
miniconda is recommended.
If you only need to make changes to tutorials or other pages that are not generated from one of the API source code folders, then you can use a basic Python pip or conda installation. But if you want edit the API source and have the reference API docs update, you also need to build MXNet from source. Refer to the build from source instructions for this requirement.
As this is maintained for CI, Ubuntu is recommended. Refer to ubuntu_doc.sh for the latest install script.
Note that without a GPU you will not be able to generate the docs with the outputs in the tutorials.
To run the full build, including tests of all tutorials, you will need at least two GPUs. Distributed training is a key feature of MXNet, so multiple GPUs are required for running through every tutorial.
mxnet. (There is no CUDA package for mac anyway.)
If you have a GPU and have installed CUDA 9.2 you can leave the MXNet dependency alone. Otherwise, in the
Install recommended software:
git bashterminal with Admin rights
choco to install make
condacommands should work in
Run the following commands from the project root (
new-docs) to setup the environment.
conda env create -f environment.yml source activate mxnet-docs
To build without GPUs and without testing the notebooks (faster):
To build with testing the notebooks (requires GPU):
The build docs will be available at
Each build may take a few minutes even without evaluation. To accelerate it, we can use one of the following ways:
build/conf.py, add the folders you want to skip into
exclude_patterns, such as
exclude_patterns = ['templates', 'api', 'develop', 'blog'].
mv api /tmp/, and then
To run a server to see the website:
cd build/_build/html; python -m http.server
ssh -L8000:localhost:8000 your_machine
In addition to view the built html pages, you can run the Jupyter notebook from a remote machine.
pip install https://github.com/mli/notedown/tarball/masterin remote server
jupyter notebook --NotebookApp.contents_manager_class='notedown.NotedownContentsManager'in remote server
ssh -L8888:localhost:8888 your_machine
Optionally, one can run the following to launch the notedown plugin automatically when starting jupyter notebook.
~/.jupyter/jupyter_notebook_config.pyif it is not existing by run
jupyter notebook --generate-config
c.NotebookApp.contents_manager_class = 'notedown.NotedownContentsManager'to
Dependencies and the setup steps for this website are changing often. Here are some troubleshooting tips.
conda env update -f environment.yml
-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.
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.
This information is maintained on the MXNet Wiki.
make cleanand then