Skip to content

Commit 44f67ab

Browse files
python-sidebarpython-sidebar
authored
Merge pull request #1 from python-docs-101/PYDOC-6-rebuild-official-docs-using-rtd-theme--branch-a
PYDOC-6 [a]: Rebuild official docs using RTD theme
2 parents 9ccd09b + aa18d65 commit 44f67ab

File tree

13 files changed

+700
-20
lines changed

13 files changed

+700
-20
lines changed

‎.gitignore

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,13 @@
11
##########################################################################
2-
# Added by this fork repo:
2+
# Added by this RTD fork repo:
33
# https://github.com/python-docs-101/Python-Documentation-Theme-Fork
44
##########################################################################
55
.config/*
6+
__notes__*
7+
8+
##########################################################################
9+
# Original .gitignore below this comment
10+
##########################################################################
611

712
#####
813
# First, rules intended to apply in all subdirectories.

‎Doc/_static/css_for_fork/py_rtd_fork.css

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
/* Import from original theme. */
2+
pre {
3+
padding: 5px;
4+
background-color: #eeffcc;
5+
color: #333333;
6+
line-height: 120%;
7+
border: 1px solid #ac9;
8+
border-left: none;
9+
border-right: none;
10+
}
11+
12+
/* Import from original theme. */
13+
div.body a {
14+
color: #0072aa;
15+
}
16+
div.body a:visited {
17+
color: #6363bb;
18+
}
19+
div.body a:hover {
20+
color: #00B0E4;
21+
}
22+
/* minor edit to add scope `div.wy-nav-content` to fix sidebar */
23+
div.wy-nav-content a code span.pre {
24+
color: #2980b9;
25+
}
26+
27+
/* Import from original theme.
28+
Fixes an awful issue where RTD theme settings made non-hyperlinks look like hyperlinks.
29+
*/
30+
html.writer-html4 .rst-content dl:not(.docutils)>dt, html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt {
31+
color: #222222;
32+
}
33+
34+
/* Import from original theme.
35+
Make inline code blocks look more like GitHub and Slack
36+
*/
37+
code,
38+
.rst-content code,
39+
.rst-content code.literal,
40+
.rst-content tt,
41+
.rst-content tt.literal {
42+
color: #333333;
43+
padding: 0 1px 0 1px;
44+
font-size: 0.95em;
45+
background-color: #ecf0f3;
46+
}
47+
48+
/* Import from original theme. */
49+
a.headerlink {
50+
visibility: hidden;
51+
}
52+
53+
a.brackets:before {
54+
content: "[";
55+
}
56+
57+
a.brackets:after {
58+
content: "]";
59+
}
60+
61+
62+
/* Import from original theme. */
63+
span.linkdescr {
64+
font-style: italic;
65+
padding-top: 5px;
66+
font-size: 90%;
67+
}
68+
a.biglink {
69+
font-size: 1.3em;
70+
}
71+
72+
div.footer {
73+
line-height: 150%;
74+
margin-top: -2em;
75+
text-align: right;
76+
width: auto;
77+
margin-right: 10px;
78+
font-size: 75%;
79+
padding: 9px 0 9px 0;
80+
}

‎Doc/_static/py.svg

Lines changed: 14 additions & 0 deletions
Loading

‎Doc/conf.py

Lines changed: 134 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -85,16 +85,145 @@
8585
# Options for HTML output
8686
# -----------------------
8787

88-
# Use our custom theme.
89-
html_theme = 'python_docs_theme'
90-
html_theme_path = ['tools']
88+
89+
##<>=========================================================
90+
## @@~@@ FORK MODIFIES THIS SECTOION -- replaced
91+
##===========================================================
92+
## Original options using `html_theme = 'python_docs_theme'`
93+
##===========================================================
94+
# # Use our custom theme.
95+
# html_theme = 'python_docs_theme'
96+
# html_theme_path = ['tools']
97+
# html_theme_options = {
98+
# 'collapsiblesidebar': True,
99+
# 'issues_url': '/bugs.html',
100+
# 'license_url': '/license.html',
101+
# 'root_include_title': False # We use the version switcher instead.
102+
# }
103+
##</>========================================================
104+
105+
106+
##<>=========================================================
107+
## @@~@@ FORK MODIFIES THIS SECTOION -- added
108+
##===========================================================
109+
## Original options using `html_theme = 'python_docs_theme'`
110+
##===========================================================
111+
html_theme = 'sphinx_rtd_theme'
112+
html_theme_path = ['']
113+
html_favicon = '_static/py.svg'
91114
html_theme_options = {
92-
'collapsiblesidebar': True,
115+
#-------------------------------------------------------------------
116+
# Add these variables manually to:
117+
# Doc/venv/lib/python3.9/site-packages/sphinx_rtd_theme/theme.conf
118+
# then they can be accessed via theme_issues_url + theme_license_url
119+
#-------------------------------------------------------------------
93120
'issues_url': '/bugs.html',
94121
'license_url': '/license.html',
95-
'root_include_title': False # We use the version switcher instead.
122+
123+
#***************************************************************
124+
# DOCS: sphinx_rtd_theme : collapse_navigation *
125+
#***************************************************************
126+
# Poorly named. *
127+
# *
128+
# From sphinx-rtd-theme.readthedocs.io: *
129+
# *
130+
# Type: boolean *
131+
# Default: True *
132+
# *
133+
# Description: *
134+
# *
135+
# With collapse_navigation enabled *
136+
# *
137+
# Navigation entries are not expandable *
138+
# – the [+] icons next to each entry are removed. *
139+
# *
140+
#***************************************************************
141+
# This really means, *
142+
# "Do you want to collapse all the nav *
143+
# and not include sub-pages?" *
144+
# *
145+
# We want to tell it: *
146+
# "False, I wish to include sub-pages." *
147+
#***************************************************************
148+
'collapse_navigation': False,
149+
150+
#**********************************************************************
151+
# DOCS: sphinx_rtd_theme : navigation_depth *
152+
#**********************************************************************
153+
# *
154+
# From sphinx-rtd-theme.readthedocs.io: *
155+
# *
156+
# Type: integer *
157+
# Default: 4 *
158+
# *
159+
# Description: *
160+
# The maximum depth of the table of contents tree. *
161+
# Set this to -1 to allow unlimited depth. *
162+
# *
163+
#**********************************************************************
164+
'navigation_depth': -1,
165+
166+
#************************************************************
167+
# DOCS: sphinx_rtd_theme : titles_only *
168+
#************************************************************
169+
# *
170+
# From sphinx-rtd-theme.readthedocs.io: *
171+
# *
172+
# Type: boolean *
173+
# Default: False *
174+
# *
175+
# Description: *
176+
# When enabled, page subheadings *
177+
# are not included in the navigation. *
178+
# *
179+
#************************************************************
180+
'titles_only': False,
181+
182+
#************************************************************
183+
# DOCS: sphinx_rtd_theme : warning *
184+
#************************************************************
185+
# *
186+
# Note: *
187+
# *
188+
# Setting collapse_navigation to False *
189+
# and using a high value for navigation_depth *
190+
# on projects with many files and a deep file structure *
191+
# *
192+
# can cause long compilation times *
193+
# and can result in HTML files *
194+
# that are significantly larger in file size. *
195+
# *
196+
#************************************************************
96197
}
97198

199+
##</>========================================================
200+
## @@~@@ FORK MODIFIES THIS SECTOION -- added
201+
## endof update
202+
##===========================================================
203+
204+
##-------------------------------------------------------------------------
205+
## <> RTD CSS Config
206+
##-------------------------------------------------------------------------
207+
## See
208+
## https://docs.readthedocs.io/en/stable/guides/adding-custom-css.html
209+
##-------------------------------------------------------------------------
210+
# These folders are copied to the documentation's HTML output
211+
html_static_path = ['_static']
212+
213+
# These paths are either relative to html_static_path
214+
# or fully qualified paths (eg. https://...)
215+
html_css_files = [
216+
'css_for_fork/py_rtd_fork.css',
217+
]
218+
##-------------------------------------------------------------------------
219+
## </> RTD CSS Config
220+
##-------------------------------------------------------------------------
221+
222+
223+
224+
225+
226+
98227
# Override stylesheet fingerprinting for Windows CHM htmlhelp to fix GH-91207
99228
# https://github.com/python/cpython/issues/91207
100229
if any('htmlhelp' in arg for arg in sys.argv):

‎Doc/contents.rst

Lines changed: 24 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2,29 +2,40 @@
22
Python Documentation contents
33
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
44

5-
.. toctree::
5+
.. |hr| raw:: html
6+
7+
<hr>
68

9+
.. toctree::
10+
711
whatsnew/index.rst
12+
---------------------- <glossary.rst>
813
tutorial/index.rst
9-
using/index.rst
10-
reference/index.rst
1114
library/index.rst
15+
reference/index.rst
16+
using/index.rst
17+
howto/index.rst
18+
19+
---------------------- <glossary.rst>
20+
installing/index.rst
21+
distributing/index.rst
1222
extending/index.rst
1323
c-api/index.rst
14-
distributing/index.rst
15-
installing/index.rst
16-
howto/index.rst
1724
faq/index.rst
25+
26+
---------------------- <glossary.rst>
27+
28+
Python Module Index <https://python-docs-101.github.io/py-modindex.html>
29+
General Index <https://python-docs-101.github.io/genindex.html>
30+
Search page <https://python-docs-101.github.io/search.html>
31+
Complete TOC <https://python-docs-101.github.io/contents.html>
1832
glossary.rst
19-
33+
34+
---------------------- <glossary.rst>
2035
about.rst
36+
Contributing to Docs <https://devguide.python.org/documentation/help-documenting/index.html#helping-with-documentation>
2137
bugs.rst
22-
copyright.rst
2338
license.rst
39+
copyright.rst
2440

2541
.. to include legacy packaging docs in build
26-
27-
.. toctree::
28-
:hidden:
29-
30-
install/index.rst

‎Doc/installing/index.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -239,3 +239,9 @@ obtaining other binary extensions without needing to build them locally.
239239

240240
`Python Packaging User Guide: Binary Extensions
241241
<https://packaging.python.org/extensions/>`__
242+
243+
244+
.. toctree::
245+
:hidden:
246+
247+
../install/index.rst

‎Doc/requirements.txt

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,17 @@
1+
##########################################################################
2+
# Added by this RTD fork repo:
3+
# https://github.com/python-docs-101/Python-Documentation-Theme-Fork
4+
##########################################################################
5+
6+
sphinx_rtd_theme
7+
8+
9+
10+
##########################################################################
11+
# Original requirements.txt below this comment
12+
##########################################################################
13+
14+
115
# Requirements to build the Python documentation
216

317
# Sphinx version is pinned so that new versions that introduce new warnings

‎Doc/tools/templates/footerdonate.html

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{% trans %}The Python Software Foundation is a non-profit corporation.{% endtrans %}
2+
<a href="https://www.python.org/psf/donations/">{% trans %}Please donate.{% endtrans %}</a>
3+
<br />

‎Doc/tools/templates/indexcontent.html

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,24 @@
55
{% block body %}
66
<h1>{{ docstitle|e }}</h1>
77
<p>
8-
{% trans %}Welcome! This is the official documentation for Python {{ release }}.{% endtrans %}
8+
{% trans %}Welcome! This is
9+
<a href="https://github.com/python-docs-101/python-docs-101.github.io">
10+
<strong style="font-size:larger;">
11+
<code>A FORK OF</code>
12+
</strong>
13+
</a>
14+
the official documentation for Python {{ release }}.{% endtrans %}
915
</p>
16+
<div style="background-color:#edf0f2; padding-left:7px;"><br>
17+
<span style="font-size:larger;">Fork note:</span><br><br>
18+
<p style="padding-left: 3vw;">
19+
◀ We added a TOC sidebar to this entire site!
20+
<br>
21+
Otherwise, the rest of this repo is identical to the main docs at <a href="https://docs.python.org/">https://docs.python.org</a>
22+
</p>
23+
<span style="font-size:larger;">Happy coding 👩‍💻</span><br><br>
24+
</div>
25+
<br>
1026
<p><strong>{% trans %}Parts of the documentation:{% endtrans %}</strong></p>
1127
<table class="contentstable" align="center"><tr>
1228
<td width="50%">

0 commit comments

Comments
 (0)