From cc571eb816884a22502152c1f0c1e31a7e3af8e3 Mon Sep 17 00:00:00 2001 From: Matthew Treinish Date: Fri, 21 May 2021 10:09:52 -0400 Subject: [PATCH] Fix read the docs builds and docs formatting (#329) * Add matplotlib to read the docs builds Since #304 merged building the retworkx documentation has required that matplotlib be installed for generating the matplotlib visualizations in the documentation of `mpl_draw()`. However that PR neglected to add it to the read the docs conda environment configuration. This commit corrects this oversight to hopefully fix the documentation builds on read the docs. * Fix docs theme formatting This commit fixes some docs theme formatting issues to make sure the compiled HTML docs are correctly formatted. It mainly adds missing template files and configuration so the qiskit-sphinx-theme package has all the necessary details to correctly render. * Update copyright string --- .conda-rtd-environment.yml | 1 + docs/source/_static/gallery.css | 195 ++++++++++++ docs/source/_templates/autosummary/base.rst | 10 + docs/source/_templates/autosummary/class.rst | 49 +++ docs/source/_templates/autosummary/module.rst | 41 +++ docs/source/_templates/layout.html | 289 ++++++++++++++++++ docs/source/_templates/page.html | 14 + docs/source/_templates/theme_variables.jinja | 8 + docs/source/conf.py | 15 +- 9 files changed, 619 insertions(+), 3 deletions(-) create mode 100644 docs/source/_static/gallery.css create mode 100644 docs/source/_templates/autosummary/base.rst create mode 100644 docs/source/_templates/autosummary/class.rst create mode 100644 docs/source/_templates/autosummary/module.rst create mode 100644 docs/source/_templates/layout.html create mode 100644 docs/source/_templates/page.html create mode 100644 docs/source/_templates/theme_variables.jinja diff --git a/.conda-rtd-environment.yml b/.conda-rtd-environment.yml index 34c3c8f234..8a22365623 100644 --- a/.conda-rtd-environment.yml +++ b/.conda-rtd-environment.yml @@ -13,3 +13,4 @@ dependencies: - pillow - qiskit-sphinx-theme>=1.7 - reno>=3.2.0 + - matplotlib>=3.0 diff --git a/docs/source/_static/gallery.css b/docs/source/_static/gallery.css new file mode 100644 index 0000000000..e5f79a8c5a --- /dev/null +++ b/docs/source/_static/gallery.css @@ -0,0 +1,195 @@ +/* +Sphinx-Gallery has compatible CSS to fix default sphinx themes +Tested for Sphinx 1.3.1 for all themes: default, alabaster, sphinxdoc, +scrolls, agogo, traditional, nature, haiku, pyramid +Tested for Read the Docs theme 0.1.7 */ +.sphx-glr-thumbcontainer { + background: #fff; + border: solid #fff 1px; + -moz-border-radius: 5px; + -webkit-border-radius: 5px; + border-radius: 5px; + box-shadow: none; + float: left; + margin: 5px; + min-height: 230px; + padding-top: 5px; + position: relative; +} +.sphx-glr-thumbcontainer:hover { + border: solid #6200EE 1px; + box-shadow: 0 0 15px rgba(163, 142, 202, 0.5); +} +.sphx-glr-thumbcontainer a.internal { + bottom: 0; + display: block; + left: 0; + padding: 150px 10px 0; + position: absolute; + right: 0; + top: 0; +} +/* Next one is to avoid Sphinx traditional theme to cover all the +thumbnail with its default link Background color */ +.sphx-glr-thumbcontainer a.internal:hover { + background-color: transparent; +} + +.sphx-glr-thumbcontainer p { + margin: 0 0 .1em 0; +} +.sphx-glr-thumbcontainer .figure { + margin: 10px; + width: 160px; +} +.sphx-glr-thumbcontainer img { + display: inline; + max-height: 112px; + max-width: 160px; +} +.sphx-glr-thumbcontainer[tooltip]:hover:after { + background: rgba(0, 0, 0, 0.8); + -webkit-border-radius: 5px; + -moz-border-radius: 5px; + border-radius: 5px; + color: #fff; + content: attr(tooltip); + left: 95%; + padding: 5px 15px; + position: absolute; + z-index: 98; + width: 220px; + bottom: 52%; +} +.sphx-glr-thumbcontainer[tooltip]:hover:before { + border: solid; + border-color: #333 transparent; + border-width: 18px 0 0 20px; + bottom: 58%; + content: ''; + left: 85%; + position: absolute; + z-index: 99; +} + +.sphx-glr-script-out { + color: #888; + margin: 0; +} +p.sphx-glr-script-out { + padding-top: 0.7em; +} +.sphx-glr-script-out .highlight { + background-color: transparent; + margin-left: 2.5em; + margin-top: -2.1em; +} +.sphx-glr-script-out .highlight pre { + background-color: #fafae2; + border: 0; + max-height: 30em; + overflow: auto; + padding-left: 1ex; + margin: 0px; + word-break: break-word; +} +.sphx-glr-script-out + p { + margin-top: 1.8em; +} +blockquote.sphx-glr-script-out { + margin-left: 0pt; +} +.sphx-glr-script-out.highlight-pytb .highlight pre { + color: #000; + background-color: #ffe4e4; + border: 1px solid #f66; + margin-top: 10px; + padding: 7px; +} + +div.sphx-glr-footer { + text-align: center; +} + +div.sphx-glr-download { + margin: 1em auto; + vertical-align: middle; +} + +div.sphx-glr-download a { + background-color: #ffc; + background-image: linear-gradient(to bottom, #FFC, #d5d57e); + border-radius: 4px; + border: 1px solid #c2c22d; + color: #000; + display: inline-block; + font-weight: bold; + padding: 1ex; + text-align: center; +} + +div.sphx-glr-download code.download { + display: inline-block; + white-space: normal; + word-break: normal; + overflow-wrap: break-word; + /* border and background are given by the enclosing 'a' */ + border: none; + background: none; +} + +div.sphx-glr-download a:hover { + box-shadow: inset 0 1px 0 rgba(255,255,255,.1), 0 1px 5px rgba(0,0,0,.25); + text-decoration: none; + background-image: none; + background-color: #d5d57e; +} + +.sphx-glr-example-title > :target::before { + display: block; + content: ""; + margin-top: -50px; + height: 50px; + visibility: hidden; +} + +ul.sphx-glr-horizontal { + list-style: none; + padding: 0; +} +ul.sphx-glr-horizontal li { + display: inline; +} +ul.sphx-glr-horizontal img { + height: auto !important; +} + +.sphx-glr-single-img { + margin: auto; + display: block; + max-width: 100%; +} + +.sphx-glr-multi-img { + max-width: 42%; + height: auto; +} + +p.sphx-glr-signature a.reference.external { + -moz-border-radius: 5px; + -webkit-border-radius: 5px; + border-radius: 5px; + padding: 3px; + font-size: 75%; + text-align: right; + margin-left: auto; + display: table; +} + +.sphx-glr-clear{ + clear: both; +} + +a.sphx-glr-backref-instance { + text-decoration: none; +} diff --git a/docs/source/_templates/autosummary/base.rst b/docs/source/_templates/autosummary/base.rst new file mode 100644 index 0000000000..a58aa35ff9 --- /dev/null +++ b/docs/source/_templates/autosummary/base.rst @@ -0,0 +1,10 @@ +{% if referencefile %} +.. include:: {{ referencefile }} +{% endif %} + +{{ objname }} +{{ underline }} + +.. currentmodule:: {{ module }} + +.. auto{{ objtype }}:: {{ objname }} diff --git a/docs/source/_templates/autosummary/class.rst b/docs/source/_templates/autosummary/class.rst new file mode 100644 index 0000000000..e4d661a008 --- /dev/null +++ b/docs/source/_templates/autosummary/class.rst @@ -0,0 +1,49 @@ +{% if referencefile %} +.. include:: {{ referencefile }} +{% endif %} + +{{ objname }} +{{ underline }} + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + :no-members: + :no-inherited-members: + :no-special-members: + + {% block attributes_summary %} + {% if attributes %} + + .. rubric:: Attributes + + .. autosummary:: + :toctree: ../stubs/ + {% for item in all_attributes %} + {%- if not item.startswith('_') %} + {{ name }}.{{ item }} + {%- endif -%} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block methods_summary %} + {% if methods %} + + .. rubric:: Methods + + .. autosummary:: + :toctree: ../stubs/ + {% for item in all_methods %} + {%- if not item.startswith('_') or item in ['__call__', '__mul__', '__getitem__', '__len__'] %} + {{ name }}.{{ item }} + {%- endif -%} + {%- endfor %} + {% for item in inherited_members %} + {%- if item in ['__call__', '__mul__', '__getitem__', '__len__'] %} + {{ name }}.{{ item }} + {%- endif -%} + {%- endfor %} + + {% endif %} + {% endblock %} diff --git a/docs/source/_templates/autosummary/module.rst b/docs/source/_templates/autosummary/module.rst new file mode 100644 index 0000000000..11208a25c6 --- /dev/null +++ b/docs/source/_templates/autosummary/module.rst @@ -0,0 +1,41 @@ +{% if referencefile %} +.. include:: {{ referencefile }} +{% endif %} + +{{ objname }} +{{ underline }} + +.. automodule:: {{ fullname }} + + {% block functions %} + {% if functions %} + .. rubric:: Functions + + .. autosummary:: + {% for item in functions %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block classes %} + {% if classes %} + .. rubric:: Classes + + .. autosummary:: + {% for item in classes %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block exceptions %} + {% if exceptions %} + .. rubric:: Exceptions + + .. autosummary:: + {% for item in exceptions %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html new file mode 100644 index 0000000000..102d6029ed --- /dev/null +++ b/docs/source/_templates/layout.html @@ -0,0 +1,289 @@ +{# TEMPLATE VAR SETTINGS #} +{%- set url_root = pathto('', 1) %} +{%- if url_root == '#' %}{% set url_root = '' %}{% endif %} +{%- if not embedded and docstitle %} + {%- set titlesuffix = " — "|safe + docstitle|e %} +{%- else %} + {%- set titlesuffix = "" %} +{%- endif %} +{%- set lang_attr = 'en' if language == None else (language | replace('_', '-')) %} +{% import 'theme_variables.jinja' as theme_variables %} + + + + + + + {{ metatags }} + + {% block htmltitle %} + {{ title|striptags|e }}{{ titlesuffix }} + {% endblock %} + + {# FAVICON #} + {% if favicon %} + + {% endif %} + {# CANONICAL URL #} + {% if theme_canonical_url %} + + {% endif %} + + {# CSS #} + + {# OPENSEARCH #} + {% if not embedded %} + {% if use_opensearch %} + + {% endif %} + + {% endif %} + + + + {%- for css in css_files %} + {%- if css|attr("rel") %} + + {%- else %} + + {%- endif %} + {%- endfor %} + {%- for cssfile in extra_css_files %} + + {%- endfor %} + + {%- block linktags %} + {%- if hasdoc('about') %} + + {%- endif %} + {%- if hasdoc('genindex') %} + + {%- endif %} + {%- if hasdoc('search') %} + + {%- endif %} + {%- if hasdoc('copyright') %} + + {%- endif %} + {%- if next %} + + {%- endif %} + {%- if prev %} + + {%- endif %} + {%- endblock %} + {%- block extrahead %} {% endblock %} + + {# Keep modernizr in head - http://modernizr.com/docs/#installing #} + + + + + + + {% block extrabody %} {% endblock %} + + {# SIDE NAV, TOGGLES ON MOBILE #} + + {% include "versions.html" %} + +
+ Table of Contents + +
+ + + +
+
+
+ {% include "breadcrumbs.html" %} +
+ +
+ Shortcuts +
+
+ +
+
+ + {%- block content %} + {% if theme_style_external_links|tobool %} +
+ {% else %} +
+ {% endif %} +
+ {%- block document %} +
+ {% block body %}{% endblock %} +
+ {% if self.comments()|trim %} +
+ {% block comments %}{% endblock %} +
+ {% endif%} +
+ {%- endblock %} + {% include "footer.html" %} +
+ {%- endblock %} +
+ +
+
+
+ {{ toc }} +
+
+
+
+
+ + {% if not embedded %} + + {% if sphinx_version >= "1.8.0" %} + + {%- for scriptfile in script_files %} + {{ js_tag(scriptfile) }} + {%- endfor %} + {% else %} + + {%- for scriptfile in script_files %} + + {%- endfor %} + {% endif %} + + {% endif %} + + + + + + + + +{%- block footer %} {% endblock %} + +
+
+
+ + + +
+
+
+
+ + +
+
+
+ +
+
+ +
+
+
+ + + + + + + + diff --git a/docs/source/_templates/page.html b/docs/source/_templates/page.html new file mode 100644 index 0000000000..429a7dedd9 --- /dev/null +++ b/docs/source/_templates/page.html @@ -0,0 +1,14 @@ +{% extends "!page.html" %} + +{% block footer %} + +{% endblock %} \ No newline at end of file diff --git a/docs/source/_templates/theme_variables.jinja b/docs/source/_templates/theme_variables.jinja new file mode 100644 index 0000000000..625a44f17a --- /dev/null +++ b/docs/source/_templates/theme_variables.jinja @@ -0,0 +1,8 @@ +{%- set external_urls = { + 'github': 'https://github.com/Qiskit/retworkx', + 'docs': 'https://retworkx.readthedocs.io/en/stable/', + 'slack': 'https://qiskit.slack.com', + 'home': 'https://qiskit.org/', + 'resources': 'https://qiskit.org/learn', +} +-%} diff --git a/docs/source/conf.py b/docs/source/conf.py index 1b4bf0fb3e..3ae8c3225d 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -75,7 +75,7 @@ # General information about the project. project = u'retworkx' -copyright = u'2019, Matthew Treinish' +copyright = u'2021, retworkx Contributors' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -86,6 +86,15 @@ # The full version, including alpha/beta/rc tags. release = '0.9.0' +rst_prolog = """ +.. raw:: html + +


+ +.. |version| replace:: {0} +""".format(release) + + # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. #language = None @@ -225,7 +234,7 @@ # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ ('index', 'retworkx.tex', u'retworkx Documentation', - u'Matthew Treinish', 'manual'), + u'retworkx Contributors', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of @@ -256,7 +265,7 @@ #man_pages = [ # ('MANUAL', 'retworkx', # u'A parallel Python test runner built around subunit', -# [u'Matthew Treinish'], 1) +# [u'retworkx Contributors'], 1) #] # If true, show URL addresses after external links.