diff --git a/azure-pipelines.yml b/azure-pipelines.yml index 4c80ed729..2a55d3633 100644 --- a/azure-pipelines.yml +++ b/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' 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' diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html new file mode 100644 index 000000000..f8f7aa6db --- /dev/null +++ b/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 %} +

+ + {% 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 {{latest_version.name}}. + {% else %} + You're reading the documentation for a development version. + For the latest released version, please have a look at {{latest_version.name}}. + {% endif %} + +

+{% endif %} +{{ super() }} +{% endblock %} diff --git a/doc/_templates/versions.html b/doc/_templates/versions.html new file mode 100644 index 000000000..86ece3c1a --- /dev/null +++ b/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 %} +
+ + Other Versions + {{ current_version.name }} + + +
+ {%- if versions.tags %} +
+
Tags
+ {%- for item in versions.tags %} +
{{ item.name }}
+ {%- endfor %} +
+ {%- endif %} + {%- if versions.branches %} +
+
Branches
+ {%- for item in versions.branches %} +
{{ item.name }}
+ {%- endfor %} +
+ {%- endif %} +
+
+{%- endif %} \ No newline at end of file diff --git a/doc/conf.py b/doc/conf.py index 12eab5cdc..8794b4ba1 100644 --- a/doc/conf.py +++ b/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) ()