Some docs on stylesheets and update linting fix to KO hidden pattern (#585)

This adds some more documentation sourced from our theme styles,
including the pattern we've been using to replace the Knockout
``visible`` binding with a pattern that doesn't need inline styles.


https://read-the-docs-docs-landing--585.com.readthedocs.build/projects/ext-theme/en/585/api/stylesheets.html

Author: agjohnson

docs/api/stylesheets.rst

@@ -0,0 +1,33 @@
+Stylesheets
+===========
+
+This repository uses our base FUI/SUI theme, which is shared with our website.
+
+https://github.com/readthedocs/sui-common-theme/
+
+In this repository, there are some additional styles and elements that are
+specific to our application or that don't need to be defined at our common
+theme. Many of the styles are small bug fixes that don't require additional
+documentation, but there are some styles and new elements that are only found
+and used in this repository.
+
+Utilities
+---------
+
+.. autoanysrc:: hidden
+    :src: ../src/sui/themes/rtd-application/globals/site.overrides
+    :analyzer: css
+
+Images
+------
+
+.. autoanysrc:: images
+    :src: ../src/sui/themes/rtd-application/elements/image.overrides
+    :analyzer: css
+
+Tables
+------
+
+.. autoanysrc:: tables
+    :src: ../src/sui/themes/rtd-application/collections/table.overrides
+    :analyzer: css

docs/conf.py

@@ -6,14 +6,15 @@
 import docext  # noqa
 
 project = "readthedocsext-theme"
-copyright = "2022, Read the Docs, Inc"
+copyright = "2025, Read the Docs, Inc"
 author = "Read the Docs, Inc"
 
 release = "1.0rc1"
 version = release
 
 extensions = [
     "docext",
+    "sphinx.ext.autodoc",
     "sphinxcontrib.autoanysrc",
     "sphinx_js",
 ]
@@ -25,6 +26,7 @@
 
 autoanysrc_analyzers = {
     "html": "docext.DjangoTemplateAnalyzer",
+    "css": "docext.CSSAnalyzer",
 }
 
 js_source_path = "../src/js"

docs/docext.py

@@ -2,6 +2,7 @@
 readthedocsext-theme doc extensions
 """
 
+import re
 import os
 import subprocess
 from pathlib import Path
@@ -12,14 +13,7 @@
 logger = logging.getLogger(__name__)
 
 
-class DjangoTemplateAnalyzer(analyzers.BaseCommentAnalyzer):
-
-    """There are a few errors with this docstring
-    but black will not reformat any of this"""
-
-    comment_starts_with = '{% comment "rst" %}'
-    comment_ends_with = "{% endcomment %}"
-
+class CommonAnalyzer(analyzers.BaseCommentAnalyzer):
     def process(self, content):
         first_indent = None
 
@@ -40,7 +34,26 @@ def process(self, content):
                     f"Try indenting the block inner text once."
                 )
 
-            yield (line[first_indent:], lineno)
+            line_content = line[first_indent:]
+
+            # Conditionally left strip comment lines out
+            if hasattr(self, "strip_comment"):
+                line_content = self.strip_comment(line_content)
+
+            yield (line_content, lineno)
+
+
+class DjangoTemplateAnalyzer(CommonAnalyzer):
+    comment_starts_with = '{% comment "rst" %}'
+    comment_ends_with = "{% endcomment %}"
+
+
+class CSSAnalyzer(CommonAnalyzer):
+    comment_starts_with = "/*"
+    comment_ends_with = "*/"
+
+    def strip_comment(self, line):
+        return re.sub(r"^\s?\*\s?", "", line)
 
 
 def build_init(app):

docs/index.rst

@@ -18,6 +18,7 @@ Read the Docs -- Application theme
 
    api/templates
    api/javascript
+   api/stylesheets
 
 .. include:: ../README.rst
    :start-line: 3

readthedocsext/theme/templates/includes/header.html

@@ -50,7 +50,7 @@
         <div class="five wide mobile only right aligned column">
           <div class="ui wide dropdown"
                data-bind="semanticui: {dropdown: {action: 'select'}}">
-            {# Ignore "avoid inline styles" rule #}
+            {# Ignore "avoid inline styles" rule. Don't use this hack, this should eventually be a CSS rule instead. #}
             {# djlint:off H021 #}
             <i class="fad fa-bars large icon" style="--fa-secondary-opacity: 0.8;"></i>
             {# djlint:on #}

readthedocsext/theme/templates/projects/partials/project_create_automatic.html

@@ -24,12 +24,8 @@
 {% endblock project_add_configuration %}
 
 {% block project_add_automatic_search %}
-  {# Ignore "avoid inline styles" rule #}
-  {# djlint:off H021 #}
-  <div class="ui small error message"
-       data-bind="visible: error"
-       style="display: none">
-    {# djlint:on #}
+  <div class="ui small error message ko hidden"
+       data-bind="css: {hidden: !error()}">
     {% trans "There was an error while syncing your remote repositories" %}
   </div>
 
@@ -127,12 +123,8 @@
     connected and why the repository can/cannot be used.
 
   {% endcomment %}
-  {# Ignore "avoid inline styles" rule #}
-  {# djlint:off H021 #}
-  <div class="ui fluid card"
-       data-bind="visible: is_selected, with: selected"
-       style="display: none">
-    {# djlint:on #}
+  <div class="ui fluid card ko hidden"
+       data-bind="css: {hidden: !is_selected()}, with: selected">
     <div class="content">
       <img class="ui right floated mini rounded image"
            data-bind="attr: { src: avatar_url }"

setup.cfg

@@ -29,8 +29,7 @@ install_requires =
 
 [options.extras_require]
 docs =
-    # We can't upgrade Sphinx because of sphinx-js (Sphinx<6)
-    Sphinx<6
-    sphinx_rtd_theme<3
-    sphinxcontrib-autoanysrc<1
-    sphinx-js
+    Sphinx>6
+    sphinx_rtd_theme
+    sphinxcontrib-autoanysrc>=0.2.0
+    sphinx-js>=4

src/sui/themes/rtd-application/collections/table.overrides

@@ -1,5 +1,27 @@
-// Build detail page command output table
+/*
+ * Command table variant
+ * =====================
+ *
+ * This is a special table, used solely on the build detail page to list
+ * commands and steps executed. There is some unique CSS rules here to support
+ * command highlighting and ANSI sequences.
+ *
+ * .. code:: html
+ *
+ *     <div class="ui command table">
+ *       ...
+ *     </div>
+ */
 .ui.ui.ui.command.table {
+  /*
+   * Each command is made of up two rows:
+   *
+   * - The first row has two columns, a dropdown expander icon and the
+   *   command executed.
+   * - The second row is normally hidden until collapsed open, it contains
+   *   two columns: the line number and line contents for each line of output in
+   *   STDOUT.
+   */
   tr {
     border-bottom: 0px;
     cursor: unset;
@@ -29,6 +51,16 @@
       word-wrap: anywhere;
     }
 
+    /*
+     * The STDOUT styling supports ANSI color codes through special classes
+     that should be added by the backend exectuion through Docker:
+     *
+     * .. code:: html
+     *
+     *     <span class="ansi-black-fg">...</span>
+     *
+     * .. note:: ANSI sequences are not yet supported by the build backend.
+     */
     &.stdout > code {
       // ansi_up control character classes
       span.ansi-black-fg {

src/sui/themes/rtd-application/elements/image.overrides

@@ -1,3 +1,15 @@
+/*
+ * Avatar overlapping variant
+ * ==========================
+ *
+ * Used to create stacking avatar bubbles for maintainer and team member lists.
+ *
+ * .. code:: html
+ *
+ *     <div class="ui overlapping avatar images">
+ *       <img class="ui image" src="..." />
+ *     </div>
+ */
 .ui.overlapping.avatar.images {
   margin-left: 0.25rem;
   > .ui.image,

src/sui/themes/rtd-application/globals/site.overrides

@@ -4,14 +4,32 @@
 // chaining more selectors. This rule will override most 3 and 4 selector rules
 // due to the artificially increased specificity in this rule.
 .ko.ko.ko.ko.ko {
-  // There is the Knockout ``visible`` data binding, but this injects a hard
-  // coded style="display: none;" when the binding is false. This makes default
-  // styling on initial load hard with CSS and tends to flash the element to the
-  // user, before the JS loads.
-  //
-  // Instead, something like this is preferable:
-  //
-  //     <div class="ko hidden" data-bind="css: { hidden: !is_showing() }"></div>
+  /*
+   * Knockout ``visible`` binding
+   * ============================
+   *
+   * In standard Knockout there is a ``visible`` data binding, but this
+   * injects a hard coded ``style="display: none;"`` when the binding is false.
+   * This makes default styling on initial load hard with CSS and tends to
+   * flash the element to the user, before the JS loads.
+   *
+   * In standard Knockout, this would look like:
+   *
+   * .. code:: html
+   *
+   *     <div data-bind="visible: is_showing" style="display: none;"></div>
+   *
+   * Using this ``.ko.hidden`` class and the ``css`` binding, this example would instead be:
+   *
+   * .. code:: html
+   *
+   *     <div class="ko hidden" data-bind="css: { hidden: !is_showing() }"></div>
+   *
+   * .. note::
+   *     When used as an observable name, executing the observable as a function
+   *     is not required. In the second example, due to nesting and value negation, we
+   *     have to call the observable as a function, ``is_showing()``.
+   */
   &.hidden {
     display: none;
   }