8000 Use custom Sphinx theme for ePub generation · python/peps@be84045 · GitHub
[go: up one dir, main page]
Skip to content

Commit be84045

Browse files
AA-TurnerAA-Turner
committed
Use custom Sphinx theme for ePub generation
1 parent 37d9975 commit be84045

File tree

5 files changed

+300
-6
lines changed

5 files changed

+300
-6
lines changed

‎build.py

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -66,15 +66,14 @@ def create_index_file(html_root: Path, builder: str) -> None:
6666
if sphinx_builder == "epub":
6767
config_overrides |= {
6868
"master_doc": "contents-epub",
69+
"epub_theme": "pep_theme_epub",
70+
"templates_path": ["pep_sphinx_extensions/pep_theme_epub/templates"],
71+
"suppress_warnings": ["epub.unknown_project_files"],
72+
# epub metadata:
6973
"version": time.strftime("%Y-%m-%d"),
7074
"epub_copyright": "PSF",
7175
"epub_description": "Python Enhancement Proposals",
7276
"epub_author": "PEP Authors",
73-
# clear conflicting conf.py settings
74-
"html_theme_path": [],
75-
"html_theme": "epub",
76-
"html_style": None,
77-
"templates_path": [],
7877
}
7978

8079
app = Sphinx(

‎pep_sphinx_extensions/__init__.py

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,8 +39,15 @@ def _depart_maths():
3939

4040
def _update_config_for_builder(app: Sphinx):
4141
if app.builder.name == "dirhtml":
42+
# Docutils Node Visitor overrides (dirhtml builder)
43+
app.set_translator("dirhtml", pep_html_translator.PEPTranslator)
44+
45+
# PEP url overrides
4246
config.pep_url = f"../{config.pep_stem}"
4347
app.env.settings["pep_file_url_template"] = "../pep-%04d"
48+
elif app.builder.name == "epub":
49+
# Docutils Node Visitor overrides (epub builder)
50+
app.set_translator("epub", pep_html_translator.PEPTranslator)
4451

4552

4653
def setup(app: Sphinx) -> dict[str, bool]:
@@ -50,7 +57,6 @@ def setup(app: Sphinx) -> dict[str, bool]:
5057
app.add_source_parser(pep_parser.PEPParser) # Add PEP transforms
5158
app.add_role("pep", pep_role.PEPRole(), override=True) # Transform PEP references to links
5259
app.set_translator("html", pep_html_translator.PEPTranslator) # Docutils Node Visitor overrides (html builder)
53-
app.set_translator("dirhtml", pep_html_translator.PEPTranslator) # Docutils Node Visitor overrides (dirhtml builder)
5460
app.connect("env-before-read-docs", create_pep_zero) # PEP 0 hook
5561
app.connect("builder-inited", _update_config_for_builder) # Update configuration values for builder used
5662

‎pep_sphinx_extensions/pep_theme_epub/static/epub.css

Lines changed: 266 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,266 @@
1+
@charset "UTF-8";
2+
/* Styles for PEPs
3+
4+
Changes for ePub:
5+
- header line height reduced
6+
- horizontal line made invisible
7+
- ePub reading mode added
8+
- link target rules added
9+
- breadcrumbs and sidebar rules removed
10+
11+
Colours:
12+
white:
13+
background
14+
footnotes/references vertical border
15+
#333
16+
body text
17+
#888
18+
blockquote left line
19+
header breadcrumbs separator
20+
link underline (hovered/focussed)
21+
#ccc:
22+
scrollbar
23+
#ddd
24+
header bottom border
25+
horizontal rule
26+
table vertical border
27+
#eee:
28+
link underline
29+
table rows & top/bottom border
30+
PEP header rows
31+
footnotes/references rows
32+
admonition note background
33+
#f8f8f8:
34+
inline code background
35+
36+
#0072aa:
37+
links
38+
# fee:
39+
admonition warning background
40+
41+
*/
42+
43+
/* Set master rules */
44+
* {box-sizing: border-box}
45+
html {
46+
overflow-y: scroll;
47+
-webkit-font-smoothing: antialiased;
48+
margin: 0;
49+
line-height: 1.4rem;
50+
font-weight: normal;
51+
font-size: 1rem;
52+
font-family: "Source Sans Pro", Arial, sans-serif;
53+
}
54+
body {
55+
writing-mode: horizontal-tb;
56+
line-break: normal;
57+
-epub-writing-mode: horizontal-tb;
58+
-webkit-writing-mode: horizontal-tb;
59+
-epub-line-break: normal;
60+
-webkit-line-break: normal;
61+
margin: 0;
62+
color: #333;
63+
background-color: white;
64+
}
65+
section#pep-page-section {
66+
padding: 0.25rem 0.25rem 0;
67+
display: table;
68+
}
69+
70+
/* Reduce margin sizes for body text */
71+
p {margin: .5rem 0}
72+
73+
/* Header rules */
74+
h1.page-title {
75+
line-height: 2.3rem;
76+
font-size: 2rem;
77+
font-weight: bold;
78+
margin-top: 2rem;
79+
margin-bottom: 1.5rem;
80+
}
81+
h2 {
82+
font-size: 1.6rem;
83+
font-weight: bold;
84+
margin-top: 1rem;
85+
margin-bottom: .5rem;
86+
}
87+
h3 {
88+
font-size: 1.4rem;
89+
font-weight: normal;
90+
margin-top: 1rem;
91+
margin-bottom: 0.5rem;
92+
}
93+
h4 {
94+
font-size: 1.2rem;
95+
font-weight: normal;
96+
margin-top: .5rem;
97+
margin-bottom: 0;
98+
}
99+
h5,
100+
h6 {
101+
font-size: 1rem;
102+
font-weight: bold;
103+
margin-top: 0;
104+
margin-bottom: 0;
105+
}
106+
107+
/* Anchor link rules */
108+
a,
109+
a:active,
110+
a:visited {
111+
color: #0072aa;
112+
text-decoration-color: #eee;
113+
display: inline;
114+
}
115+
a:hover,
116+
a:focus {
117+
text-decoration-color: #888;
118+
}
119+
120+
/* Blockquote rules */
121+
blockquote {
122+
font-style: italic;
123+
border-left: 1px solid #888;
124+
margin: .5rem;
125+
padding: .5rem 1rem;
126+
}
127+
blockquote em {
128+
font-style: normal;
129+
}
130+
131+
cite {
132+
font-style: italic;
133+
}
134+
135+
/* Code rules (code literals and Pygments highlighting blocks) */
136+
pre,
137+
code {
138+
font-family: ui-monospace, "Cascadia Mono", "Segoe UI Mono", "DejaVu Sans Mono", Consolas, monospace;
139+
white-space: pre-wrap;
140+
word-wrap: break-word;
141+
-webkit-hyphens: none;
142+
hyphens: none;
143+
}
144+
code.literal {
145+
font-size: .8em;
146+
background-color: #f8f8f8;
147+
}
148+
pre {
149+
padding: .5rem .75rem;
150+
}
151+
152+
/* Definition list rules */
153+
dl dt {
154+
font-weight: bold;
155+
}
156+
dl dd {
157+
margin: 0;
158+
}
159+
160+
/* Horizontal rule rule */
161+
hr {
162+
display: none;
163+
}
164+
/*Image rules */
165+
img {
166+
max-width: 100%;
167+
}
168+
a img {
169+
display: block;
170+
margin: 0 auto;
171+
}
172+
173+
/* List rules */
174+
ul,
175+
ol {
176+
padding: 0;
177+
margin: 0 0 0 1.5rem;
178+
}
179+
ul {list-style: square}
180+
ol.arabic {list-style: decimal}
181+
ol.loweralpha {list-style: lower-alpha}
182+
ol.upperalpha {list-style: upper-alpha}
183+
ol.lowerroman {list-style: lower-roman}
184+
ol.upperroman {list-style: upper-roman}
185+
186+
/* Maths rules */
187+
sub,
188+
sup {
189+
font-size: .75em;
190+
line-height: 0;
191+
position: relative;
192+
vertical-align: baseline;
193+
}
194+
sup {top: -0.5em}
195+
sub {bottom: -0.25em}
196+
197+
/* Table rules */
198+
table {
199+
width: 100%;
200+
border-collapse: collapse;
201+
border-top: 1px solid #eee;
202+
border-bottom: 1px solid #eee;
203+
}
204+
table caption {
205+
margin: 1rem 0 .75rem;
206+
}
207+
table tbody tr:nth-of-type(odd) {
208+
background-color: #eee;
209+
}
210+
table th,
211+
table td {
212+
text-align: left;
213+
padding: 0.25rem 0.5rem 0.2rem;
214+
}
215+
table td + td {
216+
border-left: 1px solid #ddd;
217+
}
218+
219+
/* Admonitions rules */
220+
div.note,
221+
div.warning {
222+
padding: 0.5rem 0.75rem;
223+
margin-top: 1rem;
224+
margin-bottom: 1rem;
225+
}
226+
div.note {
227+
background-color: #eee;
228+
}
229+
div.warning {
230+
background-color: #fee;
231+
}
232+
p.admonition-title {
233+
font-weight: bold;
234+
}
235+
236+
/* PEP Header / references rules */
237+
dl.rfc2822,
238+
dl.footnote {
239+
display: grid;
240+
grid-template-columns: fit-content(30%) auto;
241+
width: 100%;
242+
border-top: 1px solid #eee;
243+
border-bottom: 1px solid #eee;
244+
}
245+
dl.rfc2822 > dt, dl.rfc2822 > dd,
246+
dl.footnote > dt, dl.footnote > dd {
247+
padding: .25rem .5rem .2rem;
248+
}
249+
dl.rfc2822 > dt:nth-of-type(even), dl.rfc2822 > dd:nth-of-type(even),
250+
dl.footnote > dt:nth-of-type(even), dl.footnote > dd:nth-of-type(even) {
251+
background-color: #eee;
252+
}
253+
dl.footnote > dt {
254+
font-weight: normal;
255+
border-right: 1px solid white;
256+
}
257+
258+
/* Link-target rules */
259+
.link-target {
260+
font-size: 80%;
261+
}
262+
263+
table .link-target {
264+
/* Do not show links in tables, there is not enough space */
265+
display: none;
266+
}

‎pep_sphinx_extensions/pep_theme_epub/templates/page.html

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
{# Master layout template for the PEP epub theme. #}
2+
<!DOCTYPE html>
3+
<html lang="en-GB" xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops">
4+
<head>
5+
<meta charset="utf-8" />
6+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
7+
<title>{{ title|striptags|e }}</title>
8+
<link rel="stylesheet" href="{{ pathto('_static/pygments.css', resource=True) }}" type="text/css" />
9+
<link rel="stylesheet" href="{{ pathto('_static/epub.css', resource=True) }}" type="text/css" />
10+
<link href="https://fonts.googleapis.com/css2?family=Source+Sans+Pro:ital,wght@0,400;0,700;1,400&display=swap" rel="stylesheet">
11+
</head>
12+
<body>
13+
<section id="pep-page-section">
14+
<article>
15+
{{ body }}
16+
</article>
17+
</section>
18+
</body>
19+
</html>

‎pep_sphinx_extensions/pep_theme_epub/theme.conf

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
[theme]
2+
# Theme options
3+
inherit = none
4+
pygments_style = tango

0 commit comments

Comments
 (0)
0