Finish linting non-API modules

5 files changed, 85 insertions, 1 deletions

diff --git a/manage.py b/manage.py
index ca7a5142..37cca124 100755
--- a/manage.py
+++ b/manage.py
@@ -5,6 +5,8 @@ import sys
 
 # Separate definition to ease calling this in other scripts.
 def main():
+    """Entry point for Django management script."""
+
     os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'pydis_site.settings')
     try:
         from django.core.management import execute_from_command_line
diff --git a/pydis_site/apps/home/apps.py b/pydis_site/apps/home/apps.py
index 90dc7137..2a2d362a 100644
--- a/pydis_site/apps/home/apps.py
+++ b/pydis_site/apps/home/apps.py
@@ -2,4 +2,5 @@ from django.apps import AppConfig
 
 
 class HomeConfig(AppConfig):
+    """Django AppConfig for the home app."""
     name = 'home'
diff --git a/pydis_site/apps/home/models/repository_metadata.py b/pydis_site/apps/home/models/repository_metadata.py
index c975c904..f68d3985 100644
--- a/pydis_site/apps/home/models/repository_metadata.py
+++ b/pydis_site/apps/home/models/repository_metadata.py
@@ -30,4 +30,6 @@ class RepositoryMetadata(models.Model):
     )
 
     def __str__(self):
+        """Returns the repo name, for display purposes."""
+
         return self.repo_name
diff --git a/pydis_site/apps/home/templatetags/extra_filters.py b/pydis_site/apps/home/templatetags/extra_filters.py
index edffe9ac..d3e1788c 100644
--- a/pydis_site/apps/home/templatetags/extra_filters.py
+++ b/pydis_site/apps/home/templatetags/extra_filters.py
@@ -5,4 +5,18 @@ register = template.Library()
 
 @register.filter
 def starts_with(value: str, arg: str):
+    """
+    Simple filter for checking if a string value starts with another string.
+
+    Kind of surprising that Django doesn't come with this one, actually...
+
+    Usage:
+
+    ```django
+        {% if request.url | starts_with:"/wiki" %}
+          ...
+        {% endif %}
+    ```
+    """
+
     return value.startswith(arg)
diff --git a/pydis_site/apps/home/templatetags/wiki_extra.py b/pydis_site/apps/home/templatetags/wiki_extra.py
index 289b0279..ab14f7be 100644
--- a/pydis_site/apps/home/templatetags/wiki_extra.py
+++ b/pydis_site/apps/home/templatetags/wiki_extra.py
@@ -27,6 +27,13 @@ register = template.Library()
 
 
 def get_unbound_field(field: Union[BoundField, Field]) -> Field:
+    """
+    Unwraps a bound Django Forms field, returning the unbound field.
+
+    Bound fields often don't give you the same level of access to the field's underlying attributes,
+    so sometimes it helps to have access to the underlying field object.
+    """
+
     while isinstance(field, BoundField):
         field = field.field
 
@@ -34,11 +41,33 @@ def get_unbound_field(field: Union[BoundField, Field]) -> Field:
 
 
 def render(template_path: str, context: Dict[str, Any]):
-    return mark_safe(get_template(template_path).render(context))  # noqa: S703 S308
+    """
+    Renders a template at a specified path, with the provided context dictionary.
+
+    This was extracted mostly for the sake of mocking it out in the tests - but do note that
+    the resulting rendered template is wrapped with `mark_safe`, so it will not be escaped.
+    """
+
+    return mark_safe(get_template(template_path).render(context))  # noqa: S703, S308
 
 
 @register.simple_tag
 def render_field(field: Field, render_labels: bool = True):
+    """
+    Renders a form field using a custom template designed specifically for the wiki forms.
+
+    As the wiki uses custom form rendering logic, we were unable to make use of Crispy Forms for
+    it. This means that, in order to customize the form fields, we needed to be able to render
+    the fields manually. This function handles that logic.
+
+    Sometimes we don't want to render the label that goes with a field - the `render_labels`
+    argument defaults to True, but can be set to False if the label shouldn't be rendered.
+
+    The label rendering logic is left up to the template.
+
+    Usage: `{% render_field field_obj [render_labels=True/False] %}`
+    """
+
     unbound_field = get_unbound_field(field)
 
     if not isinstance(render_labels, bool):
@@ -53,6 +82,29 @@ def render_field(field: Field, render_labels: bool = True):
 
 @register.simple_tag(takes_context=True)
 def get_field_options(context: Context, field: BoundField):
+    """
+    Retrieves the field options for a multiple choice field, and stores it in the context.
+
+    This tag exists because we can't call functions within Django templates directly, and is
+    only made use of in the template for ModelChoice (and derived) fields - but would work fine
+    with anything that makes use of your standard `<select>` element widgets.
+
+    This stores the parsed options under `options` in the context, which will subsequently
+    be available in the template.
+
+    Usage:
+
+    ```django
+    {% get_field_options field_object %}
+
+    {% if options %}
+      {% for group_name, group_choices, group_index in options %}
+        ...
+      {% endfor %}
+    {% endif %}
+    ```
+    """
+
     widget = field.field.widget
 
     if field.value() is None:
@@ -66,6 +118,19 @@ def get_field_options(context: Context, field: BoundField):
 
 @register.filter
 def render_urlpath(value: Union[URLPath, str]):
+    """
+    Simple filter to render a URLPath (or string) into a template.
+
+    This is used where the wiki intends to render a path - mostly because if you just
+    `str(url_path)`, you'll actually get a path that starts with `(root)` instead of `/`.
+
+    We support strings here as well because the wiki is very inconsistent about when it
+    provides a string versus when it provides a URLPath, and it was too much work to figure out
+    and account for it in the templates.
+
+    Usage: `{{ url_path | render_urlpath }}`
+    """
+
     if isinstance(value, str):
         return value or "/"