Merge pull request #1990 from sopel-irc/furo-docs

docs: switch to Furo theme
sopel-irc · Jul 3, 2021 · fc85888 · fc85888
2 parents f1bc92d + 9a574ec
commit fc85888
Show file tree

Hide file tree

Showing 21 changed files with 98 additions and 89 deletions.
diff --git a/dev-requirements.txt b/dev-requirements.txt
@@ -3,11 +3,12 @@ flake8
 flake8-coding
 flake8-future-import
 flake8-import-order
+furo==2021.6.24b37  # Sphinx theme
 pytest>=4.6,<4.7
 pytest-vcr==1.0.2
 requests-mock==1.9.1
-sphinx
-# further constrain autoprogram version because the new (in 2021) maintainer
-# already demonstrated a willingness to make major changes in patch versions
-sphinxcontrib-autoprogram<=0.1.7
+sphinx>=4,<5
+# specify exact autoprogram version because the new (in 2021) maintainer
+# showed that they will indeed make major changes in patch versions
+sphinxcontrib-autoprogram==0.1.7
 vcrpy<3.0.0
diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css
@@ -1,5 +1,22 @@
-.section dl.py:not(:first-of-type) {
-    margin-top: 1.5em;
+img.sidebar-logo.only-dark {
+  /* Furo sets 0.8 opacity on color-foreground-primary for dark mode,
+     but there's no variable for it. */
+  opacity: 0.8;
+}
+::-webkit-scrollbar {
+  width: 11px;
+}
+* {
+  scrollbar-width: thin;
+  scrollbar-color: var(--color-foreground-muted) transparent;
+}
+::-webkit-scrollbar-track {
+  background: transparent;
+}
+::-webkit-scrollbar-thumb {
+  background-color: var(--color-foreground-muted) ;
+  border-radius: 6px;
+  border: 3px solid var(--color-background-primary);
 }
 
 .underline {

diff --git a/docs/source/_static/sopel.png → docs/source/_static/sopel-black.png b/docs/source/_static/sopel.png → docs/source/_static/sopel-black.png
diff --git a/docs/source/_static/sopel-white.png b/docs/source/_static/sopel-white.png
diff --git a/docs/source/api.rst b/docs/source/api.rst
@@ -8,8 +8,6 @@ Note that ``sopel.web`` was deprecated in 6.2.0, and is not included in this
 documentation; it will be removed completely in Sopel 8. Plugins should use
 `requests <https://github.com/psf/requests>`_ directly.
 
-.. contents::
-
 sopel.tools
 -----------
 

diff --git a/docs/source/cli.rst b/docs/source/cli.rst
@@ -20,10 +20,6 @@ Certain command-line options can be passed via environment variables. Also see
 the :ref:`section on environment variables <Supported environment variables>`
 for more possibilities.
 
-.. contents::
-    :local:
-    :depth: 1
-
 
 The ``sopel`` command
 =====================
@@ -106,10 +102,10 @@ overrides the value from Sopel's config file.
 
 The variable name Sopel looks for is structured as follows:
 
-  * ``SOPEL_`` prefix (to prevent collisions with other programs)
-  * The section name in UPPERCASE, e.g. ``CORE`` or ``PLUGIN_NAME``
-  * ``_`` as separator
-  * The setting name in UPPERCASE, e.g. ``NICK`` or ``API_KEY``
+* ``SOPEL_`` prefix (to prevent collisions with other programs)
+* The section name in UPPERCASE, e.g. ``CORE`` or ``PLUGIN_NAME``
+* ``_`` as separator
+* The setting name in UPPERCASE, e.g. ``NICK`` or ``API_KEY``
 
 For example, take this stripped-down config file:
 

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -64,8 +64,8 @@
 master_doc = 'index'
 
 # General information about the project.
-project = u'Sopel'
-copyright = u'2012-2019, Sopel contributors'
+project = 'Sopel'
+copyright = '2012-2021, Sopel 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
@@ -115,22 +115,28 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'alabaster'
+html_theme = 'furo'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 html_theme_options = {
-    'logo': 'sopel.png',
-    'logo_name': True,
-    'logo_text_align': 'center',
-    'description': 'A Python IRC bot framework.',
-    'donate_url': 'https://opencollective.com/sopel',
-    'extra_nav_links': {
-        'Back to main site': 'https://sopel.chat/',
+    'navigation_with_keys': True,
+    'light_logo': 'sopel-black.png',
+    'dark_logo': 'sopel-white.png',
+    'light_css_variables': {
+        'sidebar-tree-space-above': '1em',
     }
 }
 
+# Extra CSS files to include, relative to html_static_path.
+html_css_files = [
+    'custom.css',
+]
+
+# Extra JavaScript files to include, relative to html_static_path.
+#html_js_files = []
+
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = []
 
@@ -216,8 +222,8 @@
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'sopel.tex', u'Sopel IRC Bot Documentation',
-   u'Sopel contributors', 'manual'),
+  ('index', 'sopel.tex', 'Sopel IRC Bot Documentation',
+   'Sopel contributors', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -255,12 +261,12 @@
 # 7: Overview, conventions, and miscellaneous
 # 8: System management commands
 man_pages = [
-    ('cli', 'sopel', u'Sopel IRC Bot Command Line',
-     [u'Sopel contributors'], 1),
-    ('package', 'sopel', u'Sopel IRC Bot Documentation',
-     [u'Sopel contributors'], 3),
-    ('configuration', 'sopel', u'Sopel IRC Bot Configuration',
-     [u'Sopel contributors'], 5),
+    ('cli', 'sopel', 'Sopel IRC Bot Command Line',
+     ['Sopel contributors'], 1),
+    ('package', 'sopel', 'Sopel IRC Bot Documentation',
+     ['Sopel contributors'], 3),
+    ('configuration', 'sopel', 'Sopel IRC Bot Configuration',
+     ['Sopel contributors'], 5),
 ]
 
 # If true, show URL addresses after external links.
@@ -273,8 +279,8 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  ('index', 'sopel', u'Sopel IRC Bot Documentation',
-   u'Sopel contributors', 'SopelIRCBot', 'Simple, extendible IRC bot.',
+  ('index', 'sopel', 'Sopel IRC Bot Documentation',
+   'Sopel contributors', 'SopelIRCBot', 'Simple, extendible IRC bot.',
    'Miscellaneous'),
 ]
 

diff --git a/docs/source/config.rst b/docs/source/config.rst
@@ -2,9 +2,6 @@
 Configuration functionality
 ===========================
 
-.. contents::
-   :local:
-
 
 sopel.config
 ============

diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst
@@ -32,10 +32,6 @@ This file can be generated with ``sopel configure``.
 
     The :doc:`cli` chapter for ``sopel configure`` subcommand.
 
-.. contents::
-    :local:
-    :depth: 2
-
 
 INI file structure
 ==================

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -27,3 +27,16 @@ Documentation
     plugin
     package
     tests
+
+.. toctree::
+    :caption: Donate
+    :hidden:
+
+    GitHub Sponsors <https://github.com/sponsors/sopel-irc>
+    Open Collective <https://opencollective.com/sopel>
+
+.. toctree::
+    :caption: Escape
+    :hidden:
+
+    Back to main site <https://sopel.chat/>
diff --git a/docs/source/irc.rst b/docs/source/irc.rst
@@ -6,11 +6,6 @@ IRC Backends
     :no-members:
 
 
-.. contents::
-    :local:
-    :depth: 2
-
-
 Bot Interface
 =============
 

diff --git a/docs/source/plugin/anatomy.rst b/docs/source/plugin/anatomy.rst
@@ -8,10 +8,6 @@ A Sopel plugin consists of a Python module containing one or more
 ``callable``\s. It may optionally also contain ``configure``, ``setup``, and
 ``shutdown`` hooks.
 
-.. contents::
-   :local:
-   :depth: 2
-
 
 .. _plugin-anatomy-rules:
 

diff --git a/docs/source/plugin/bot.rst b/docs/source/plugin/bot.rst
@@ -6,10 +6,6 @@ Once a :term:`Rule` has been triggered, it's time to do whatever the plugin is
 supposed to do. Thanks to the ``bot`` parameter, you can make the bot talk:
 say something in a channel, reply to someone, send a notice, or join a channel.
 
-.. contents::
-   :local:
-   :depth: 2
-
 
 Make it talk
 ============

diff --git a/docs/source/plugin/internals.rst b/docs/source/plugin/internals.rst
@@ -8,9 +8,6 @@ Internal machinery
    subject to rapid changes between versions. They are documented here for
    completeness, and for the aid of Sopel’s core development.
 
-.. contents::
-   :local:
-
 
 sopel.loader
 ============

diff --git a/docs/source/plugin/what.rst b/docs/source/plugin/what.rst
@@ -9,10 +9,6 @@ cover what is a plugin, what you can do with them, and some vocabulary.
 You may want to skip ahead to :doc:`anatomy` if you already know what a plugin
 is and what types of plugin there are.
 
-.. contents::
-    :local:
-    :depth: 2
-
 Plugin Types
 ============
 

diff --git a/docs/source/tests.rst b/docs/source/tests.rst
@@ -2,9 +2,6 @@
 Testing tools
 =============
 
-.. contents::
-    :local:
-    :depth: 2
 
 Common tools
 ============
@@ -18,12 +15,14 @@ Fixtures with py.test
 .. automodule:: sopel.tests.pytest_plugin
    :members:
 
+
 Factories
 =========
 
 .. automodule:: sopel.tests.factories
    :members:
 
+
 Mocks
 =====
 

diff --git a/sopel/cli/config.py b/sopel/cli/config.py
@@ -57,8 +57,14 @@ def build_parser():
         help="Get a configuration option's value",
         description="Get a configuration option's value",
     )
-    get_parser.add_argument('section')
-    get_parser.add_argument('option')
+    get_parser.add_argument(
+        'section',
+        help='The name of the section to look in',
+    )
+    get_parser.add_argument(
+        'option',
+        help='The name of the option to retrieve',
+    )
     utils.add_common_arguments(get_parser)
 
     return parser

diff --git a/sopel/cli/utils.py b/sopel/cli/utils.py
@@ -248,7 +248,7 @@ def add_common_arguments(parser):
     :param parser: Argument parser (or subparser)
     :type parser: argparse.ArgumentParser
 
-    This functions adds the common arguments for Sopel's command line tools.
+    This function adds the common arguments for Sopel's command line tools.
     It adds the following arguments:
 
     * ``-c``/``--config``: the name of the Sopel config, or its absolute path

diff --git a/sopel/config/__init__.py b/sopel/config/__init__.py
@@ -218,15 +218,15 @@ def add_section(self, name):
 
             The section's ``name`` SHOULD follow *snake_case* naming rules:
 
-              * use only lowercase letters, digits, and underscore (``_``)
-              * SHOULD NOT start with a digit
+            * use only lowercase letters, digits, and underscore (``_``)
+            * SHOULD NOT start with a digit
 
             Deviations from *snake_case* can break the following operations:
 
-              * :ref:`accessing the section <sopel.config>` from Python code using
-                the :class:`~.Config` object's attributes
-              * :ref:`overriding the section's values <Overriding individual
-                settings>` using environment variables
+            * :ref:`accessing the section <sopel.config>` from Python code
+              using the :class:`~.Config` object's attributes
+            * :ref:`overriding the section's values <Overriding individual
+              settings>` using environment variables
 
         """
         try:
@@ -255,15 +255,15 @@ def define_section(self, name, cls_, validate=True):
 
             The section's ``name`` SHOULD follow *snake_case* naming rules:
 
-              * use only lowercase letters, digits, and underscore (``_``)
-              * SHOULD NOT start with a digit
+            * use only lowercase letters, digits, and underscore (``_``)
+            * SHOULD NOT start with a digit
 
             Deviations from *snake_case* can break the following operations:
 
-              * :ref:`accessing the section <sopel.config>` from Python code using
-                the :class:`~.Config` object's attributes
-              * :ref:`overriding the section's values <Overriding individual
-                settings>` using environment variables
+            * :ref:`accessing the section <sopel.config>` from Python code
+              using the :class:`~.Config` object's attributes
+            * :ref:`overriding the section's values <Overriding individual
+              settings>` using environment variables
 
         """
         if not issubclass(cls_, types.StaticSection):

diff --git a/sopel/config/types.py b/sopel/config/types.py
@@ -135,15 +135,15 @@ class BaseValidated(object):
 
         Setting names SHOULD follow *snake_case* naming rules:
 
-          * use only lowercase letters, digits, and underscore (``_``)
-          * SHOULD NOT start with a digit
+        * use only lowercase letters, digits, and underscore (``_``)
+        * SHOULD NOT start with a digit
 
         Deviations from *snake_case* can break the following operations:
 
-          * :ref:`accessing the setting <sopel.config>` from Python code using
-            the :class:`~.Config` object's attributes
-          * :ref:`overriding the setting's value <Overriding individual
-            settings>` using environment variables
+        * :ref:`accessing the setting <sopel.config>` from Python code using
+          the :class:`~.Config` object's attributes
+        * :ref:`overriding the setting's value <Overriding individual
+          settings>` using environment variables
 
     """
     def __init__(self, name, default=None, is_secret=False):

diff --git a/sopel/tools/web.py b/sopel/tools/web.py
@@ -193,8 +193,8 @@ def trim_url(url):
     This function removes trailing punctuation that looks like it was not
     intended to be part of the URL:
 
-        * trailing sentence- or clause-ending marks like ``.``, ``;``, etc.
-        * unmatched trailing brackets/braces like ``}``, ``)``, etc.
+    * trailing sentence- or clause-ending marks like ``.``, ``;``, etc.
+    * unmatched trailing brackets/braces like ``}``, ``)``, etc.
 
     It is intended for use with the output of :py:func:`~.search_urls`, which
     may include trailing punctuation when used on input from chat.