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
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
|
Pylons Sphinx Themes
====================
This repository is a Python package that contains Sphinx themes for
Pylons related projects. This project is based on [Pylons Sphinx
Theme](https://github.com/Pylons/pylons_sphinx_theme) (singular), but
uses a package implementation instead of git submodules and manual
steps.
To use a theme in your Sphinx documentation, follow this guide.
Edit your project\'s `setup.py`
-------------------------------
1. Add `pylons-sphinx-themes` to your project\'s requirements in its
`setup.py`. Here\'s an example from Pyramid.
``` {.sourceCode .python}
docs_extras = [
'Sphinx >= 1.7.5', # Read The Docs minimum version
'docutils',
'repoze.sphinx.autointerface',
'pylons-sphinx-themes',
]
```
Edit your Sphinx\'s `conf.py`
-----------------------------
1. Near the top, add the following.
``` {.sourceCode .python}
import pylons_sphinx_themes
```
2. Activate the theme.
``` {.sourceCode .python}
html_theme = 'pyramid'
html_theme_path = pylons_sphinx_themes.get_html_themes_path()
```
3. (Recommended) Enable [Ethical
Ads](https://docs.readthedocs.io/en/latest/advertising/ethical-advertising.html).
Doing so supports both [Read the Docs](https://readthedocs.org/) and
the [Python Software
Foundation](https://www.python.org/psf-landing/) with ad revenue.
``` {.sourceCode .python}
# Control display of sidebars
html_sidebars = { '**': [
'localtoc.html',
'ethicalads.html',
'relations.html',
'sourcelink.html',
'searchbox.html',
] }
```
4. If you were previously using the git submodule method to use the
Pylons theme, then comment or delete the block of code under the
following statement.
``` {.sourceCode .python}
# Add and use Pylons theme
if 'sphinx-build' in ' '.join(sys.argv): # protect against dumb importers
```
5. (Optional) Set a canonical root URL. The URL points to the root of
the documentation, and requires a trailing slash.
``` {.sourceCode .python}
html_theme_options = dict(
canonical_url='http://the_root_domain/latest/docs/'
)
```
Undo git submodule method
-------------------------
If you were previously using the git submodule method to use the Pylons
theme, then perform the following additional steps.
1. Remove `.gitmodules`.
``` {.sourceCode .bash}
cd <your_project_directory>
git rm .gitmodules
```
2. Deinitialize the submodule.
``` {.sourceCode .bash}
cd docs/_themes
git submodule deinit .
```
3. Remove the submodule\'s directory.
``` {.sourceCode .bash}
cd ..
git rm _themes/
```
4. Edit your Sphinx\'s `Makefile`. The following is an [example
diff](https://github.com/Pylons/pyramid/pull/1636/files) from
Pyramid.
``` {.sourceCode .diff}
-html: themes
+html:
# ...
-htmlhelp: themes
+htmlhelp:
#...
-themes:
- cd ..; git submodule update --init --recursive; cd docs;
```
Update `tox.ini`
----------------
If you use tox, you can specify dependencies for building your docs
either in your `setup.py` (preferred) or in your `tox.ini`
(duplicitous). See the [example from
Pyramid](https://github.com/Pylons/pyramid/blob/master/setup.py#L58-L64).
``` {.sourceCode .ini}
docs_extras = [
'Sphinx >= 1.7.5',
'docutils',
'repoze.sphinx.autointerface',
'pylons_sphinx_latesturl',
'pylons-sphinx-themes',
]
# ...
extras_require = {
'testing':testing_extras,
'docs':docs_extras,
},
```
Otherwise you can repeat yourself and edit your `tox.ini`. The following
example is from
[waitress](https://github.com/Pylons/waitress/blob/master/tox.ini#L28).
``` {.sourceCode .ini}
deps =
Sphinx
repoze.sphinx.autointerface
pylons-sphinx-themes
```
Update Read the Docs configuration
----------------------------------
If you specify package requirements for Read the Docs, specify
dependencies in your `rtd.txt`. You can either name them explicitly,
which might be duplicitous:
``` {.sourceCode .text}
pylons-sphinx-themes
```
or you can rely on your `setup.py` configuration, specifying
dependencies in only one place, by simply using this in your `rtd.txt`.
``` {.sourceCode .text}
-e .[docs]
```
Available themes
----------------
- **pylons** - the generic Pylons Project documentation theme
- **pyramid** - the specific Pyramid documentation theme
- **pylonsfw** - the specific Pylons Framework documentation theme
|
