Enable sphinx_multiversion

Author: kbattocchi

azure-pipelines.yml

@@ -54,13 +54,17 @@ jobs:
   parameters:
     versions: ['3.6']
     images: ['ubuntu-18.04']
-    package: '-e .[all]'
+    # don't install package, just build dependencies
+    package: 'oldest-supported-numpy scipy cython'
     job:
       job: 'Docs'
       displayName: 'Build documentation'  
       dependsOn: 'EvalChanges'
       condition: eq(dependencies.EvalChanges.outputs['output.buildDocs'], 'True')
       steps:
+      - script: 'pip install "scipy>1.4.0" "scikit-learn>0.22.0" sparse "joblib>=0.13.0" "statsmodels>=0.10" pandas "shap>=0.38.1,<0.40.0" "dowhy<0.8" lightgbm'
+        displayName: 'Install dependencies'
+        
       - script: 'sudo apt-get -yq install graphviz'
         displayName: 'Install graphviz'
 
@@ -70,17 +74,17 @@ jobs:
       - script: 'pip install git+https://github.com/slundberg/shap.git@d1d2700acc0259f211934373826d5ff71ad514de'
         displayName: 'Install specific version of shap'  
 
-      - script: 'pip install sphinx sphinx_rtd_theme'
+      - script: 'pip install sphinx sphinx_rtd_theme sphinx_multiversion'
         displayName: 'Install sphinx'
 
-      - script: 'python setup.py build_sphinx -W'
+      - script: 'sphinx-multiversion doc build/sphinx -W'
         displayName: 'Build documentation'
 
       - publish: 'build/sphinx/html'
         artifact: 'Documentation'
         displayName: 'Publish documentation as artifact'
 
-      - script: 'python setup.py build_sphinx -b doctest'
+      - script: 'pip install matplotlib & python setup.py build_sphinx -b doctest'
         displayName: 'Run doctests'
 
 

doc/_templates/layout.html

@@ -0,0 +1,19 @@
+{# This content is taken from https://holzhaus.github.io/sphinx-multiversion/master/templates.html#version-banners 
+   but applied to the layout.html document since the Read the Docs template does not have a page.html file. #}
+{% extends "!layout.html" %}
+{% block document %}
+{% if current_version and latest_version and current_version != latest_version %}
+<p>
+  <strong>
+    {% if current_version.is_released %}
+    You're reading an old version of this documentation.
+    If you want up-to-date information, please have a look at <a href="{{ vpathto(latest_version.name) }}">{{latest_version.name}}</a>.
+    {% else %}
+    You're reading the documentation for a development version.
+    For the latest released version, please have a look at <a href="{{ vpathto(latest_version.name) }}">{{latest_version.name}}</a>.
+    {% endif %}
+  </strong>
+</p>
+{% endif %}
+{{ super() }}
+{% endblock %}

doc/_templates/versions.html

@@ -0,0 +1,28 @@
+{# This content is a slightly tweaked version of the suggestions in https://holzhaus.github.io/sphinx-multiversion/master/templates.html#readthedocs-theme #}
+{%- if current_version %}
+<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
+  <span class="rst-current-version" data-toggle="rst-current-version">
+    <span class="fa fa-book"> Other Versions</span>
+    {{ current_version.name }}
+    <span class="fa fa-caret-down"></span>
+  </span>
+  <div class="rst-other-versions">
+    {%- if versions.tags %}
+    <dl>
+      <dt>Tags</dt>
+      {%- for item in versions.tags %}
+      <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
+      {%- endfor %}
+    </dl>
+    {%- endif %}
+    {%- if versions.branches %}
+    <dl>
+      <dt>Branches</dt>
+      {%- for item in versions.branches %}
+      <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
+      {%- endfor %}
+    </dl>
+    {%- endif %}
+  </div>
+</div>
+{%- endif %}

doc/conf.py

@@ -14,7 +14,8 @@
 #
 import os
 import sys
-import econml
+import re
+
 sys.path.insert(0, os.path.abspath('econml'))
 
 
@@ -23,8 +24,15 @@
 project = 'econml'
 copyright = '2019, Microsoft Research'
 author = 'Microsoft Research'
-version = econml.__version__
-release = econml.__version__
+
+# TODO: this seems much hackier than if we could just import econml and access the version directly
+#       but with sphinx-multiversion we can't do that
+with open(os.path.join(os.path.dirname(__file__), '..', "econml", "_version.py")) as file:
+    for line in file:
+        m = re.fullmatch("__version__ = '([^']+)'\n", line)
+        if m:
+            version = m.group(1)
+            release = version
 
 # -- General configuration ---------------------------------------------------
 
@@ -46,6 +54,7 @@
     'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
     'sphinx.ext.inheritance_diagram',
+    "sphinx_multiversion"
 ]
 inheritance_graph_attrs = dict(rankdir="TB", size='"7.0, 10.0"',
                                fontsize=12, ratio='auto',
@@ -99,6 +108,11 @@
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = None
 
+# sphinx_multiversion configuration
+smv_tag_whitelist = r'^v0\.(12\.0|13\.0)$'
+smv_branch_whitelist = '^main$'
+smv_latest_version = 'v0.13.0'
+smv_released_pattern = '^refs/tags/.+$'
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -215,7 +229,7 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'python': ('https://docs.python.org/3', None),
-                       'numpy': ('https://docs.scipy.org/doc/numpy/', None),
+                       'numpy': ('https://numpy.org/doc/stable/', None),
                        'sklearn': ('https://scikit-learn.org/stable/', None),
                        'matplotlib': ('https://matplotlib.org/', None),
                        'shap': ('https://shap.readthedocs.io/en/stable/', None),
@@ -244,5 +258,13 @@ def exclude_entity(app, what, name, obj, skip, opts):
 
 
 def setup(app):
+    # HACK: ensure that we build extensions in place first
+    # Will not be necessary if one of the PRs addressing https://github.com/Holzhaus/sphinx-multiversion/issues/45
+    # is merged into sphinx-multiversion
+    import subprocess
+    print("Building extensions")
+    subprocess.call(["python", "setup.py", "build_ext", "-i"])
+
+    # Hook up our method for skipping entities
     app.connect('autodoc-skip-member', exclude_entity)
     ()