Navigation

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.