You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/builds.rst
+58-33
Original file line number
Diff line number
Diff line change
@@ -15,38 +15,38 @@ Our current build limits are:
15
15
We can increase build limits on a per-project basis,
16
16
if you provide a good reason your documentation needs more resources.
17
17
18
-
You can see the current Docker build images that we use in our `docker repository <https://github.com/rtfd/readthedocs-docker-images>`_. `Docker Hub <https://hub.docker.com/r/readthedocs/build/>`_ also shows the latest set of images that have been built.
18
+
You can see the current Docker build images that we use in our `docker
<https://hub.docker.com/r/readthedocs/build/>`_ also shows the latest set of
21
+
images that have been built.
19
22
20
-
Currently in production we're using the ``readthedocs/build:2.0`` docker image as our default image.
23
+
Currently in production we're using the ``readthedocs/build:2.0`` docker image
24
+
as our default image.
21
25
22
26
How we build documentation
23
27
--------------------------
24
28
25
-
When we import your documentation, we look at two things first: your *Repository URL* and the *Documentation Type*.
26
-
We will clone your repository,
29
+
When we import your documentation, we look at two things first: your
30
+
*Repository URL* and the *Documentation Type*. We will clone your repository,
27
31
and then build your documentation using the *Documentation Type* specified.
28
32
29
33
Sphinx
30
34
~~~~~~
31
35
32
-
When you choose *Sphinx* as your *Documentation Type*,
33
-
we will first look for a ``conf.py`` file in your repository.
34
-
If we don't find one,
35
-
we will generate one for you.
36
-
We will look inside a ``doc`` or ``docs`` directory first,
37
-
and then look within your entire project.
36
+
When you choose *Sphinx* as your *Documentation Type*, we will first look for a
37
+
``conf.py`` file in your repository. If we don't find one, we will generate one
38
+
for you. We will look inside a ``doc`` or ``docs`` directory first, and then
39
+
look within your entire project.
38
40
39
41
Then Sphinx will build any files with an ``.rst`` extension.
40
42
41
43
Mkdocs
42
44
~~~~~~
43
45
44
-
When you choose *Mkdocs* as your *Documentation Type*,
45
-
we will first look for a ``mkdocs.yml`` file in your repository.
46
-
If we don't find one,
47
-
we will generate one for you.
48
-
We will look inside a ``doc`` or ``docs`` directory first,
49
-
and then default to the top-level of your documentation.
46
+
When you choose *Mkdocs* as your *Documentation Type*, we will first look for a
47
+
``mkdocs.yml`` file in your repository. If we don't find one, we will generate
48
+
one for you. We will look inside a ``doc`` or ``docs`` directory first, and
49
+
then default to the top-level of your documentation.
50
50
51
51
Then Mkdocs will build any files with an ``.md`` extension. As MkDocs doesn't
52
52
support automatic PDF generation, Read the Docs cannot create a PDF version of
@@ -55,17 +55,27 @@ your documentation with the *Mkdocs* option.
55
55
Understanding what's going on
56
56
-----------------------------
57
57
58
-
Understanding how Read the Docs builds your project will help you with debugging the problems you have with the site. It should also allow you to take advantage of certain things that happen during the build process.
58
+
Understanding how Read the Docs builds your project will help you with
59
+
debugging the problems you have with the site. It should also allow you to take
60
+
advantage of certain things that happen during the build process.
59
61
60
-
The first step of the process is that we check out your code from the repository you have given us. If the code is already checked out, we update the copy to the branch that you have specified in your projects configuration.
62
+
The first step of the process is that we check out your code from the
63
+
repository you have given us. If the code is already checked out, we update the
64
+
copy to the branch that you have specified in your projects configuration.
61
65
62
-
Then we build the proper backend code for the type of documentation you've selected.
66
+
Then we build the proper backend code for the type of documentation you've
67
+
selected.
63
68
64
-
If you have the *Install Project* option enabled, we will run ``setup.py install`` on your package, installing it into a virtual environment. You can also define additional packages to install with the *Requirements File* option.
69
+
If you have the *Install Project* option enabled, we will run ``setup.py
70
+
install`` on your package, installing it into a virtual environment. You can
71
+
also define additional packages to install with the *Requirements File* option.
65
72
66
-
When we build your documentation, we run `sphinx-build -b html . _build/html`, where `html` would be replaced with the correct backend. We also create man pages and pdf's automatically based on your project.
73
+
When we build your documentation, we run `sphinx-build -b html . _build/html`,
74
+
where `html` would be replaced with the correct backend. We also create man
75
+
pages and pdf's automatically based on your project.
67
76
68
-
Then these files are copied across to our application servers from the build server. Once on the application servers, they are served from nginx.
77
+
Then these files are copied across to our application servers from the build
78
+
server. Once on the application servers, they are served from nginx.
69
79
70
80
An example in code:
71
81
@@ -84,16 +94,20 @@ Builder Responsibility
84
94
----------------------
85
95
86
96
Builders have a very specific job.
87
-
They take the updated source code and generate the correct artifacts.
88
-
The code lives in ``self.version.project.checkout_path(self.version.slug)``.
89
-
The artifacts should end up in ``self.version.project.artifact_path(version=self.version.slug, type=self.type)``
90
-
Where ``type`` is the name of your builder.
91
-
All files that end up in the artifact directory should be in their final form.
97
+
They take the updated source code and generate the correct artifacts. The code
98
+
lives in ``self.version.project.checkout_path(self.version.slug)``.
Where ``type`` is the name of your builder. All files that end up in the
102
+
artifact directory should be in their final form.
92
103
93
104
Packages installed in the build environment
94
105
-------------------------------------------
95
106
96
-
The build server does have a select number of C libraries installed, because they are used across a wide array of python projects. We can't install every C library out there, but we try and support the major ones. We currently have the following libraries installed:
107
+
The build server does have a select number of C libraries installed, because
108
+
they are used across a wide array of python projects. We can't install every C
109
+
library out there, but we try and support the major ones. We currently have the
110
+
following libraries installed:
97
111
98
112
* doxygen
99
113
* LaTeX (texlive-full)
@@ -106,11 +120,17 @@ The build server does have a select number of C libraries installed, because the
106
120
Writing your own builder
107
121
------------------------
108
122
109
-
.. note:: Builds happen on a server using only the RTD Public API. There is no reason that you couldn't build your own independent builder that wrote into the RTD namespace. The only thing that is currently unsupported there is a saner way than uploading the processed files as a zip.
123
+
.. note:: Builds happen on a server using only the RTD Public API. There is no
124
+
reason that you couldn't build your own independent builder that wrote into
125
+
the RTD namespace. The only thing that is currently unsupported there is a
126
+
saner way than uploading the processed files as a zip.
110
127
111
-
The documentation build system in RTD is made pluggable, so that you can build out your own backend. If you have a documentation format that isn't currently supported, you can add support by contributing a backend.
128
+
The documentation build system in RTD is made pluggable, so that you can build
129
+
out your own backend. If you have a documentation format that isn't currently
130
+
supported, you can add support by contributing a backend.
112
131
113
-
The :doc:`api/doc_builder` API explains the higher level parts of the API that you need to implement. A basic run goes something like this::
132
+
The :doc:`api/doc_builder` API explains the higher level parts of the API that
133
+
you need to implement. A basic run goes something like this::
114
134
115
135
backend = get_backend(project.documentation_type)
116
136
if force:
@@ -123,12 +143,17 @@ The :doc:`api/doc_builder` API explains the higher level parts of the API that y
123
143
Deleting a stale or broken build environment
124
144
--------------------------------------------
125
145
126
-
If you're having trouble getting your version to build, try wiping out the existing build/environment files. On your version list page ``/projects/[project]/versions`` there is a "Wipe" button that will remove all of the files associated with your documentation build, but not the documentation itself.
146
+
If you're having trouble getting your version to build, try wiping out the
147
+
existing build/environment files. On your version list page
148
+
``/projects/[project]/versions`` there is a "Wipe" button that will remove all
149
+
of the files associated with your documentation build, but not the
150
+
documentation itself.
127
151
128
152
Build environment
129
153
-----------------
130
154
131
-
The *Sphinx* and *Mkdocs* builders set the following RTD-specific environment variables when building your documentation:
155
+
The *Sphinx* and *Mkdocs* builders set the following RTD-specific environment
0 commit comments