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:
- GNU Make
- GNU Tar
- Python
- Git
- Sphinx (documentation management toolchain)
- Pygments (syntax highlighting)
- PyYAML (for the generated tables)
- Droopy (Python package for static text analysis)
- Fabric (Python package for scripting and orchestration)
- Inkscape (Image generation.)
- python-argparse (For Python 2.6.)
- LaTeX/PDF LaTeX (typically texlive; for building PDFs)
- Common Utilities (rsync, tar, gzip, sed)
OS X¶
Install Sphinx, Docutils, and their dependencies with easy_install the following command:
easy_install Sphinx Jinja2 Pygments docutils PyYAML droopy fabric
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 python2-sphinx python2-yaml inkscape python2-pip
Then install the following Python packages:
pip install droopy fabric
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 python-sphinx python-yaml python-argparse inkscape python-pip
Then install the following Python packages:
pip install droopy fabric
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
Then run the bootstrap.py script in the docs/ repository, to configure the build dependencies:
python bootstrap.py
This downloads and configures the mongodb/docs-tools repository, which contains the authoritative build system shared between branches of the MongoDB Manual and other MongoDB documentation projects.
You can run bootstrap.py regularly to update build system.
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.
Build Mechanics and Tools¶
Internally the build system has a number of components and processes. See the docs-tools README for more information on the internals. This section documents a few of these components from a very high level and lists useful operations for contributors to the documentation.
Fabric¶
Fabric is an orchestration and scripting package for Python. The documentation uses Fabric to handle the deployment of the build products to the web servers and also unifies a number of independent build operations. Fabric commands have the following form:
fab <module>.<task>[:<argument>]
The <argument> is optional in most cases. Additionally some tasks are available at the root level, without a module. To see a full list of fabric tasks, use the following command:
fab -l
You can chain fabric tasks on a single command line, although this doesn’t always make sense.
Important fabric tasks include:
- tools.bootstrap
- Runs the bootstrap.py script. Useful for re-initializing the repository without needing to be in root of the repository.
- tools.dev; tools.reset
- tools.dev switches the origin remote of the docs-tools checkout in build directory, to ../docs-tools to facilitate build system testing and development. tools.reset resets the origin remote for normal operation.
- tools.conf
- tools.conf returns the content of the configuration object for the current project. These data are useful during development.
- stats.report:<filename>
- Returns, a collection of readability statistics. Specify file names relative to source/ tree.
- make
- Provides a thin wrapper around Make calls. Allows you to start make builds from different locations in the project repository.
- process.refresh_dependencies
- Updates the time stamp of .txt source files with changed include files, to facilitate Sphinx’s incremental rebuild process. This task runs internally as part of the build process.
Buildcloth¶
Buildcloth is a meta-build tool, used to generate Makefiles programmatically. This makes the build system easier to maintain, and makes it easier to use the same fundamental code to generate various branches of the Manual as well as related documentation projects. See makecloth/ in the docs-tools repository for the relevant code.
Running make with no arguments will regenerate these parts of the build system automatically.
Rstcloth¶
Rstcloth is a library for generating reStructuredText programmatically. This makes it possible to generate content for the documentation, such as tables, tables of contents, and API reference material programmatically and transparently. See rstcloth/ in the docs-tools repository for the relevant code.