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

Setup and Configuration¶

Clone the repository:

git clone git://github.com/mongodb/docs.git

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.