Merge pull request #3023 from getpelican/furo-sphinx-theme

Use Furo as Sphinx documentation theme

docs/_templates/page.html

@@ -0,0 +1,199 @@
+{% extends "base.html" %}
+
+{% block body -%}
+{{ super() }}
+{% include "partials/icons.html" %}
+
+<input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation">
+<input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc">
+<label class="overlay sidebar-overlay" for="__navigation">
+  <div class="visually-hidden">Hide navigation sidebar</div>
+</label>
+<label class="overlay toc-overlay" for="__toc">
+  <div class="visually-hidden">Hide table of contents sidebar</div>
+</label>
+
+{% if theme_announcement -%}
+<div class="announcement">
+  <aside class="announcement-content">
+    {% block announcement %} {{ theme_announcement }} {% endblock announcement %}
+  </aside>
+</div>
+{%- endif %}
+
+<div class="page">
+  <header class="mobile-header">
+    <div class="header-left">
+      <label class="nav-overlay-icon" for="__navigation">
+        <div class="visually-hidden">Toggle site navigation sidebar</div>
+        <i class="icon"><svg><use href="#svg-menu"></use></svg></i>
+      </label>
+    </div>
+    <div class="header-center">
+      <a href="{{ pathto(master_doc) }}"><div class="brand">{{ docstitle if docstitle else project }}</div></a>
+    </div>
+    <div class="header-right">
+      <div class="theme-toggle-container theme-toggle-header">
+        <button class="theme-toggle">
+          <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
+          <svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
+          <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
+          <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
+        </button>
+      </div>
+      <label class="toc-overlay-icon toc-header-icon{% if furo_hide_toc %} no-toc{% endif %}" for="__toc">
+        <div class="visually-hidden">Toggle table of contents sidebar</div>
+        <i class="icon"><svg><use href="#svg-toc"></use></svg></i>
+      </label>
+    </div>
+  </header>
+  <aside class="sidebar-drawer">
+    <div class="sidebar-container">
+      {% block left_sidebar %}
+      <div class="sidebar-sticky">
+        {%- for sidebar_section in sidebars %}
+          {%- include sidebar_section %}
+        {%- endfor %}
+      </div>
+      {% endblock left_sidebar %}
+    </div>
+  </aside>
+  <div class="main">
+    <div class="content">
+      <div class="article-container">
+        <a href="#" class="back-to-top muted-link">
+          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
+            <path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8v12z"></path>
+          </svg>
+          <span>{% trans %}Back to top{% endtrans %}</span>
+        </a>
+        <div class="content-icon-container">
+          {% if theme_top_of_page_button == "edit" -%}
+          {%- include "components/edit-this-page.html" with context -%}
+          {%- elif theme_top_of_page_button != None -%}
+          {{ warning("Got an unsupported value for 'top_of_page_button'") }}
+          {%- endif -%}
+          {#- Theme toggle -#}
+          <div class="theme-toggle-container theme-toggle-content">
+            <button class="theme-toggle">
+              <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
+              <svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
+              <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
+              <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
+            </button>
+          </div>
+          <label class="toc-overlay-icon toc-content-icon{% if furo_hide_toc %} no-toc{% endif %}" for="__toc">
+            <div class="visually-hidden">Toggle table of contents sidebar</div>
+            <i class="icon"><svg><use href="#svg-toc"></use></svg></i>
+          </label>
+        </div>
+        <article role="main">
+          {% block content %}{{ body }}{% endblock %}
+        </article>
+      </div>
+      <footer>
+        {% block footer %}
+        <div class="related-pages">
+          {% if next -%}
+            <a class="next-page" href="{{ next.link }}">
+              <div class="page-info">
+                <div class="context">
+                  <span>{{ _("Next") }}</span>
+                </div>
+                <div class="title">{{ next.title }}</div>
+              </div>
+              <svg><use href="#svg-arrow-right"></use></svg>
+            </a>
+          {%- endif %}
+          {% if prev -%}
+            <a class="prev-page" href="{{ prev.link }}">
+              <svg><use href="#svg-arrow-right"></use></svg>
+              <div class="page-info">
+                <div class="context">
+                  <span>{{ _("Previous") }}</span>
+                </div>
+                {% if prev.link == pathto(master_doc) %}
+                <div class="title">{{ _("Home") }}</div>
+                {% else %}
+                <div class="title">{{ prev.title }}</div>
+                {% endif %}
+              </div>
+            </a>
+          {%- endif %}
+        </div>
+        <div class="bottom-of-page">
+          <div class="left-details">
+            {%- if show_copyright %}
+            <div class="copyright">
+              {%- if hasdoc('copyright') %}
+                {% trans path=pathto('copyright'), copyright=copyright|e -%}
+                  <a href="{{ path }}">Copyright</a> &#169; {{ copyright }}
+                {%- endtrans %}
+              {%- else %}
+                {% trans copyright=copyright|e -%}
+                  Copyright &#169; {{ copyright }}, <a href="https://justinmayer.com">Justin Mayer</a>, Alexis Metaireau, and contributors
+                {%- endtrans %}
+              {%- endif %}
+            </div>
+            {%- endif %}
+            {%- if last_updated -%}
+            <div class="last-updated">
+              {% trans last_updated=last_updated|e -%}
+                Last updated on {{ last_updated }}
+              {%- endtrans -%}
+            </div>
+            {%- endif %}
+          </div>
+          <div class="right-details">
+            <div class="icons">
+              {% if theme_footer_icons -%}
+              {% for icon_dict in theme_footer_icons -%}
+              <a class="muted-link {{ icon_dict.class }}" href="{{ icon_dict.url }}" aria-label="{{ icon_dict.name }}">
+                {{- icon_dict.html -}}
+              </a>
+              {% endfor %}
+              {%- else -%}
+              {#- Show Read the Docs project -#}
+              {%- if READTHEDOCS and slug -%}
+              <a class="muted-link" href="https://readthedocs.org/projects/{{ slug }}" aria-label="On Read the Docs">
+                <svg x="0px" y="0px" viewBox="-125 217 360 360" xml:space="preserve">
+                  <path fill="currentColor" d="M39.2,391.3c-4.2,0.6-7.1,4.4-6.5,8.5c0.4,3,2.6,5.5,5.5,6.3 c0,0,18.5,6.1,50,8.7c25.3,2.1,54-1.8,54-1.8c4.2-0.1,7.5-3.6,7.4-7.8c-0.1-4.2-3.6-7.5-7.8-7.4c-0.5,0-1,0.1-1.5,0.2 c0,0-28.1,3.5-50.9,1.6c-30.1-2.4-46.5-7.9-46.5-7.9C41.7,391.3,40.4,391.1,39.2,391.3z M39.2,353.6c-4.2,0.6-7.1,4.4-6.5,8.5 c0.4,3,2.6,5.5,5.5,6.3c0,0,18.5,6.1,50,8.7c25.3,2.1,54-1.8,54-1.8c4.2-0.1,7.5-3.6,7.4-7.8c-0.1-4.2-3.6-7.5-7.8-7.4 c-0.5,0-1,0.1-1.5,0.2c0,0-28.1,3.5-50.9,1.6c-30.1-2.4-46.5-7.9-46.5-7.9C41.7,353.6,40.4,353.4,39.2,353.6z M39.2,315.9 c-4.2,0.6-7.1,4.4-6.5,8.5c0.4,3,2.6,5.5,5.5,6.3c0,0,18.5,6.1,50,8.7c25.3,2.1,54-1.8,54-1.8c4.2-0.1,7.5-3.6,7.4-7.8 c-0.1-4.2-3.6-7.5-7.8-7.4c-0.5,0-1,0.1-1.5,0.2c0,0-28.1,3.5-50.9,1.6c-30.1-2.4-46.5-7.9-46.5-7.9 C41.7,315.9,40.4,315.8,39.2,315.9z M39.2,278.3c-4.2,0.6-7.1,4.4-6.5,8.5c0.4,3,2.6,5.5,5.5,6.3c0,0,18.5,6.1,50,8.7 c25.3,2.1,54-1.8,54-1.8c4.2-0.1,7.5-3.6,7.4-7.8c-0.1-4.2-3.6-7.5-7.8-7.4c-0.5,0-1,0.1-1.5,0.2c0,0-28.1,3.5-50.9,1.6 c-30.1-2.4-46.5-7.9-46.5-7.9C41.7,278.2,40.4,278.1,39.2,278.3z M-13.6,238.5c-39.6,0.3-54.3,12.5-54.3,12.5v295.7 c0,0,14.4-12.4,60.8-10.5s55.9,18.2,112.9,19.3s71.3-8.8,71.3-8.8l0.8-301.4c0,0-25.6,7.3-75.6,7.7c-49.9,0.4-61.9-12.7-107.7-14.2 C-8.2,238.6-10.9,238.5-13.6,238.5z M19.5,257.8c0,0,24,7.9,68.3,10.1c37.5,1.9,75-3.7,75-3.7v267.9c0,0-19,10-66.5,6.6 C59.5,536.1,19,522.1,19,522.1L19.5,257.8z M-3.6,264.8c4.2,0,7.7,3.4,7.7,7.7c0,4.2-3.4,7.7-7.7,7.7c0,0-12.4,0.1-20,0.8 c-12.7,1.3-21.4,5.9-21.4,5.9c-3.7,2-8.4,0.5-10.3-3.2c-2-3.7-0.5-8.4,3.2-10.3c0,0,0,0,0,0c0,0,11.3-6,27-7.5 C-16,264.9-3.6,264.8-3.6,264.8z M-11,302.6c4.2-0.1,7.4,0,7.4,0c4.2,0.5,7.2,4.3,6.7,8.5c-0.4,3.5-3.2,6.3-6.7,6.7 c0,0-12.4,0.1-20,0.8c-12.7,1.3-21.4,5.9-21.4,5.9c-3.7,2-8.4,0.5-10.3-3.2c-2-3.7-0.5-8.4,3.2-10.3c0,0,11.3-6,27-7.5 C-20.5,302.9-15.2,302.7-11,302.6z M-3.6,340.2c4.2,0,7.7,3.4,7.7,7.7s-3.4,7.7-7.7,7.7c0,0-12.4-0.1-20,0.7 c-12.7,1.3-21.4,5.9-21.4,5.9c-3.7,2-8.4,0.5-10.3-3.2c-2-3.7-0.5-8.4,3.2-10.3c0,0,11.3-6,27-7.5C-16,340.1-3.6,340.2-3.6,340.2z" />
+                </svg>
+              </a>
+              {%- endif -%}
+              {#- Show GitHub repository home -#}
+              {%- if READTHEDOCS and display_github and github_user != "None" and github_repo != "None" -%}
+              <a class="muted-link" href="https://github.com/{{ github_user }}/{{ github_repo }}" aria-label="On GitHub">
+                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
+                  <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
+                </svg>
+              </a>
+              {%- endif -%}
+              {%- endif %}
+            </div>
+          </div>
+        </div>
+        {% endblock footer %}
+      </footer>
+    </div>
+    <aside class="toc-drawer{% if furo_hide_toc %} no-toc{% endif %}">
+      {% block right_sidebar %}
+      {% if not furo_hide_toc %}
+      <div class="toc-sticky toc-scroll">
+        <div class="toc-title-container">
+          <span class="toc-title">
+            {{ _("Contents") }}
+          </span>
+        </div>
+        <div class="toc-tree-container">
+          <div class="toc-tree">
+            {{ toc }}
+          </div>
+        </div>
+      </div>
+      {% endif %}
+      {% endblock right_sidebar %}
+    </aside>
+  </div>
+</div>
+{%- endblock %}

docs/conf.py

@@ -1,10 +1,9 @@
+import datetime
 import os
 import sys
 
 from pelican import __version__
 
-on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
-
 sys.path.append(os.path.abspath(os.pardir))
 
 # -- General configuration ----------------------------------------------------
@@ -15,7 +14,8 @@
 source_suffix = '.rst'
 master_doc = 'index'
 project = 'Pelican'
-copyright = '2010 – present, Justin Mayer, Alexis Metaireau, and contributors'
+year = datetime.datetime.now().date().year
+copyright = f'2010–{year}'
 exclude_patterns = ['_build']
 release = __version__
 version = '.'.join(release.split('.')[:1])
@@ -24,25 +24,20 @@
 .. |last_stable| replace:: :pelican-doc:`{}`
 '''.format(last_stable)
 
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
-
 extlinks = {
-    'pelican-doc':  ('https://docs.getpelican.com/%s/', '')
+    'pelican-doc':  ('https://docs.getpelican.com/%s/', '%s')
 }
 
 # -- Options for HTML output --------------------------------------------------
 
-html_theme = 'default'
-if not on_rtd:
-    try:
-        import sphinx_rtd_theme
-        html_theme = 'sphinx_rtd_theme'
-        html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
-    except ImportError:
-        pass
-
+html_theme = 'furo'
+html_title = f'<strong>{project}</strong> <i>{release}</i>'
 html_static_path = ['_static']
+html_theme_options = {
+    'light_logo': 'pelican-logo.svg',
+    'dark_logo': 'pelican-logo.svg',
+    'navigation_with_keys': True,
+}
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'Pelicandoc'

pelican/tools/pelican_import.py

@@ -350,7 +350,7 @@ def dc2fields(file):
             else:
                 i = 1
                 j = 1
-                while(i <= int(tag[:1])):
+                while (i <= int(tag[:1])):
                     newtag = tag.split('"')[j].replace('\\', '')
                     tags.append(
                         BeautifulSoup(

pyproject.toml

@@ -30,7 +30,7 @@ classifiers = [
 "Tracker" = "https://github.com/getpelican/pelican/issues"
 
 [tool.poetry.dependencies]
-python = "^3.6"
+python = ">=3.7,<4.0"
 blinker = ">=1.4"
 docutils = ">=0.16"
 feedgenerator = ">=1.9"
@@ -44,19 +44,18 @@ markdown = {version = ">=3.1", optional = true}
 
 [tool.poetry.dev-dependencies]
 BeautifulSoup4 = "^4.9"
-jinja2 = "~2.11"
+jinja2 = "~3.1.2"
 lxml = "^4.3"
-markdown = "~3.3.4"
+markdown = "~3.3.7"
 typogrify = "^2.0"
-sphinx = "<4.4.0"
-sphinx_rtd_theme = "^0.5"
+sphinx = "^5.1"
+furo = "2022.06.21"
 livereload = "^2.6"
 psutil = {version = "^5.7", optional = true}
 pygments = "~2.8"
-pytest = "^6.0"
-pytest-cov = "^2.8"
-pytest-pythonpath = "^0.7.3"
-pytest-sugar = "^0.9.4"
+pytest = "^7.1"
+pytest-cov = "^3.0"
+pytest-sugar = "^0.9.5"
 pytest-xdist = "^2.0"
 tox = {version = "^3.13", optional = true}
 flake8 = "^3.8"

requirements/docs.pip

@@ -1,3 +1,3 @@
-sphinx<4.4.0
-sphinx_rtd_theme
+sphinx<6.0
+furo
 livereload

requirements/style.pip

@@ -1,2 +1,2 @@
-flake8
+flake8<4.0
 flake8-import-order

requirements/test.pip

@@ -5,7 +5,7 @@ pytest-cov
 pytest-xdist[psutil]
 
 # Optional Packages
-Markdown==3.3.4
+Markdown==3.3.7
 BeautifulSoup4
 lxml
 typogrify