Simplify conf.py and RST to prep for Furo vs Pytorch config (#268)

We plan to land the Furo proof of concept soon
(#233), so that people
can more easily finish Qiskit-ifying the theme.

We have to set slightly different conf.py values, like
`html_theme_options`. We'll do that by something like this:

```python
if "FURO" in os.environ:
   # furo options
else:
   # pytorch options
```

So, this is prework to make `conf.py` as simple as possible before
adding new complexity.

--

This also removes the unnecessary `.. contents::` directives from some
pages. They didn't actually do anything, but cause a huge warning when
using Furo. With Pytorch, we still have our right page-level table of
contents even without it.

example_docs/docs/conf.py

@@ -10,60 +10,27 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-# pylint: disable=invalid-name
-# Configuration file for the Sphinx documentation builder.
-#
-# This file does only contain a selection of the most common options. For a
-# full list see the documentation:
-# http://www.sphinx-doc.org/en/master/config
-
-# -- Path setup --------------------------------------------------------------
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
-
-"""
-Sphinx documentation builder
-"""
 import os
 import sys
 
+# This allows autodoc to find the `api_example` folder and
+# for us to register our `docs.language_utils` extension.
 sys.path.insert(0, os.path.abspath(".."))
 
-# -- Project information -----------------------------------------------------
 project = 'Qiskit sphinx theme'
-copyright = '2020, Qiskit Development Team'  # pylint: disable=redefined-builtin
+project_copyright = '2020, Qiskit Development Team'
 author = 'Qiskit Development Team'
+language = "en"
+release = "9.99"
 
-import qiskit_sphinx_theme
-
-release = qiskit_sphinx_theme.__version__
-
-html_theme = 'qiskit_sphinx_theme'  # use the theme in subdir 'theme'
-templates_path = ['_templates']
-
-rst_prolog = """
-.. |version| replace:: {0}
-""".format(release)
-
+# This allows including custom CSS and HTML templates.
 html_static_path = ['_static']
 templates_path = ['_templates']
 html_css_files = ['gallery.css']
 
-# -- General configuration ---------------------------------------------------
-
-# If your documentation needs a minimal Sphinx version, state it here.
-#
-# needs_sphinx = '1.0'
+# Sphinx should ignore these patterns when building.
+exclude_patterns = ['_build', '**.ipynb_checkpoints']
 
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
 extensions = [
     'sphinx.ext.napoleon',
     'sphinx.ext.autodoc',
@@ -76,96 +43,55 @@
     "nbsphinx",
 ]
 
-# -----------------------------------------------------------------------------
-# Autodoc
-# -----------------------------------------------------------------------------
-
-# Keep aligned with Terra.
-autosummary_generate = True
-autosummary_generate_overwrite = False
-autoclass_content = "both"
-autodoc_typehints = "description"
-autodoc_typehints_description_target = "documented_params"
-
-
-# If true, figures, tables and code-blocks are automatically numbered if they
-# have a caption.
-numfig = True
-
-# A dictionary mapping 'figure', 'table', 'code-block' and 'section' to
-# strings that are used for format of figure numbers. As a special character,
-# %s will be replaced to figure number.
-numfig_format = {
-    'table': 'Table %s'
-}
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = "en"
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', '**.ipynb_checkpoints']
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'colorful'
-
-# A boolean that decides whether module names are prepended to all object names
-# (for object types where a “module” of some kind is defined), e.g. for
-# py:function directives.
-add_module_names = False
-
-# A list of prefixes that are ignored for sorting the Python module index
-# (e.g., if this is set to ['foo.'], then foo.bar is shown under B, not F).
-# This can be handy if you document a project that consists of a single
-# package. Works only for the HTML builder currently.
-modindex_common_prefix = ['qiskit.']
-
-# -- Configuration for extlinks extension ------------------------------------
-# Refer to https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
-
-
-# -- Options for HTML output -------------------------------------------------
-
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
-
-#html_sidebars = {'**': ['globaltoc.html']}
 html_last_updated_fmt = '%Y/%m/%d'
 
+html_theme = 'qiskit_sphinx_theme'
 html_theme_options = {
     'logo_only': True,
     'display_version': True,
     'prev_next_buttons_location': 'bottom',
 }
-
-# qiskit package specific variables
 html_context = {
-    # toggle analytics
+    # Add "Was this page useful?" to the footer.
     'analytics_enabled': True,
-
-    # dummy list for versions
+    # Users of the theme can set prior version numbers. They'll
+    # show up in the sidebar under the "Previous Versions" section.
     'version_list': [0.1, 0.2, 0.3],
-
-    # make captioned headings into dropdowns
+    # This allows docs authors to have folders that can be
+    # closed and opened in the left sidebar.
     'expandable_sidebar': True
 }
 
+# Sets a better style for code syntax highlighting.
+pygments_style = 'colorful'
+
+# This allows RST files to put `|version|` in their file and
+# have it updated with the release set in conf.py.
+rst_prolog = f"""
+.. |version| replace:: {release}
+"""
+
+# Options for autodoc. These reflect the values from Terra.
+autosummary_generate = True
+autosummary_generate_overwrite = False
+autoclass_content = "both"
+autodoc_typehints = "description"
+autodoc_typehints_description_target = "documented_params"
 
-# -----------------------------------------------------------------------------
-# nbsphinx
-# -----------------------------------------------------------------------------
+# This adds numbers to the captions for figures, tables,
+# and code blocks.
+numfig = True
+numfig_format = {
+    'table': 'Table %s'
+}
 
+# Settings for Jupyter notebooks.
 nbsphinx_execute = "never"
 nbsphinx_thumbnails = {
     "sphinx_guide/notebook": "_static/no_image.png",
 }
 
 
-# set up custom extension for languages
 def setup(app):
-    app.setup_extension('docs.language_utils')
+    """Entry point for Sphinx extensions."""
+    app.setup_extension('docs.language_utils')

example_docs/docs/sphinx_guide/lists.rst

@@ -2,9 +2,6 @@
 Lists
 =====
 
-
-.. contents:: Table of Contents
-
 Enumerated Lists
 ----------------
 

example_docs/docs/sphinx_guide/paragraph.rst

@@ -10,8 +10,6 @@
 Paragraph Level Markup
 **********************
 
-.. contents:: Table of Contents
-
 Inline Markup
 =============
 
@@ -238,8 +236,6 @@ Directives
 Contents
 --------
 
-.. contents:: :local:
-
 These are just a sample of the many reStructuredText Directives. For others, please see:
 http://docutils.sourceforge.net/docs/ref/rst/directives.html.
 

example_docs/docs/sphinx_guide/structural.rst

@@ -2,8 +2,6 @@
 Generic formatting
 ==================
 
-.. contents:: Table of Contents
-
 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec lorem neque, interdum in ipsum nec,
 finibus dictum velit. Ut eu efficitur arcu, id aliquam erat. In sit amet diam gravida, imperdiet tellus eu,
 gravida nisl. Praesent aliquet odio eget libero elementum, quis rhoncus tellus tincidunt.