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
Qiskit · May 21, 2021 · cc571eb · cc571eb
1 parent 4ef9ed9
commit cc571eb
Show file tree

Hide file tree

Showing 9 changed files with 619 additions and 3 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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 %}