MongoDB Documentation Build System¶
This document contains more direct instructions for building the MongoDB documentation.
Getting Started¶
Install Dependencies¶
The MongoDB Documentation project depends on the following tools:
- Python
- Git
- Inkscape (Image generation.)
- LaTeX/PDF LaTeX (typically texlive; for building PDFs)
- Giza
OS X¶
Install Sphinx, Docutils, and their dependencies with easy_install the following command:
easy_install giza
Feel free to use pip rather than easy_install to install python packages.
To generate the images used in the documentation, download and install Inkscape.
Optional
To generate PDFs for the full production build, install a TeX distribution (for building the PDF.) If you do not have a LaTeX installation, use MacTeX. This is only required to build PDFs.
Arch Linux¶
Install packages from the system repositories with the following command:
pacman -S inkscape python2-pip
Then install the following Python packages:
pip2 install giza
Optional
To generate PDFs for the full production build, install the following packages from the system repository:
pacman -S texlive-bin texlive-core texlive-latexextra
Debian/Ubuntu¶
Install the required system packages with the following command:
apt-get install inkscape python-pip
Then install the following Python packages:
pip install giza
Optional
To generate PDFs for the full production build, install the following packages from the system repository:
apt-get install texlive-latex-recommended texlive-latex-recommended
Building the Documentation¶
The MongoDB documentation build system is entirely accessible via make targets. For example, to build an HTML version of the documentation issue the following command:
make html
You can find the build output in build/<branch>/html, where <branch> is the name of the current branch.
In addition to the html target, the build system provides the following targets:
- publish
- Builds and integrates all output for the production build. Build output is in build/public/<branch>/. When you run publish in the master, the build will generate some output in build/public/.
- push; stage
- Uploads the production build to the production or staging web servers. Depends on publish. Requires access production or staging environment.
- push-all; stage-all
- Uploads the entire content of build/public/ to the web servers. Depends on publish. Not used in common practice.
- push-with-delete; stage-with-delete
- Modifies the action of push and stage to remove remote file that don’t exist in the local build. Use with caution.
- html; latex; dirhtml; epub; texinfo; man; json
These are standard targets derived from the default Sphinx Makefile, with adjusted dependencies. Additionally, for all of these targets you can append -nitpick to increase Sphinx’s verbosity, or -clean to remove all Sphinx build artifacts.
latex performs several additional post-processing steps on .tex output generated by Sphinx. This target will also compile PDFs using pdflatex.
html and man also generates a .tar.gz file of the build outputs for inclusion in the final releases.