/
build.txt
149 lines (97 loc) · 3.88 KB
/
build.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
==================================
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 <https://pypi.python.org/pypi/giza>`_
OS X
````
Install Sphinx, Docutils, and their dependencies with ``easy_install``
the following command:
.. code-block:: sh
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 <http://inkscape.org/download/>`_.
.. 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 <http://www.tug.org/mactex/2011/>`_. This
is **only** required to build PDFs.
Arch Linux
``````````
Install packages from the system repositories with the following command:
.. code-block:: sh
pacman -S inkscape python2-pip
Then install the following Python packages:
.. code-block:: sh
pip2 install giza
.. optional::
To generate PDFs for the full production build, install the
following packages from the system repository:
.. code-block:: sh
pacman -S texlive-bin texlive-core texlive-latexextra
Debian/Ubuntu
`````````````
Install the required system packages with the following command:
.. code-block:: sh
apt-get install inkscape python-pip
Then install the following Python packages:
.. code-block:: sh
pip install giza
.. optional::
To generate PDFs for the full production build, install the
following packages from the system repository:
.. code-block:: sh
apt-get install texlive-latex-recommended texlive-latex-recommended
Setup and Configuration
~~~~~~~~~~~~~~~~~~~~~~~
Clone the repository:
.. code-block:: sh
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:
.. code-block:: sh
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.