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/faq.rst
+38-13
Original file line number
Diff line number
Diff line change
@@ -4,9 +4,15 @@ Frequently Asked Questions
4
4
My project isn't building with autodoc
5
5
--------------------------------------
6
6
7
-
First, you should check out the Builds tab of your project. That records all of the build attempts that RTD has made to build your project. If you see ``ImportError`` messages for custom Python modules, you should enable the virtualenv feature in the Admin page of your project, which will install your project into a virtualenv, and allow you to specify a ``requirements.txt`` file for your project.
7
+
First, you should check out the Builds tab of your project. That records all of
8
+
the build attempts that RTD has made to build your project. If you see
9
+
``ImportError`` messages for custom Python modules, you should enable the
10
+
virtualenv feature in the Admin page of your project, which will install your
11
+
project into a virtualenv, and allow you to specify a ``requirements.txt`` file
12
+
for your project.
8
13
9
-
If you are still seeing errors because of C library dependencies, please see the below section about that.
14
+
If you are still seeing errors because of C library dependencies, please see
15
+
the below section about that.
10
16
11
17
How do I change my slug (the URL your docs are served at)?
Another use case for this is when you have a module with a C extension.
64
70
65
-
This happens because our build system doesn't have the dependencies for building your project. This happens with things like libevent and mysql, and other python things that depend on C libraries. We can't support installing random C binaries on our system, so there is another way to fix these imports.
71
+
This happens because our build system doesn't have the dependencies for
72
+
building your project. This happens with things like libevent and mysql, and
73
+
other python things that depend on C libraries. We can't support installing
74
+
random C binaries on our system, so there is another way to fix these imports.
66
75
67
-
You can mock out the imports for these modules in your ``conf.py`` with the following snippet::
76
+
You can mock out the imports for these modules in your ``conf.py`` with the
77
+
following snippet::
68
78
69
79
import sys
70
80
from unittest.mock import MagicMock
@@ -79,12 +89,15 @@ You can mock out the imports for these modules in your ``conf.py`` with the foll
79
89
80
90
Of course, replacing `MOCK_MODULES` with the modules that you want to mock out.
81
91
82
-
.. Tip:: The library ``unittest.mock`` was introduced on python 3.3. On earlier versions install the ``mock`` library
83
-
from PyPI with (ie ``pip install mock``) and replace the above import::
92
+
.. Tip:: The library ``unittest.mock`` was introduced on python 3.3. On earlier
93
+
versions install the ``mock`` library from PyPI with (ie ``pip install
94
+
mock``) and replace the above import::
84
95
85
96
from mock import Mock as MagicMock
86
97
87
-
If such libraries are installed via ``setup.py``, you also will need to remove all the C-dependent libraries from your ``install_requires`` in the RTD environment.
98
+
If such libraries are installed via ``setup.py``, you also will need to remove
99
+
all the C-dependent libraries from your ``install_requires`` in the RTD
100
+
environment.
88
101
89
102
`Client Error 401` when building documentation
90
103
----------------------------------------------
@@ -133,12 +146,19 @@ You can add subprojects in the Admin section for your project.
133
146
Where do I need to put my docs for RTD to find it?
Read the Docs will crawl your project looking for a ``conf.py``. Where it finds the ``conf.py``, it will run ``sphinx-build`` in that directory. So as long as you only have one set of sphinx documentation in your project, it should Just Work.
149
+
Read the Docs will crawl your project looking for a ``conf.py``. Where it finds
150
+
the ``conf.py``, it will run ``sphinx-build`` in that directory. So as long as
151
+
you only have one set of sphinx documentation in your project, it should Just
152
+
Work.
137
153
138
154
I want to use the Blue/Default Sphinx theme
139
155
-------------------------------------------
140
156
141
-
We think that our theme is badass, and better than the default for many reasons. Some people don't like change though :), so there is a hack that will let you keep using the default theme. If you set the ``html_style`` variable in your ``conf.py``, it should default to using the default theme. The value of this doesn't matter, and can be set to ``/default.css`` for default behavior.
157
+
We think that our theme is badass, and better than the default for many
158
+
reasons. Some people don't like change though :), so there is a hack that will
159
+
let you keep using the default theme. If you set the ``html_style`` variable in
160
+
your ``conf.py``, it should default to using the default theme. The value of
161
+
this doesn't matter, and can be set to ``/default.css`` for default behavior.
142
162
143
163
I want to use the Read the Docs theme locally
144
164
---------------------------------------------
@@ -149,12 +169,15 @@ Simply follow the instructions in the README.
149
169
Image scaling doesn't work in my documentation
150
170
-----------------------------------------------
151
171
152
-
Image scaling in docutils depends on PIL. PIL is installed in the system that RTD runs on. However, if you are using the virtualenv building option, you will likely need to include PIL in your requirements for your project.
172
+
Image scaling in docutils depends on PIL. PIL is installed in the system that
173
+
RTD runs on. However, if you are using the virtualenv building option, you will
174
+
likely need to include PIL in your requirements for your project.
153
175
154
176
I want comments in my docs
155
177
--------------------------
156
178
157
-
RTD doesn't have explicit support for this. That said, a tool like `Disqus`_ (and the `sphinxcontrib-disqus`_ plugin) can be used for this purpose on RTD.
179
+
RTD doesn't have explicit support for this. That said, a tool like `Disqus`_
180
+
(and the `sphinxcontrib-disqus`_ plugin) can be used for this purpose on RTD.
We deploy readthedocs.org from the `rel` branch in our GitHub repository. You can see the latest commits that have been deployed by looking on GitHub: https://github.com/rtfd/readthedocs.org/commits/rel
245
+
We deploy readthedocs.org from the `rel` branch in our GitHub repository. You
246
+
can see the latest commits that have been deployed by looking on GitHub:
0 commit comments