revamp documentation of checks on readthedocs

auto-generate the .rst files for the check implementations so that it
does not have to be manually maintained.

Lib/fontbakery/callable.py

@@ -139,9 +139,6 @@ def __init__(
         # Using markdown, perhaps?
         proposal=None,  # An URL to the original proposal for this check.
         # This is typically a github issue or pull request.
-        proponent=None,  # Name Surname (@github_username)
-        suggested_profile=None,  # A suggestion of which fontbakery profile
-        # should this check be added to once implemented.
         experimental=False,  # Experimental checks won't affect the process exit code
         severity=None,  # numeric value from 1=min to 10=max, denoting check severity
         configs=None,  # items from config[self.id] to inject into the check's namespace
@@ -151,9 +148,6 @@ def __init__(
         # Below are a few candidates for that:
         # affects=None,  # A list of tuples each indicating Browser/OS/Application
         #                # and the affected versions range.
-        # example_failures=None,  # A reference to some font or family that
-        #                         # originally failed due to the problems
-        #                         # that this check tries to detect and report.
     ):
         """This is the base class for all checks. It will usually
         not be used directly to create check instances, rather
@@ -204,9 +198,7 @@ def __init__(
         )
         self.configs = configs
         self.proposal = proposal
-        self.proponent = proponent
         self.experimental = experimental
-        self.suggested_profile = suggested_profile
         self.severity = severity
         if not self.description:
             raise TypeError("{} needs a description.".format(type(self).__name__))

Lib/fontbakery/reporters/terminal.py

@@ -266,17 +266,6 @@ def receive_result(self, checkresult: CheckResult):
                     line.set_length(self._console.width)
                 self._console.print(lines)
 
-            if check.suggested_profile:
-                self._console.print(
-                    "    [rationale-title]Suggested Profile:[/] "
-                    + f" {check.suggested_profile}",
-                )
-
-            if check.proponent:
-                self._console.print(
-                    "    [rationale-title]Proponent:[/]" + f" {check.proponent}\n",
-                )
-
             if check.proposal:
                 moreinfo = check.proposal
                 if not isinstance(moreinfo, list):

Lib/fontbakery/sphinx_extensions/profile.py

@@ -103,7 +103,7 @@ def add_content(
         check = self.object
         self.add_line("*" + check.description + "*", source_name)
         self.add_line("", source_name)
-        for section in ["rationale", "proposal", "proponent", "conditions", "severity"]:
+        for section in ["rationale", "proposal", "conditions", "severity"]:
             if getattr(check, section):
                 getattr(self, f"render_{section}")()
         self.add_line("", source_name)
@@ -132,12 +132,6 @@ def render_proposal(self) -> None:
         else:
             self.add_line(f"* **Original proposal**: {check.proposal}", source_name)
 
-    def render_proponent(self):
-        check = self.object
-        source_name = self.get_sourcename()
-        self.add_line("", source_name)
-        self.add_line(f"**Proponent**: {check.proponent}", source_name)
-
     def render_conditions(self):
         check = self.object
         source_name = self.get_sourcename()

docs/Makefile

@@ -12,9 +12,12 @@ BUILDDIR      = _build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+generate:
+	python3 generate_check_listing.py
+
+.PHONY: generate help Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
+%: Makefile generate
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/generate_check_listing.py

@@ -0,0 +1,66 @@
+from fontbakery.profiles.opentype import PROFILE as opentype_profile
+from fontbakery.profiles.universal import PROFILE as universal_profile
+from fontbakery.profiles.adobefonts import PROFILE as adobefonts_profile
+from fontbakery.profiles.fontbureau import PROFILE as fontbureau_profile
+from fontbakery.profiles.fontval import PROFILE as fontval_profile
+from fontbakery.profiles.fontwerk import PROFILE as fontwerk_profile
+from fontbakery.profiles.googlefonts import PROFILE as googlefonts_profile
+from fontbakery.profiles.iso15008 import PROFILE as iso15008_profile
+from fontbakery.profiles.microsoft import PROFILE as microsoft_profile
+from fontbakery.profiles.notofonts import PROFILE as notofonts_profile
+from fontbakery.profiles.typenetwork import PROFILE as typenetwork_profile
+
+VENDOR_SPECIFIC_NAMES = [
+    "adobefonts",
+    "fontbureau",
+    "fontval",
+    "fontwerk",
+    "googlefonts",
+    "microsoft",
+    "notofonts",
+    "typenetwork",
+]
+
+seen = set()
+
+for filename, profile, msg in [
+    ("opentype", opentype_profile, "Conformance with the OpenType spec"),
+    (
+        "iso15008",
+        iso15008_profile,
+        "Conformance with the ISO15008 (car safety) standard",
+    ),
+    ("universal", universal_profile, "Universal: Generally agreed upon checks"),
+    ("adobefonts", adobefonts_profile, "Vendor-specific: Adobe Fonts"),
+    ("fontbureau", fontbureau_profile, "Vendor-specific: Fontbureau"),
+    ("fontwerk", fontwerk_profile, "Vendor-specific: Fontwerk"),
+    ("googlefonts", googlefonts_profile, "Vendor-specific: Google Fonts"),
+    ("microsoft", microsoft_profile, "Vendor-specific: Microsoft"),
+    ("notofonts", notofonts_profile, "Vendor-specific: Noto fonts"),
+    ("typenetwork", typenetwork_profile, "Vendor-specific: Type Network"),
+    ("fontval", fontval_profile, "3rd party tool: MS Font Validator wrapper"),
+]:
+    output = open(f"source/fontbakery/checks/{filename}.rst", "w")
+    output.write(f"{'#'*len(msg)}\n{msg}\n{'#'*len(msg)}\n\n")
+
+    for section, checks in profile["sections"].items():
+        for checkid in checks:
+            # we don´t want to document any given check more than once:
+            if checkid in seen:
+                continue
+            else:
+                seen.add(checkid)
+
+            checkid = checkid.split("/")
+            if checkid[0] in VENDOR_SPECIFIC_NAMES:
+                vendor_profile = checkid.pop(0)
+                if vendor_profile != filename:
+                    # Sometimes other vendor checks are referenced in a vendor profile.
+                    # But here we'll just list our own vendor-specific checks.
+                    continue
+                else:
+                    f = f"vendorspecific.{vendor_profile}.{'.'.join(checkid)}"
+            else:
+                f = ".".join(checkid)
+            output.write(f".. automodule:: fontbakery.checks.{f}\n    :members:\n")
+    output.close()

docs/source/fontbakery/checks/index.rst

@@ -5,16 +5,14 @@ Check definitions
 .. toctree::
    :maxdepth: 1
 
+   opentype
+   iso15008
+   universal
    adobefonts
    fontbureau
-   fontval
    fontwerk
    googlefonts
-   iso15008
    microsoft
    notofonts
-   opentype
-   outline
-   shaping
    typenetwork
-   ufo
+   fontval