From 569465026cb1660c485d9683bd34bb2fdbbf2fd9 Mon Sep 17 00:00:00 2001 From: dgw Date: Sun, 15 Nov 2020 00:57:06 -0600 Subject: [PATCH] docs(trings): fix
s happening when they shouldn't One left in sopel.cli.config, which is better fixed by a small patch to sphinxcontrib.autoprogram if the patch is accepted. (See sphinx-contrib/autoprogram#21) --- docs/source/cli.rst | 8 ++++---- sopel/cli/config.py | 3 +++ sopel/config/__init__.py | 24 ++++++++++++------------ sopel/config/types.py | 12 ++++++------ sopel/tools/web.py | 4 ++-- 5 files changed, 27 insertions(+), 24 deletions(-) diff --git a/docs/source/cli.rst b/docs/source/cli.rst index 62536d34e0..3a473d39f9 100644 --- a/docs/source/cli.rst +++ b/docs/source/cli.rst @@ -102,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/sopel/cli/config.py b/sopel/cli/config.py index c2728c12c4..b2eeb33444 100644 --- a/sopel/cli/config.py +++ b/sopel/cli/config.py @@ -27,6 +27,9 @@ def build_parser(): list_parser = subparsers.add_parser( 'list', help="List available configurations from Sopel's config directory", + # TODO: if https://github.com/sphinx-contrib/autoprogram/pull/21 is + # accepted, we'll need to require a version of autoprogram including + # the fix. (If not... we need an alternative solution locally.) description=""" List available configurations from Sopel's config directory with the extension "{ext}". Use option ``--config-dir`` to use a diff --git a/sopel/config/__init__.py b/sopel/config/__init__.py index 4290b8a4cc..4aba1e3b16 100644 --- a/sopel/config/__init__.py +++ b/sopel/config/__init__.py @@ -198,15 +198,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 ` from Python code using - the :class:`~.Config` object's attributes - * :ref:`overriding the section's values ` using environment variables + * :ref:`accessing the section ` from Python code + using the :class:`~.Config` object's attributes + * :ref:`overriding the section's values ` using environment variables """ try: @@ -235,15 +235,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 ` from Python code using - the :class:`~.Config` object's attributes - * :ref:`overriding the section's values ` using environment variables + * :ref:`accessing the section ` from Python code + using the :class:`~.Config` object's attributes + * :ref:`overriding the section's values ` using environment variables """ if not issubclass(cls_, types.StaticSection): diff --git a/sopel/config/types.py b/sopel/config/types.py index cc09a5dfb6..f7b4bf5c5b 100644 --- a/sopel/config/types.py +++ b/sopel/config/types.py @@ -138,15 +138,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 ` from Python code using - the :class:`~.Config` object's attributes - * :ref:`overriding the setting's value ` using environment variables + * :ref:`accessing the setting ` from Python code using + the :class:`~.Config` object's attributes + * :ref:`overriding the setting's value ` using environment variables """ def __init__(self, name, default=None, is_secret=False): diff --git a/sopel/tools/web.py b/sopel/tools/web.py index 70d7b63147..8918a4a64f 100644 --- a/sopel/tools/web.py +++ b/sopel/tools/web.py @@ -215,8 +215,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.