Skip to content

Commit cdec6a1

Browse files
ivankravetsivankravets
committed
Refactor docs to be deployed as a static content
1 parent 91cc2ef commit cdec6a1

File tree

10 files changed

+366
-473
lines changed

10 files changed

+366
-473
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,2 @@
11
_build
2+
_ext/__pycache__

‎Makefile‎

Lines changed: 13 additions & 170 deletions
Original file line numberDiff line numberDiff line change
@@ -1,177 +1,20 @@
1-
# Makefile for Sphinx documentation
1+
# Minimal makefile for Sphinx documentation
22
#
33

4-
# You can set these variables from the command line.
5-
SPHINXOPTS =
6-
SPHINXBUILD = sphinx-build
7-
PAPER =
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
89
BUILDDIR = _build
910

10-
# User-friendly check for sphinx-build
11-
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
12-
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
13-
endif
14-
15-
# Internal variables.
16-
PAPEROPT_a4 = -D latex_paper_size=a4
17-
PAPEROPT_letter = -D latex_paper_size=letter
18-
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
19-
# the i18n builder cannot share the environment and doctrees with the others
20-
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
21-
22-
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
23-
11+
# Put it first so that "make" without argument is like "make help".
2412
help:
25-
@echo "Please use \`make <target>' where <target> is one of"
26-
@echo " html to make standalone HTML files"
27-
@echo " dirhtml to make HTML files named index.html in directories"
28-
@echo " singlehtml to make a single large HTML file"
29-
@echo " pickle to make pickle files"
30-
@echo " json to make JSON files"
31-
@echo " htmlhelp to make HTML files and a HTML help project"
32-
@echo " qthelp to make HTML files and a qthelp project"
33-
@echo " devhelp to make HTML files and a Devhelp project"
34-
@echo " epub to make an epub"
35-
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
36-
@echo " latexpdf to make LaTeX files and run them through pdflatex"
37-
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
38-
@echo " text to make text files"
39-
@echo " man to make manual pages"
40-
@echo " texinfo to make Texinfo files"
41-
@echo " info to make Texinfo files and run them through makeinfo"
42-
@echo " gettext to make PO message catalogs"
43-
@echo " changes to make an overview of all changed/added/deprecated items"
44-
@echo " xml to make Docutils-native XML files"
45-
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
46-
@echo " linkcheck to check all external links for integrity"
47-
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
48-
49-
clean:
50-
rm -rf $(BUILDDIR)/*
51-
52-
html:
53-
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
54-
@echo
55-
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
56-
57-
dirhtml:
58-
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
59-
@echo
60-
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
61-
62-
singlehtml:
63-
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
64-
@echo
65-
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
66-
67-
pickle:
68-
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
69-
@echo
70-
@echo "Build finished; now you can process the pickle files."
71-
72-
json:
73-
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
74-
@echo
75-
@echo "Build finished; now you can process the JSON files."
76-
77-
htmlhelp:
78-
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
79-
@echo
80-
@echo "Build finished; now you can run HTML Help Workshop with the" \
81-
".hhp project file in $(BUILDDIR)/htmlhelp."
82-
83-
qthelp:
84-
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
85-
@echo
86-
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
87-
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
88-
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/PlatformIO.qhcp"
89-
@echo "To view the help file:"
90-
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/PlatformIO.qhc"
91-
92-
devhelp:
93-
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
94-
@echo
95-
@echo "Build finished."
96-
@echo "To view the help file:"
97-
@echo "# mkdir -p $$HOME/.local/share/devhelp/PlatformIO"
98-
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/PlatformIO"
99-
@echo "# devhelp"
100-
101-
epub:
102-
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
103-
@echo
104-
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
105-
106-
latex:
107-
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
108-
@echo
109-
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
110-
@echo "Run \`make' in that directory to run these through (pdf)latex" \
111-
"(use \`make latexpdf' here to do that automatically)."
112-
113-
latexpdf:
114-
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
115-
@echo "Running LaTeX files through pdflatex..."
116-
$(MAKE) -C $(BUILDDIR)/latex all-pdf
117-
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
118-
119-
latexpdfja:
120-
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
121-
@echo "Running LaTeX files through platex and dvipdfmx..."
122-
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
123-
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
124-
125-
text:
126-
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
127-
@echo
128-
@echo "Build finished. The text files are in $(BUILDDIR)/text."
129-
130-
man:
131-
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
132-
@echo
133-
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
134-
135-
texinfo:
136-
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
137-
@echo
138-
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
139-
@echo "Run \`make' in that directory to run these through makeinfo" \
140-
"(use \`make info' here to do that automatically)."
141-
142-
info:
143-
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
144-
@echo "Running Texinfo files through makeinfo..."
145-
make -C $(BUILDDIR)/texinfo info
146-
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
147-
148-
gettext:
149-
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
150-
@echo
151-
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
152-
153-
changes:
154-
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
155-
@echo
156-
@echo "The overview file is in $(BUILDDIR)/changes."
157-
158-
linkcheck:
159-
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
160-
@echo
161-
@echo "Link check complete; look for any errors in the above output " \
162-
"or in $(BUILDDIR)/linkcheck/output.txt."
163-
164-
doctest:
165-
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
166-
@echo "Testing of doctests in the sources finished, look at the " \
167-
"results in $(BUILDDIR)/doctest/output.txt."
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
16814

169-
xml:
170-
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
171-
@echo
172-
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
15+
.PHONY: help Makefile
17316

174-
pseudoxml:
175-
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
176-
@echo
177-
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎_ext/redirects.py‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# Copyright (c) 2014-present PlatformIO <contact@platformio.org>
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
import os
16+
from string import Template
17+
18+
19+
REDIRECT_TEMPLATE = Template(
20+
r"""
21+
<!DOCTYPE html>
22+
<html lang="en-US">
23+
<head>
24+
<title>Redirecting&hellip;</title>
25+
<script>
26+
var redirect_url = "$redirect_url";
27+
if (window.location.search) {
28+
redirect_url += "?" + window.location.search;
29+
}
30+
if (window.location.hash) {
31+
redirect_url += "#" + window.location.hash;
32+
}
33+
window.location.href = redirect_url;
34+
</script>
35+
<link rel="canonical" href="$redirect_url" />
36+
<meta charset="utf-8" />
37+
<meta http-equiv="refresh" content="1; URL=$redirect_url" />
38+
<meta name="robots" content="noindex" />
39+
</head>
40+
<body>
41+
<h1>Redirecting&hellip;</h1>
42+
<p><a href="$redirect_url">Click here if you are not redirected.</a></p>
43+
</body>
44+
</html>
45+
"""
46+
)
47+
48+
49+
def load_redirects(src_dir):
50+
redirects_txt = os.path.join(src_dir, "redirects.txt")
51+
assert os.path.isfile(redirects_txt)
52+
result = {}
53+
with open(redirects_txt) as fp:
54+
for line in fp.readlines():
55+
line = line.strip()
56+
skip_conds = [
57+
not line,
58+
not line.startswith("/"),
59+
"->" not in line,
60+
]
61+
if any(skip_conds):
62+
continue
63+
from_path, to_path = line.split("->")
64+
from_path = from_path.strip()
65+
to_path = to_path.strip()
66+
assert from_path.endswith(".html")
67+
assert to_path.endswith(".html")
68+
result[from_path] = to_path
69+
return result
70+
71+
72+
def build_redirect_pages(app, exception):
73+
if app.builder.name != "html":
74+
return
75+
is_latest = app.config.html_context.get("is_latest")
76+
redirects = load_redirects(app.srcdir)
77+
for from_path, to_path in redirects.items():
78+
out_dir = app.outdir
79+
if os.path.dirname(from_path) != "/":
80+
out_dir = os.path.join(out_dir, os.path.dirname(from_path)[1:])
81+
os.makedirs(out_dir, exist_ok=True)
82+
with open(os.path.join(out_dir, os.path.basename(from_path)), "w") as fp:
83+
fp.write(
84+
REDIRECT_TEMPLATE.substitute(
85+
redirect_url="%s/en/%s%s"
86+
% (
87+
app.config.html_baseurl,
88+
("latest" if is_latest else "stable"),
89+
to_path,
90+
)
91+
).strip()
92+
)
93+
print("Built %d redirect pages" % len(redirects))
94+
95+
96+
def build_legacy_rtd_pages(app, exception):
97+
if app.builder.name != "html":
98+
return
99+
for root, dirs, files in os.walk(app.outdir):
100+
for name in files:
101+
if not name.endswith(".html"):
102+
continue
103+
out_dir = os.path.join(os.path.dirname(app.outdir), "rtdpage")
104+
relative_dir = root[len(os.path.commonpath([app.outdir, root])) :] or "/"
105+
if relative_dir != "/":
106+
out_dir = os.path.join(out_dir, relative_dir[1:])
107+
os.makedirs(out_dir, exist_ok=True)
108+
with open(os.path.join(out_dir, name), "w") as fp:
109+
fp.write(
110+
REDIRECT_TEMPLATE.substitute(
111+
redirect_url="%s/en/latest%s%s"
112+
% (
113+
app.config.html_baseurl,
114+
relative_dir,
115+
name,
116+
)
117+
).strip()
118+
)
119+
120+
121+
def setup(app):
122+
app.connect("build-finished", build_redirect_pages)
123+
app.connect("build-finished", build_legacy_rtd_pages)
124+
return {
125+
"parallel_read_safe": True,
126+
"parallel_write_safe": True,
127+
}

‎_static/css/extra.css‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -529,8 +529,7 @@ fieldset[disabled] .navbar-inverse .btn-link:focus {
529529
max-width: 1000px !important;
530530
}
531531

532-
.wy-side-scroll .wy-side-nav-search .icon,
533-
.wy-side-scroll .wy-side-nav-search .version {
532+
.wy-side-scroll .wy-side-nav-search .icon {
534533
display: none;
535534
visibility: none;
536535
}

‎_templates/layout.html‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{% extends "!layout.html" %}
2+
3+
{% block extrahead %}
4+
{{ super() }}
5+
<link rel="stylesheet" href="{{ pathto('_static/css/extra.css', 1) }}" type="text/css" />
6+
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.4.1/js/bootstrap.min.js" integrity="sha384-Tc5IQib027qvyjSMfHjOMaLkfuWVxZxUPnCJA7l2mCWNIpG9mGCD8wGNIcPD7Txa" crossorigin="anonymous"></script>
7+
<!-- <script src="http://dl.platformio.org/misc/abplus.js"></script> -->
8+
{% endblock %}
9+
10+
{% block footer %}
11+
{% include "pio-versions.html" %}
12+
{{ super() }}
13+
{% include "navigation.html" %}
14+
{% endblock %}

‎_templates/footer.html‎ renamed to ‎_templates/navigation.html‎

Lines changed: 0 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,3 @@
1-
{% extends "!footer.html" %}
2-
3-
{% block extrafooter %}
4-
<link rel="stylesheet" href="{{ pathto('_static/css/extra.css', 1) }}" type="text/css" />
5-
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.4.1/js/bootstrap.min.js" integrity="sha384-Tc5IQib027qvyjSMfHjOMaLkfuWVxZxUPnCJA7l2mCWNIpG9mGCD8wGNIcPD7Txa" crossorigin="anonymous"></script>
6-
<!-- <script src="http://dl.platformio.org/misc/abplus.js"></script> -->
71
<script>
82
var navBarHTML = '\
93
<div>\
@@ -107,5 +101,3 @@
107101
});
108102
})();
109103
</script>
110-
{{ super() }}
111-
{% endblock %}

‎_templates/pio-versions.html‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
{# Keep in sync with https://github.com/readthedocs/sphinx_rtd_theme/blob/master/sphinx_rtd_theme/versions.html #}
2+
{# Add rst-badge after rst-versions for small badge style. #}
3+
<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="{{ _('Versions') }}">
4+
<span class="rst-current-version" data-toggle="rst-current-version">
5+
<span class="fa fa-book"> Documentation</span>
6+
v{{ release }} ({{ "latest" if is_latest else "stable" }})
7+
<span class="fa fa-caret-down"></span>
8+
</span>
9+
<div class="rst-other-versions">
10+
<dl>
11+
<dt>{{ _('Versions') }}</dt>
12+
{% for slug, url in versions %}
13+
<dd><a href="{{ url }}">{{ slug }}</a></dd>
14+
{% endfor %}
15+
</dl>
16+
<dl>
17+
<dt>{{ _('On Github') }}</dt>
18+
<dd><a href="https://{{ github_host|default("github.com") }}/{{ github_user }}/{{ github_repo }}/blob/{{ github_version }}{{ conf_py_path }}{{ pagename }}{{ page_source_suffix }}"> {{ _('View') }}</a></dd>
19+
<dd><a href="https://{{ github_host|default("github.com") }}/{{ github_user }}/{{ github_repo }}/edit/{{ github_version }}{{ conf_py_path }}{{ pagename }}{{ page_source_suffix }}"> {{ _('Edit') }}</a></dd>
20+
</dl>
21+
<dl>
22+
<dt>{{ _('Search') }}</dt>
23+
<dd>{% include "searchbox.html" %}</dd>
24+
</dl>
25+
</div>
26+
</div>

0 commit comments

Comments
 (0)