Add docstring, uncomment code, extract nested function

pelicanconf.py

@@ -1,3 +1,5 @@
+"""Base and development configuration for Pelican"""
+
 from pathlib import Path
 
 PROJECT_DIR = Path(__file__).parent
@@ -78,8 +80,8 @@
 TAGS_SAVE_AS = False
 INDEX_SAVE_AS = False
 
-# Uncomment following line if you want document-relative URLs when developing
-# RELATIVE_URLS = True
+# Set the following to True if you want document-relative URLs when developing
+RELATIVE_URLS = False
 
 # No feeds, no blog!
 FEED_ALL_ATOM = None

plugins/__init__.py

@@ -0,0 +1 @@
+"""Custom Pelican plugins used for this project"""

plugins/libsass.py

@@ -1,5 +1,4 @@
-"""
-libsass
+"""libsass
 
 This plugin compiles sass/scss files to plain css.
 """
@@ -11,14 +10,13 @@
 
 
 def compile_sass(instance: Pelican) -> None:
-    """
-    Compile SASS/SCSS with libsass to CSS
-    """
+    """Compile SASS/SCSS with libsass to CSS"""
     paths = instance.settings.get(SETTINGS_NAME, [])
 
     for input_output_paths in paths:
         sass.compile(dirname=input_output_paths)
 
 
 def register() -> None:
+    """Register with pelican"""
     signals.finalized.connect(compile_sass)

plugins/shortcodes.py

@@ -1,12 +1,12 @@
-"""
-shortcodes.py
-=============
+"""shortcodes
+
 Copyright: AGPLv3 <Bernardas Ališauskas @ bernardas.alisauskas@pm.me>
 
 This plugin allows to define macros called shortcodes in content pages that will be expanded as jinja2 templates.
-The purpose of this plugin is to allow explicit and quick jinja2 templating in your content without compromising markdown/rst.
+The purpose of this plugin is to allow explicit and quick jinja2 templating in your content without compromising
+markdown/rst.
 
-Example:
+Example usage:
 
 In `pelicanconf.py` add:
 
@@ -25,35 +25,42 @@
 """
 import re
 
+from functools import partial
+
 from jinja2 import Template
 
 from pelican import Pelican, signals
 
 SETTINGS_NAME = 'SHORTCODES'
 
 
-def expand_shortcodes(text: str, shortcodes: dict[str, str]) -> str:
-    def replace_shortcode(group: re.Match) -> str:
-        """Replace shortcodes with evaluated templates"""
-        match = group.groups()[0]
-        code, _, args = match.partition(' ')
-        args = re.split(r'(\w+)=', args)
-        args = [a.strip('\'" ') for a in args if a]
-        kwargs = {args[i]: args[i + 1] for i in range(0, len(args), 2)}
-        try:
-            return Template(shortcodes[code]).render(**kwargs)
-        except KeyError:
-            raise KeyError(f'shortcode "{code}" not found')
+def replace_shortcode(group: re.Match, shortcodes: dict[str, str]) -> str:
+    """Replace shortcodes with evaluated templates"""
+    match = group.groups()[0]
+    code, _, args = match.partition(' ')
+    args = re.split(r'(\w+)=', args)
+    args = [a.strip('\'" ') for a in args if a]
+    kwargs = {args[i]: args[i + 1] for i in range(0, len(args), 2)}
+    try:
+        return Template(shortcodes[code]).render(**kwargs)
+    except KeyError:
+        raise KeyError(f'shortcode "{code}" not found') from None
+
 
-    return re.sub(r'\[% ([\w\W]+?) %\]', replace_shortcode, text, flags=re.MULTILINE)
+def expand_shortcodes(text: str, shortcodes: dict[str, str]) -> str:
+    """Find all shortcodes and apply the replacement templates"""
+    shortcode_replacer = partial(replace_shortcode, shortcodes=shortcodes)
+    return re.sub(r'\[% ([\w\W]+?) %\]', shortcode_replacer, text, flags=re.MULTILINE)
 
 
 def content_object_init(instance: Pelican) -> None:
+    """Apply shortcodes to content, replacing original content"""
     shortcodes = instance.settings.get(SETTINGS_NAME)
     if not shortcodes or not instance._content:
         return
     instance._content = expand_shortcodes(instance._content, shortcodes)
 
 
 def register() -> None:
+    """Register with pelican"""
     signals.content_object_init.connect(content_object_init)

plugins/thumbnails.py

@@ -1,5 +1,4 @@
-"""
-thumbnails
+"""thumbnails
 
 This plugin creates half size versions of images in specified path.
 
@@ -20,6 +19,7 @@
 
 
 def create_thumbnail(image_path: Path) -> None:
+    """Create half size (halved width and height) thumbnail"""
     extension = image_path.suffix
     image = Image.open(image_path)
     image.thumbnail((
@@ -30,9 +30,7 @@ def create_thumbnail(image_path: Path) -> None:
 
 
 def create_thumbnails(instance: Pelican) -> None:
-    """
-    Create half size versions of '@2x' images in given paths
-    """
+    """Create half size versions of '@2x' images in given paths"""
     extensions = ['.png', '.jpg', '.jpeg']
     paths = instance.settings.get(SETTINGS_NAME, [])
 
@@ -48,4 +46,5 @@ def create_thumbnails(instance: Pelican) -> None:
 
 
 def register() -> None:
+    """Register with pelican"""
     signals.finalized.connect(create_thumbnails)

publishconf.py

@@ -1,3 +1,5 @@
+"""Production configuration for Pelican"""
+
 from pelicanconf import *  # noqa: F403
 
 SITEURL = 'https://arne.delaat.net'