scikit-learn · TomDLT · Nov 20, 2017 · Sep 27, 2017 · Sep 27, 2017 · Sep 27, 2017
diff --git a/build_tools/circle/build_doc.sh b/build_tools/circle/build_doc.sh
@@ -114,6 +114,13 @@ pip install sphinx-gallery numpydoc
 # Build and install scikit-learn in dev mode
 python setup.py develop
 
+# TO BE UNCOMMENTED BEFORE MERGE
+###if [[ "$CIRCLE_BRANCH" =~ ^master$ && -z "$CI_PULL_REQUEST" ]]
+###then
+    # List available documentation versions if on master
+    python build_tools/circle/list_versions.py > doc/versions.rst
+###fi
+
 # The pipefail is requested to propagate exit code
 set -o pipefail && cd doc && make $MAKE_TARGET 2>&1 | tee ~/log.txt
 

diff --git a/build_tools/circle/list_versions.py b/build_tools/circle/list_versions.py
@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+
+# List all available versions of the documentation
+
+from urllib.request import urlopen
+import json
+import re
+
+from distutils.version import LooseVersion
+
+
+def json_urlread(url):
+    return json.loads(urlopen(url).read().decode('utf8'))
+
+
+def human_readable_data_quantity(quantity, multiple=1024):
+    # https://stackoverflow.com/questions/1094841/reusable-library-to-get-human-readable-version-of-file-size
+    if quantity == 0:
+        quantity = +0
+    SUFFIXES = ["B"] + [i + {1000: "B", 1024: "iB"}[multiple]
+                        for i in "KMGTPEZY"]
+    for suffix in SUFFIXES:
+        if quantity < multiple or suffix == SUFFIXES[-1]:
+            if suffix == SUFFIXES[0]:
+                return "%d %s" % (quantity, suffix)
+            else:
+                return "%.1f %s" % (quantity, suffix)
+        else:
+            quantity /= multiple
+
+
+def get_pdf_size(version):
+    api_url = ROOT_URL + '%s/_downloads' % version
+    for path_details in json_urlread(api_url):
+        if path_details['name'] == 'scikit-learn-docs.pdf':
+            return human_readable_data_quantity(path_details['size'], 1000)
+
+
+heading = 'Available documentation for Scikit-learn'
+print(heading)
+print('=' * len(heading))
+print()
+print('Web-based documentation is available for versions listed below:')
+print()
+
+ROOT_URL = 'https://api.github.com/repos/scikit-learn/scikit-learn.github.io/contents/'  # noqa
+RAW_FMT = 'https://raw.githubusercontent.com/scikit-learn/scikit-learn.github.io/master/%s/documentation.html'  # noqa
+VERSION_RE = re.compile(r"\bVERSION:\s*'([^']+)'")
+NAMED_DIRS = ['dev', 'stable']
+
+# Gather data for each version directory, including symlinks
+dirs = {}
+symlinks = {}
+root_listing = json_urlread(ROOT_URL)
+for path_details in root_listing:
+    name = path_details['name']
+    if not (name[:1].isdigit() or name in NAMED_DIRS):
+        continue
+    if path_details['type'] == 'dir':
+        html = urlopen(RAW_FMT % name).read().decode('utf8')
+        version_num = VERSION_RE.search(html).group(1)
+        pdf_size = get_pdf_size(name)
+        dirs[name] = (version_num, pdf_size)
+
+    if path_details['type'] == 'symlink':
+        symlinks[name] = json_urlread(path_details['_links']['self'])['target']
+
+
+# Symlinks should have same data as target
+for src, dst in symlinks.items():
+    if dst in dirs:
+        dirs[src] = dirs[dst]
+
+# Output in order: dev, stable, decreasing other version
+seen = set()
8000
+for name in (NAMED_DIRS +
+             sorted((k for k in dirs if k[:1].isdigit()),
+                    key=LooseVersion, reverse=True)):
+    version_num, pdf_size = dirs[name]
+    if version_num in seen:
+        # symlink came first
+        continue
+    else:
+        seen.add(version_num)
+    name_display = '' if name[:1].isdigit() else ' (%s)' % name
+    path = 'http://scikit-learn.org/%s' % name
+    out = ('* `Scikit-learn %s%s documentation <%s/documentation.html>`_'
+           % (version_num, name_display, path))
+    if pdf_size is not None:
+        out += (' (`PDF %s <%s/_downloads/scikit-learn-docs.pdf>`_)'
+                % (pdf_size, path))
+    print(out)
diff --git a/build_tools/circle/push_doc.sh b/build_tools/circle/push_doc.sh
@@ -39,5 +39,4 @@ git config --global push.default matching
 git add -f $dir/
 git commit -m "$MSG" $dir
 git push
-
 echo $MSG 
diff --git a/doc/developers/maintainer.rst b/doc/developers/maintainer.rst
@@ -13,10 +13,7 @@ Making a release
 
         $ git shortlog -ns 0.998..
 
-    - edit the doc/conf.py to increase the version number
-
-    - edit the doc/themes/scikit-learn/layout.html to change the 'News'
-      entry of the front page.
+    - edit the doc/index.rst to change the 'News' entry of the front page.
 
 2. Update the version number in sklearn/__init__.py, the __version__
    variable
@@ -38,7 +35,8 @@ Making a release
        $ python setup.py sdist register upload
 
 
-5. Push the documentation to the website (see README in doc folder)
+5. Push the documentation to the website. Circle CI should do this
+   automatically for master and <N>.<N>.X branches.
 
 
 6. Build binaries using dedicated CI servers by updating the git submodule

diff --git a/doc/documentation.rst b/doc/documentation.rst
@@ -2,7 +2,7 @@
 
   <div class="container-index">
 
-Documentation of scikit-learn 0.19.dev0
+Documentation of scikit-learn |version|
 =======================================
 
 .. raw:: html
@@ -28,10 +28,10 @@ Documentation of scikit-learn 0.19.dev0
                 <!-- doc versions -->
                     <h2>Other Versions</h2>
                     <ul>
-                        <li>scikit-learn 0.19 (development)</li>
-                        <li><a href="http://scikit-learn.org/stable/documentation.html">scikit-learn 0.18 (stable)</a></li>
-                        <li><a href="http://scikit-learn.org/0.17/documentation.html">scikit-learn 0.17</a></li>
-                        <li><a href="http://scikit-learn.org/0.16/documentation.html">scikit-learn 0.16</a></li>
+                        <script>if (VERSION_SUBDIR != "stable") document.write('<li><a href="http://scikit-learn.org/stable/documentation.html">Stable version</a></li>')</script>
+                        <script>if (VERSION_SUBDIR != "dev") document.write('<li><a href="http://scikit-learn.org/dev/documentation.html">Development version</a></li>')</script>
+                        <li><a href="http://scikit-learn.org/dev/versions.html">Previous versions</a></li>
+                        <li><a href="_downloads/scikit-learn-docs.pdf">PDF documentation</a></li>
                     </ul>
 
                 </div>

diff --git a/doc/support.rst b/doc/support.rst
@@ -90,13 +90,9 @@ client works fine: http://webchat.freenode.net
 Documentation resources
 =======================
 
-This documentation is relative to |release|. Documentation for other
-versions can be found here:
+This documentation is relative to |release|. Documentation for
+other versions can be found `here
+<http://scikit-learn.org/dev/versions.html>`_.
 
-    * `0.18 <http://scikit-learn.org/0.18/>`_
-    * `0.17 <http://scikit-learn.org/0.17/>`_
-    * `0.16 <http://scikit-learn.org/0.16/>`_
-    * `0.15 <http://scikit-learn.org/0.15/>`_
-
-Printable pdf documentation for all versions can be found `here
+Printable pdf documentation for old versions can be found `here
 <https://sourceforge.net/projects/scikit-learn/files/documentation/>`_.
diff --git a/doc/themes/scikit-learn/layout.html b/doc/themes/scikit-learn/layout.html
@@ -26,6 +26,11 @@
   {% endif %}
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <script src="{{ pathto('_static/js/bootstrap.min.js', 1)}}" type="text/javascript"></script>
+  <script>
+     VERSION_SUBDIR = (function(groups) {
+         return groups ? groups[1] : null;
+     })(location.href.match(/^https?:\/\/scikit-learn.org\/([^\/]+)/));
+  </script>
   <link rel="canonical" href="http://scikit-learn.org/stable/{{pagename}}.html" />
 
   <script type="text/javascript">
@@ -78,17 +83,17 @@
                  <span class="caret"></span>
               </a>
               <ul class="dropdown-menu">
-            <li class="link-title">Scikit-learn 0.19 (development)</li>
+            <li class="link-title">Scikit-learn <script>document.write(DOCUMENTATION_OPTIONS.VERSION + (VERSION_SUBDIR ? " (" + VERSION_SUBDIR + ")" : ""));</script></li>
             <li><a href="{{ pathto('tutorial/index') }}">Tutorials</a></li>
             <li><a href="{{ pathto('user_guide') }}">User guide</a></li>
             <li><a href="{{ pathto('modules/classes') }}">API</a></li>
             <li><a href="{{ pathto('faq') }}">FAQ</a></li>
             <li><a href="{{ pathto('developers/contributing') }}">Contributing</a></li>
             <li class="divider"></li>
-                <li><a href="http://scikit-learn.org/stable/documentation.html">Scikit-learn 0.18 (stable)</a></li>
-                <li><a href="http://scikit-learn.org/0.17/documentation.html">Scikit-learn 0.17</a></li>
-                <li><a href="http://scikit-learn.org/0.16/documentation.html">Scikit-learn 0.16</a></li>
-				<li><a href="{{ pathto('_downloads/scikit-learn-docs.pdf', 1) }}">PDF documentation</a></li>
+                <script>if (VERSION_SUBDIR != "stable") document.write('<li><a href="http://scikit-learn.org/stable/documentation.html">Stable version</a></li>')</script>
+                <script>if (VERSION_SUBDIR != "dev") document.write('<li><a href="http://scikit-learn.org/dev/documentation.html">Development version</a></li>')</script>
+                <li><a href="http://scikit-learn.org/dev/versions.html">Previous versions</a></li>
+                <li><a href="{{ pathto('_downloads/scikit-learn-docs.pdf', 1) }}">PDF documentation</a></li>
               </ul>
             </div>
         </li>