8000 [MRG+1] MAINT Use magic to list documentation versions (#9841) · scikit-learn/scikit-learn@fd25481 · GitHub
[go: up one dir, main page]
Skip to content

Commit fd25481

Browse files
jnothmanTomDLT
jnothman
authored and
TomDLT
committed
[MRG+1] MAINT Use magic to list documentation versions (#9841)
1 parent 37ce9ae commit fd25481

File tree

7 files changed

+121
-24
lines changed

7 files changed

+121
-24
lines changed

‎build_tools/circle/build_doc.sh

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,13 @@ pip install git+https://github.com/numpy/numpydoc
116116
# Build and install scikit-learn in dev mode
117117
python setup.py develop
118118

119+
# TO BE UNCOMMENTED BEFORE MERGE
120+
###if [[ "$CIRCLE_BRANCH" =~ ^master$ && -z "$CI_PULL_REQUEST" ]]
121+
###then
122+
# List available documentation versions if on master
123+
python build_tools/circle/list_versions.py > doc/versions.rst
124+
###fi
125+
119126
# The pipefail is requested to propagate exit code
120127
set -o pipefail && cd doc && make $MAKE_TARGET 2>&1 | tee ~/log.txt
121128

‎build_tools/circle/list_versions.py

Lines changed: 92 additions & 0 deletions
+
print()
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
#!/usr/bin/env python3
2+
3+
# List all available versions of the documentation
4+
5+
from urllib.request import urlopen
6+
import json
7+
import re
8+
9+
from distutils.version import LooseVersion
10+
11+
12+
def json_urlread(url):
13+
return json.loads(urlopen(url).read().decode('utf8'))
14+
15+
16+
def human_readable_data_quantity(quantity, multiple=1024):
17+
# https://stackoverflow.com/questions/1094841/reusable-library-to-get-human-readable-version-of-file-size
18+
if quantity == 0:
19+
quantity = +0
20+
SUFFIXES = ["B"] + [i + {1000: "B", 1024: "iB"}[multiple]
21+
for i in "KMGTPEZY"]
22+
for suffix in SUFFIXES:
23+
if quantity < multiple or suffix == SUFFIXES[-1]:
24+
if suffix == SUFFIXES[0]:
25+
return "%d %s" % (quantity, suffix)
26+
else:
27+
return "%.1f %s" % (quantity, suffix)
28+
else:
29+
quantity /= multiple
30+
31+
32+
def get_pdf_size(version):
33+
api_url = ROOT_URL + '%s/_downloads' % version
34+
for path_details in json_urlread(api_url):
35+
if path_details['name'] == 'scikit-learn-docs.pdf':
36+
return human_readable_data_quantity(path_details['size'], 1000)
37+
38+
39+
heading = 'Available documentation for Scikit-learn'
40+
print(heading)
41+
print('=' * len(heading))
42+
print()
43+
print('Web-based documentation is available for versions listed below:')
44
45+
46+
ROOT_URL = 'https://api.github.com/repos/scikit-learn/scikit-learn.github.io/contents/' # noqa
47+
RAW_FMT = 'https://raw.githubusercontent.com/scikit-learn/scikit-learn.github.io/master/%s/documentation.html' # noqa
48+
VERSION_RE = re.compile(r"\bVERSION:\s*'([^']+)'")
49+
NAMED_DIRS = ['dev', 'stable']
50+
51+
# Gather data for each version directory, including symlinks
52+
dirs = {}
53+
symlinks = {}
54+
root_listing = json_urlread(ROOT_URL)
55+
for path_details in root_listing:
56+
name = path_details['name']
57+
if not (name[:1].isdigit() or name in NAMED_DIRS):
58+
continue
59+
if path_details['type'] == 'dir':
60+
html = urlopen(RAW_FMT % name).read().decode('utf8')
61+
version_num = VERSION_RE.search(html).group(1)
62+
pdf_size = get_pdf_size(name)
63+
dirs[name] = (version_num, pdf_size)
64+
65+
if path_details['type'] == 'symlink':
66+
symlinks[name] = json_urlread(path_details['_links']['self'])['target']
67+
68+
69+
# Symlinks should have same data as target
70+
for src, dst in symlinks.items():
71+
if dst in dirs:
72+
dirs[src] = dirs[dst]
73+
74+
# Output in order: dev, stable, decreasing other version
75+
seen = set()
76+
for name in (NAMED_DIRS +
77+
sorted((k for k in dirs if k[:1].isdigit()),
78+
key=LooseVersion, reverse=True)):
79+
version_num, pdf_size = dirs[name]
80+
if version_num in seen:
81+
# symlink came first
82+
continue
83+
else:
84+
seen.add(version_num)
85+
name_display = '' if name[:1].isdigit() else ' (%s)' % name
86+
path = 'http://scikit-learn.org/%s' % name
87+
out = ('* `Scikit-learn %s%s documentation <%s/documentation.html>`_'
88+
% (version_num, name_display, path))
89+
if pdf_size is not None:
90+
out += (' (`PDF %s <%s/_downloads/scikit-learn-docs.pdf>`_)'
91+
% (pdf_size, path))
92+
print(out)

‎build_tools/circle/push_doc.sh

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,5 +39,4 @@ git config --global push.default matching
3939
git add -f $dir/
4040
git commit -m "$MSG" $dir
4141
git push
42-
4342
echo $MSG

‎doc/developers/maintainer.rst

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,7 @@ For more information see https://github.com/scikit-learn/scikit-learn/wiki/How-t
1313

1414
$ git shortlog -ns 0.998..
1515

16-
- edit the doc/conf.py to increase the version number
17-
18-
- edit the doc/themes/scikit-learn/layout.html to change the 'News'
19-
entry of the front page.
16+
- edit the doc/index.rst to change the 'News' entry of the front page.
2017

2118
2. Update the version number in sklearn/__init__.py, the __version__
2219
variable
@@ -38,7 +35,8 @@ For more information see https://github.com/scikit-learn/scikit-learn/wiki/How-t
3835
$ python setup.py sdist register upload
3936

4037

41-
5. Push the documentation to the website (see README in doc folder)
38+
5. Push the documentation to the website. Circle CI should do this
39+
automatically for master and <N>.<N>.X branches.
4240

4341

4442
6. Build binaries using dedicated CI servers by updating the git submodule

‎doc/documentation.rst

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
<div class="container-index">
44

5-
Documentation of scikit-learn 0.19.dev0
5+
Documentation of scikit-learn |version|
66
=======================================
77

88
.. raw:: html
@@ -28,10 +28,10 @@ Documentation of scikit-learn 0.19.dev0
2828
<!-- doc versions -->
2929
<h2>Other Versions</h2>
3030
<ul>
31-
<li>scikit-learn 0.19 (development)</li>
32-
<li><a href="http://scikit-learn.org/stable/documentation.html">scikit-learn 0.18 (stable)</a></li>
33-
<li><a href="http://scikit-learn.org/0.17/documentation.html">scikit-learn 0.17</a></li>
34-
<li><a href="http://scikit-learn.org/0.16/documentation.html">scikit-learn 0.16</a></li>
31+
<script>if (VERSION_SUBDIR != "stable") document.write('<li><a href="http://scikit-learn.org/stable/documentation.html">Stable version</a></li>')</script>
32+
<script>if (VERSION_SUBDIR != "dev") document.write('<li><a href="http://scikit-learn.org/dev/documentation.html">Development version</a></li>')</script>
33+
<li><a href="http://scikit-learn.org/dev/versions.html">Previous versions</a></li>
34+
<li><a href="_downloads/scikit-learn-docs.pdf">PDF documentation</a></li>
3535
</ul>
3636

3737
</div>

‎doc/support.rst

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -90,13 +90,9 @@ client works fine: http://webchat.freenode.net
9090
Documentation resources
9191
=======================
9292

93-
This documentation is relative to |release|. Documentation for other
94-
versions can be found here:
93+
This documentation is relative to |release|. Documentation for
94+
other versions can be found `here
95+
<http://scikit-learn.org/dev/versions.html>`_.
9596

96-
* `0.18 <http://scikit-learn.org/0.18/>`_
97-
* `0.17 <http://scikit-learn.org/0.17/>`_
98-
* `0.16 <http://scikit-learn.org/0.16/>`_
99-
* `0.15 <http://scikit-learn.org/0.15/>`_
100-
101-
Printable pdf documentation for all versions can be found `here
97+
Printable pdf documentation for old versions can be found `here
10298
<https://sourceforge.net/projects/scikit-learn/files/documentation/>`_.

‎doc/themes/scikit-learn/layout.html

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,11 @@
2626
{% endif %}
2727
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
2828
<script src="{{ pathto('_static/js/bootstrap.min.js', 1)}}" type="text/javascript"></script>
29+
<script>
30+
VERSION_SUBDIR = (function(groups) {
31+
return groups ? groups[1] : null;
32+
})(location.href.match(/^https?:\/\/scikit-learn.org\/([^\/]+)/));
33+
</script>
2934
<link rel="canonical" href="http://scikit-learn.org/stable/{{pagename}}.html" />
3035

3136
<script type="text/javascript">
@@ -78,17 +83,17 @@
7883
<span class="caret"></span>
7984
</a>
8085
<ul class="dropdown-menu">
81-
<li class="link-title">Scikit-learn 0.19 (development)</li>
86+
<li class="link-title">Scikit-learn <script>document.write(DOCUMENTATION_OPTIONS.VERSION + (VERSION_SUBDIR ? " (" + VERSION_SUBDIR + ")" : ""));</script></li>
8287
<li><a href="{{ pathto('tutorial/index') }}">Tutorials</a></li>
8388
<li><a href="{{ pathto('user_guide') }}">User guide</a></li>
8489
<li><a href="{{ pathto('modules/classes') }}">API</a></li>
8590
<li><a href="{{ pathto('faq') }}">FAQ</a></li>
8691
<li><a href="{{ pathto('developers/contributing') }}">Contributing</a></li>
8792
<li class="divider"></li>
88-
<li><a href="http://scikit-learn.org/stable/documentation.html">Scikit-learn 0.18 (stable)</a></li>
89-
<li><a href="http://scikit-learn.org/0.17/documentation.html">Scikit-learn 0.17</a></li>
90-
<li><a href="http://scikit-learn.org/0.16/documentation.html">Scikit-learn 0.16</a></li>
91-
<li><a href="{{ pathto('_downloads/scikit-learn-docs.pdf', 1) }}">PDF documentation</a></li>
93+
<script>if (VERSION_SUBDIR != "stable") document.write('<li><a href="http://scikit-learn.org/stable/documentation.html">Stable version</a></li>')</script>
94+
<script>if (VERSION_SUBDIR != "dev") document.write('<li><a href="http://scikit-learn.org/dev/documentation.html">Development version</a></li>')</script>
95+
<li><a href="http://scikit-learn.org/dev/versions.html">Previous versions</a></li>
96+
<li><a href="{{ pathto('_downloads/scikit-learn-docs.pdf', 1) }}">PDF documentation</a></li>
9297
</ul>
9398
</div>
9499
</li>

0 commit comments

Comments
 (0)
0