Use the sphinx-book-theme instead of rtd-theme (fatiando#236)

The new theme is much nicer and includes some of the things we had to hack the template of RTD theme to achieve (edit buttons, open issue, etc).
BjoernLudwigPTB · Jun 1, 2021 · 1df619d · 1df619d
1 parent 43f35b1
commit 1df619d
Show file tree

Hide file tree

Showing 8 changed files with 81 additions and 242 deletions.
diff --git a/README.rst b/README.rst
@@ -27,7 +27,6 @@ Part of the `Fatiando a Terra <https://www.fatiando.org>`__ project
 
 .. placeholder-for-doc-index
 
-🚨 **Pooch v1.2.0 is the last release that is compatible with Python 3.5.** 🚨
 
 About
 -----

diff --git a/doc/_static/style.css b/doc/_static/style.css
@@ -1,123 +1,18 @@
-/* To stick the footer to the bottom of the page */
-html {
+span.project-version {
+  color: #999999;
+  font-size: 0.8em;
+  font-weight: 600;
+  margin-left: 5px;
 }
 
-body {
-    font-family: 'Open Sans', sans-serif;
+.table td {
+  padding: 0.5rem;
 }
 
-h1, h2, h3, h4 {
-    font-weight: 300;
-    font-family: "Open Sans",sans-serif;
+.table td  p {
+  margin-bottom: 0 !important;
 }
 
-h1 {
-    font-size: 200%;
-}
-
-.sidebar-title {
-    margin-top: 10px;
-    margin-bottom: 0px;
-}
-
-.banner {
-    padding-bottom: 60px;
-    text-align: center;
-}
-
-.banner img {
-    margin-bottom: 40px;
-}
-
-.api-module {
-	margin-bottom: 80px;
-}
-
-.youtube-embed {
-    max-width: 600px;
-    margin-bottom: 24px;
-}
-
-.video-container {
-    position:relative;
-    padding-bottom:56.25%;
-    padding-top:30px;
-    height:0;
-    overflow:hidden;
-}
-
-.video-container iframe, .video-container object, .video-container embed {
-    position:absolute;
-    top:0;
-    left:0;
-    width:100%;
-    height:100%;
-}
-
-.wy-nav-content {
-    max-width: 1000px;
-}
-
-.wy-nav-top {
-    background-color: #555555;
-}
-
-.wy-side-nav-search {
-    background-color: #555555;
-}
-
-.wy-side-nav-search > a img.logo {
-    width: 30%;
-}
-
-.wy-side-nav-search input[type="text"] {
-    border-color: #555555;
-}
-
-/* Remove the padding from the Parameters table */
-.rst-content table.field-list .field-name {
-    padding-left: 0px;
-}
-
-/* Lign up the Parameters section with the descriptions */
-.rst-content table.field-list td {
-    padding-top: 8px;
-}
-
-/* Don't let captions be italic */
-.rst-content div.figure p.caption {
-    font-style: normal;
-}
-
-.rst-content .highlight > pre {
-    font-size: 14px;
-}
-
-.rst-content img {
-    max-width: 100%;
-}
-
-.source-link {
-    float: right;
-}
-
-.rst-content blockquote {
-    margin-left: 0;
-    padding-left: 10px;
-    color: #888888;
-    border-left: #dddddd solid 3px;
-    padding-bottom: 4px;
-}
-
-.rst-content blockquote p {
-    margin-bottom: 0;
-}
-
-/* Don't let the edit and notebook download links disappear on mobile. */
-@media screen and (max-width: 480px) {
-    .wy-breadcrumbs li.source-link {
-        float:none;
-        display: block;
-        margin-top: 20px;
-    }
+.py-obj {
+  margin-right: 0.15rem;
 }
diff --git a/doc/_templates/breadcrumbs.html b/doc/_templates/breadcrumbs.html
diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html
@@ -19,30 +19,8 @@
 
 {% block htmltitle %}
     {% if title == '' or title == 'Home' %}
-        <title>{{ docstitle|e }} {{ version }}</title>
+        <title>{{ docstitle|striptags|e }}</title>
     {% else %}
-    <title>{{ title|striptags|e }}{{ titlesuffix }} {{ version }}</title>
-    {% endif %}
-{% endblock %}
-
-
-{% block menu %}
-    {{ super() }}
-
-    {% if menu_links %}
-        <p class="caption">
-            <span class="caption-text">
-            {% if menu_links_name %}
-                {{ menu_links_name }}
-            {% else %}
-                External links
-            {% endif %}
-            </span>
-        </p>
-        <ul>
-            {% for text, link in menu_links %}
-                <li class="toctree-l1"><a href="{{ link }}">{{ text }}</a></li>
-            {% endfor %}
-        </ul>
+        <title>{{ title|striptags|e }}{{ titlesuffix }}</title>
     {% endif %}
 {% endblock %}
diff --git a/doc/conf.py b/doc/conf.py
@@ -4,13 +4,24 @@
 #
 # This code is part of the Fatiando a Terra project (https://www.fatiando.org)
 #
-import sys
 import os
 import datetime
-import sphinx_rtd_theme
 
 import pooch
 
+
+# Project information
+# -----------------------------------------------------------------------------
+project = "Pooch"
+copyright = f"{datetime.date.today().year}, The {project} Developers"
+if len(pooch.__version__.split(".")) > 3:
+    version = "dev"
+else:
+    version = pooch.__version__
+
+
+# General configuration
+# -----------------------------------------------------------------------------
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
@@ -23,6 +34,8 @@
     "sphinx.ext.napoleon",
 ]
 
+# Configuration to include links to other project docs when referencing
+# functions/classes
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
     "pandas": ("http://pandas.pydata.org/pandas-docs/stable/", None),
@@ -44,70 +57,40 @@
 exclude_patterns = ["_build", "**.ipynb_checkpoints"]
 source_suffix = ".rst"
 # The encoding of source files.
-source_encoding = "utf-8-sig"
+source_encoding = "utf-8"
 master_doc = "index"
+pygments_style = "default"
+add_function_parentheses = False
 
-# General information about the project
-year = datetime.date.today().year
-project = "Pooch"
-copyright = f"2018-{year}, The Pooch Developers."
-if len(pooch.__version__.split("+")) > 1 or pooch.__version__ == "unknown":
-    version = "dev"
-else:
-    version = pooch.__version__
-
-# These enable substitutions using |variable| in the rst files
-rst_epilog = f"""
-.. |year| replace:: {year}
-"""
 
-html_last_updated_fmt = "%b %d, %Y"
-html_title = project
+# HTML output configuration
+# -----------------------------------------------------------------------------
+html_title = f'{project} <span class="project-version">{version}</span>'
 html_short_title = project
 html_logo = "_static/pooch-logo.png"
 html_favicon = "_static/favicon.png"
+html_last_updated_fmt = "%b %d, %Y"
+html_copy_source = True
 html_static_path = ["_static"]
+# CSS files are relative to the static path
+html_css_files = ["style.css"]
 html_extra_path = []
-pygments_style = "default"
-add_function_parentheses = False
 html_show_sourcelink = False
 html_show_sphinx = True
 html_show_copyright = True
 
-# Theme config
-html_theme = "sphinx_rtd_theme"
-html_theme_options = {"logo_only": True, "display_version": True}
-html_context = {
-    "menu_links_name": "Getting help and contributing",
-    "menu_links": [
-        (
-            '<i class="fa fa-external-link-square fa-fw"></i> Fatiando a Terra',
-            "https://www.fatiando.org",
-        ),
-        (
-            '<i class="fa fa-users fa-fw"></i> Contributing',
-            "https://github.com/fatiando/pooch/blob/master/CONTRIBUTING.md",
-        ),
-        (
-            '<i class="fa fa-gavel fa-fw"></i> Code of Conduct',
-            "https://github.com/fatiando/pooch/blob/master/CODE_OF_CONDUCT.md",
-        ),
-        ('<i class="fa fa-comment fa-fw"></i> Contact', "http://contact.fatiando.org"),
-        (
-            '<i class="fa fa-github fa-fw"></i> Source Code',
-            "https://github.com/fatiando/pooch",
-        ),
-    ],
-    # Custom variables to enable "Improve this page"" and "Download notebook"
-    # links
-    "doc_path": "doc",
-    "galleries": "",
-    "gallery_dir": "",
-    "github_repo": "fatiando/pooch",
-    "github_version": "master",
+html_theme = "sphinx_book_theme"
+html_theme_options = {
+    "repository_url": f"https://github.com/fatiando/{project.lower()}",
+    "repository_branch": "master",
+    "path_to_docs": "doc",
+    "launch_buttons": {
+        "binderhub_url": "https://mybinder.org",
+        "notebook_interface": "jupyterlab",
+    },
+    "use_edit_page_button": True,
+    "use_issues_button": True,
+    "use_repository_button": True,
+    "use_download_button": True,
+    "home_page_in_toc": True,
 }
-
-
-# Load the custom CSS files (needs sphinx >= 1.6 for this to work)
-def setup(app):
-    app.add_stylesheet("style.css")
diff --git a/doc/index.rst b/doc/index.rst
@@ -1,10 +1,17 @@
 .. title:: Home
-.. raw:: html
 
-    <div class="banner">
-        <img src="_static/readme-banner.png" alt="Pooch">
-        <h2>A part of the <a href="https://www.fatiando.org/">Fatiando a Terra</a> project.</h2>
-    </div>
+========
+|banner|
+========
+
+.. |banner| image:: _static/readme-banner.png
+    :alt: Pooch Documentation
+    :align: middle
+
+.. seealso::
+
+    Pooch is a part of the
+    `Fatiando a Terra <https://www.fatiando.org/>`_ project.
 
 .. include:: ../README.rst
     :start-after: placeholder-for-doc-index
@@ -36,3 +43,14 @@
 
     api/index.rst
     changes.rst
+
+.. toctree::
+    :maxdepth: 2
+    :hidden:
+    :caption: Getting help and contributing
+
+    Join the community <http://contact.fatiando.org>
+    How to contribute <https://github.com/fatiando/harmonica/blob/master/CONTRIBUTING.md>
+    Code of Conduct <https://github.com/fatiando/harmonica/blob/master/CODE_OF_CONDUCT.md>
+    Source code on GitHub <https://github.com/fatiando/harmonica>
+    The Fatiando a Terra project <https://www.fatiando.org>