From da825ff0746641429cc4827ffd4a25ac3b1388b3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Felipe=20Corr=C3=AAa=20da=20Silva=20Sanches?= Date: Thu, 26 Dec 2024 02:42:54 -0300 Subject: [PATCH] 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 | 8 - .../{shape_language.py => shape_languages.py} | 0 Lib/fontbakery/reporters/terminal.py | 11 -- Lib/fontbakery/sphinx_extensions/profile.py | 8 +- docs/Makefile | 7 +- docs/generate_check_listing.py | 66 ++++++++ docs/source/fontbakery/checks/adobefonts.rst | 6 - docs/source/fontbakery/checks/fontbureau.rst | 6 - docs/source/fontbakery/checks/fontval.rst | 6 - docs/source/fontbakery/checks/fontwerk.rst | 6 - docs/source/fontbakery/checks/googlefonts.rst | 153 ------------------ docs/source/fontbakery/checks/index.rst | 10 +- docs/source/fontbakery/checks/iso15008.rst | 6 - docs/source/fontbakery/checks/microsoft.rst | 6 - docs/source/fontbakery/checks/notofonts.rst | 6 - docs/source/fontbakery/checks/opentype.rst | 93 ----------- docs/source/fontbakery/checks/outline.rst | 6 - docs/source/fontbakery/checks/shaping.rst | 6 - docs/source/fontbakery/checks/typenetwork.rst | 6 - docs/source/fontbakery/checks/ufo.rst | 6 - .../fontbakery/commands/check_profile.rst | 7 - docs/source/fontbakery/commands/index.rst | 8 - docs/source/fontbakery/index.rst | 1 - docs/source/fontbakery/profiles/fontval.rst | 6 +- docs/source/fontbakery/profiles/index.rst | 1 + docs/source/fontbakery/profiles/microsoft.rst | 5 + docs/source/fontbakery/profiles/shaping.rst | 5 - 27 files changed, 85 insertions(+), 370 deletions(-) rename Lib/fontbakery/checks/vendorspecific/googlefonts/glyphsets/{shape_language.py => shape_languages.py} (100%) create mode 100644 docs/generate_check_listing.py delete mode 100644 docs/source/fontbakery/checks/adobefonts.rst delete mode 100644 docs/source/fontbakery/checks/fontbureau.rst delete mode 100644 docs/source/fontbakery/checks/fontval.rst delete mode 100644 docs/source/fontbakery/checks/fontwerk.rst delete mode 100644 docs/source/fontbakery/checks/googlefonts.rst delete mode 100644 docs/source/fontbakery/checks/iso15008.rst delete mode 100644 docs/source/fontbakery/checks/microsoft.rst delete mode 100644 docs/source/fontbakery/checks/notofonts.rst delete mode 100644 docs/source/fontbakery/checks/opentype.rst delete mode 100644 docs/source/fontbakery/checks/outline.rst delete mode 100644 docs/source/fontbakery/checks/shaping.rst delete mode 100644 docs/source/fontbakery/checks/typenetwork.rst delete mode 100644 docs/source/fontbakery/checks/ufo.rst delete mode 100644 docs/source/fontbakery/commands/check_profile.rst delete mode 100644 docs/source/fontbakery/commands/index.rst create mode 100644 docs/source/fontbakery/profiles/microsoft.rst delete mode 100644 docs/source/fontbakery/profiles/shaping.rst diff --git a/Lib/fontbakery/callable.py b/Lib/fontbakery/callable.py index 0804853449..dcba4ed473 100644 --- a/Lib/fontbakery/callable.py +++ b/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__)) diff --git a/Lib/fontbakery/checks/vendorspecific/googlefonts/glyphsets/shape_language.py b/Lib/fontbakery/checks/vendorspecific/googlefonts/glyphsets/shape_languages.py similarity index 100% rename from Lib/fontbakery/checks/vendorspecific/googlefonts/glyphsets/shape_language.py rename to Lib/fontbakery/checks/vendorspecific/googlefonts/glyphsets/shape_languages.py diff --git a/Lib/fontbakery/reporters/terminal.py b/Lib/fontbakery/reporters/terminal.py index 3aff98557c..db8e85af6e 100644 --- a/Lib/fontbakery/reporters/terminal.py +++ b/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): diff --git a/Lib/fontbakery/sphinx_extensions/profile.py b/Lib/fontbakery/sphinx_extensions/profile.py index cc4282c013..9e1c8d17b3 100644 --- a/Lib/fontbakery/sphinx_extensions/profile.py +++ b/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() diff --git a/docs/Makefile b/docs/Makefile index c9c67ce470..b522027690 100644 --- a/docs/Makefile +++ b/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) diff --git a/docs/generate_check_listing.py b/docs/generate_check_listing.py new file mode 100644 index 0000000000..e1962c9819 --- /dev/null +++ b/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() diff --git a/docs/source/fontbakery/checks/adobefonts.rst b/docs/source/fontbakery/checks/adobefonts.rst deleted file mode 100644 index d1aa5fa302..0000000000 --- a/docs/source/fontbakery/checks/adobefonts.rst +++ /dev/null @@ -1,6 +0,0 @@ -######################################### -Checks to support the Adobe Fonts profile -######################################### - -.. automodule:: fontbakery.checks.vendorspecific.adobefonts - :members: diff --git a/docs/source/fontbakery/checks/fontbureau.rst b/docs/source/fontbakery/checks/fontbureau.rst deleted file mode 100644 index 8cefe42b9d..0000000000 --- a/docs/source/fontbakery/checks/fontbureau.rst +++ /dev/null @@ -1,6 +0,0 @@ -######################################## -Checks to support the Fontbureau profile -######################################## - -.. automodule:: fontbakery.checks.vendorspecific.fontbureau - :members: diff --git a/docs/source/fontbakery/checks/fontval.rst b/docs/source/fontbakery/checks/fontval.rst deleted file mode 100644 index 804a164c75..0000000000 --- a/docs/source/fontbakery/checks/fontval.rst +++ /dev/null @@ -1,6 +0,0 @@ -############################################ -Checks to support the Font Validator profile -############################################ - -.. automodule:: fontbakery.checks.fontval - :members: diff --git a/docs/source/fontbakery/checks/fontwerk.rst b/docs/source/fontbakery/checks/fontwerk.rst deleted file mode 100644 index 39138f609f..0000000000 --- a/docs/source/fontbakery/checks/fontwerk.rst +++ /dev/null @@ -1,6 +0,0 @@ -###################################### -Checks to support the Fontwerk profile -###################################### - -.. automodule:: fontbakery.checks.vendorspecific.fontwerk - :members: diff --git a/docs/source/fontbakery/checks/googlefonts.rst b/docs/source/fontbakery/checks/googlefonts.rst deleted file mode 100644 index cd3d0b479a..0000000000 --- a/docs/source/fontbakery/checks/googlefonts.rst +++ /dev/null @@ -1,153 +0,0 @@ -########################################## -Checks to support the Google Fonts profile -########################################## - -Base checks -*********** - -.. automodule:: fontbakery.checks.vendorspecific.googlefonts - :members: - -Axis registry checks -******************** - -.. automodule:: fontbakery.checks.vendorspecific.googlefonts.axisregistry - :members: - -Color font checks -***************** - -.. automodule:: fontbakery.checks.vendorspecific.googlefonts.color - :members: - -Copyright checks -**************** - -.. automodule:: fontbakery.checks.vendorspecific.googlefonts.copyright - :members: - -Description checks -****************** - -.. automodule:: fontbakery.checks.vendorspecific.googlefonts.description - :members: - -Family checks -************* - -.. automodule:: fontbakery.checks.vendorspecific.googlefonts.family - :members: - -GDEF table checks -***************** - -.. automodule:: fontbakery.checks.vendorspecific.googlefonts.gdef - :members: - -glyf table checks -***************** - -.. automodule:: fontbakery.checks.vendorspecific.googlefonts.glyf - :members: - -Glyphset checks -*************** - -.. automodule:: fontbakery.checks.vendorspecific.googlefonts.glyphset - :members: - -GPOS table checks -***************** - -.. automodule:: fontbakery.checks.vendorspecific.googlefonts.gpos - :members: - -GSUB table checks -***************** - -.. automodule:: fontbakery.checks.vendorspecific.googlefonts.gsub - :members: - -head table checks -***************** - -.. automodule:: fontbakery.checks.vendorspecific.googlefonts.head - :members: - -Hinting checks -************** - -.. automodule:: fontbakery.checks.vendorspecific.googlefonts.hinting - :members: - -Regressions checks against fonts hosted on fonts.google.com -*********************************************************** - -.. automodule:: fontbakery.checks.vendorspecific.googlefonts.hosted - :members: - -License checks -************** - -.. automodule:: fontbakery.checks.vendorspecific.googlefonts.license - :members: - -meta table checks -***************** - -.. automodule:: fontbakery.checks.vendorspecific.googlefonts.meta - :members: - -Metadata checks -*************** - -.. automodule:: fontbakery.checks.vendorspecific.googlefonts.metadata - :members: - -name table checks -***************** - -.. automodule:: fontbakery.checks.vendorspecific.googlefonts.name - :members: - -OS/2 table checks -***************** - -.. automodule:: fontbakery.checks.vendorspecific.googlefonts.os2 - :members: - -Repository checks -***************** - -.. automodule:: fontbakery.checks.vendorspecific.googlefonts.repo - :members: - -STAT table checks -***************** - -.. automodule:: fontbakery.checks.vendorspecific.googlefonts.stat - :members: - -Subsetting checks -***************** - -.. automodule:: fontbakery.checks.vendorspecific.googlefonts.subsets - :members: - -Font table checks -***************** - -.. automodule:: fontbakery.checks.vendorspecific.googlefonts.tables - :members: - -Variable font checks -******************** - -.. automodule:: fontbakery.checks.vendorspecific.googlefonts.varfont - :members: - -Vertical metrics checks -*********************** - -.. automodule:: fontbakery.checks.vendorspecific.googlefonts.vmetrics - :members: diff --git a/docs/source/fontbakery/checks/index.rst b/docs/source/fontbakery/checks/index.rst index b1a62c7501..35be35c29e 100644 --- a/docs/source/fontbakery/checks/index.rst +++ b/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 diff --git a/docs/source/fontbakery/checks/iso15008.rst b/docs/source/fontbakery/checks/iso15008.rst deleted file mode 100644 index 8c90c82d70..0000000000 --- a/docs/source/fontbakery/checks/iso15008.rst +++ /dev/null @@ -1,6 +0,0 @@ -###################################### -Checks to support the ISO15008 profile -###################################### - -.. automodule:: fontbakery.checks.iso15008 - :members: diff --git a/docs/source/fontbakery/checks/microsoft.rst b/docs/source/fontbakery/checks/microsoft.rst deleted file mode 100644 index 92a709f161..0000000000 --- a/docs/source/fontbakery/checks/microsoft.rst +++ /dev/null @@ -1,6 +0,0 @@ -####################################### -Checks to support the Microsoft profile -####################################### - -.. automodule:: fontbakery.checks.vendorspecific.microsoft - :members: diff --git a/docs/source/fontbakery/checks/notofonts.rst b/docs/source/fontbakery/checks/notofonts.rst deleted file mode 100644 index 9199f12381..0000000000 --- a/docs/source/fontbakery/checks/notofonts.rst +++ /dev/null @@ -1,6 +0,0 @@ -######################################## -Checks to support the Noto fonts profile -######################################## - -.. automodule:: fontbakery.checks.vendorspecific.notofonts - :members: diff --git a/docs/source/fontbakery/checks/opentype.rst b/docs/source/fontbakery/checks/opentype.rst deleted file mode 100644 index aa48b60898..0000000000 --- a/docs/source/fontbakery/checks/opentype.rst +++ /dev/null @@ -1,93 +0,0 @@ -###################################################### -Checks for conformance with the OpenType specification -###################################################### - -Base checks -*********** - -.. automodule:: fontbakery.checks.opentype - :members: - -CFF table checks -**************** - -.. automodule:: fontbakery.checks.opentype.cff - :members: - -fvar table checks -***************** - -.. automodule:: fontbakery.checks.opentype.fvar - :members: - -GDEF table checks -***************** - -.. automodule:: fontbakery.checks.opentype.gdef - :members: - -glyf table checks -***************** - -.. automodule:: fontbakery.checks.opentype.glyf - :members: - -GPOS table checks -***************** - -.. automodule:: fontbakery.checks.opentype.gpos - :members: - -head table checks -***************** - -.. automodule:: fontbakery.checks.opentype.head - :members: - -hhea table checks -***************** - -.. automodule:: fontbakery.checks.opentype.hhea - :members: - -kern table checks -***************** - -.. automodule:: fontbakery.checks.opentype.kern - :members: - -Layout-related checks -********************* - -.. automodule:: fontbakery.checks.opentype.layout - :members: - -loca table checks -***************** - -.. automodule:: fontbakery.checks.opentype.loca - :members: - -name table checks -***************** - -.. automodule:: fontbakery.checks.opentype.name - :members: - -OS/2 table checks -***************** - -.. automodule:: fontbakery.checks.opentype.os2 - :members: - -post table checks -***************** - -.. automodule:: fontbakery.checks.opentype.post - :members: - -STAT table checks -***************** - -.. automodule:: fontbakery.checks.opentype.stat - :members: diff --git a/docs/source/fontbakery/checks/outline.rst b/docs/source/fontbakery/checks/outline.rst deleted file mode 100644 index 668653e90f..0000000000 --- a/docs/source/fontbakery/checks/outline.rst +++ /dev/null @@ -1,6 +0,0 @@ -################################ -Checks related to glyph outlines -################################ - -.. automodule:: fontbakery.checks.outline - :members: diff --git a/docs/source/fontbakery/checks/shaping.rst b/docs/source/fontbakery/checks/shaping.rst deleted file mode 100644 index 816a596077..0000000000 --- a/docs/source/fontbakery/checks/shaping.rst +++ /dev/null @@ -1,6 +0,0 @@ -############################################## -Checks for shaping regression tests and errors -############################################## - -.. automodule:: fontbakery.checks.shaping - :members: diff --git a/docs/source/fontbakery/checks/typenetwork.rst b/docs/source/fontbakery/checks/typenetwork.rst deleted file mode 100644 index 513ac411ea..0000000000 --- a/docs/source/fontbakery/checks/typenetwork.rst +++ /dev/null @@ -1,6 +0,0 @@ -########################################## -Checks to support the Type Network profile -########################################## - -.. automodule:: fontbakery.checks.vendorspecific.typenetwork - :members: diff --git a/docs/source/fontbakery/checks/ufo.rst b/docs/source/fontbakery/checks/ufo.rst deleted file mode 100644 index d14c672bab..0000000000 --- a/docs/source/fontbakery/checks/ufo.rst +++ /dev/null @@ -1,6 +0,0 @@ -########################## -Checks on UFO source files -########################## - -.. automodule:: fontbakery.checks.ufo - :members: diff --git a/docs/source/fontbakery/commands/check_profile.rst b/docs/source/fontbakery/commands/check_profile.rst deleted file mode 100644 index 5b302ead53..0000000000 --- a/docs/source/fontbakery/commands/check_profile.rst +++ /dev/null @@ -1,7 +0,0 @@ -############# -check_profile -############# - -.. automodule:: fontbakery.commands.check_profile - :members: - :undoc-members: diff --git a/docs/source/fontbakery/commands/index.rst b/docs/source/fontbakery/commands/index.rst deleted file mode 100644 index 3d5f3d4f11..0000000000 --- a/docs/source/fontbakery/commands/index.rst +++ /dev/null @@ -1,8 +0,0 @@ -######## -commands -######## - -.. toctree:: - :maxdepth: 1 - - check_profile diff --git a/docs/source/fontbakery/index.rst b/docs/source/fontbakery/index.rst index 9b83535585..5c860334f3 100644 --- a/docs/source/fontbakery/index.rst +++ b/docs/source/fontbakery/index.rst @@ -11,7 +11,6 @@ A single-page index of all source modules is available in :ref:`modindex`. checks/index checkrunner cli - commands/index constants fonts_public_pb2 fonts_profile diff --git a/docs/source/fontbakery/profiles/fontval.rst b/docs/source/fontbakery/profiles/fontval.rst index 2597fdc0df..1f01c9a157 100644 --- a/docs/source/fontbakery/profiles/fontval.rst +++ b/docs/source/fontbakery/profiles/fontval.rst @@ -1,5 +1,5 @@ -######################## -Microsoft Font Validator -######################## +################# +MS Font Validator +################# .. autoprofile:: fontbakery.profiles.fontval diff --git a/docs/source/fontbakery/profiles/index.rst b/docs/source/fontbakery/profiles/index.rst index 46429e25b4..f450d4bf0e 100644 --- a/docs/source/fontbakery/profiles/index.rst +++ b/docs/source/fontbakery/profiles/index.rst @@ -13,4 +13,5 @@ profiles fontbureau fontwerk fontval + microsoft iso15008 diff --git a/docs/source/fontbakery/profiles/microsoft.rst b/docs/source/fontbakery/profiles/microsoft.rst new file mode 100644 index 0000000000..c2fc5617b6 --- /dev/null +++ b/docs/source/fontbakery/profiles/microsoft.rst @@ -0,0 +1,5 @@ +######### +Microsoft +######### + +.. autoprofile:: fontbakery.profiles.microsoft diff --git a/docs/source/fontbakery/profiles/shaping.rst b/docs/source/fontbakery/profiles/shaping.rst deleted file mode 100644 index ef67e63c4c..0000000000 --- a/docs/source/fontbakery/profiles/shaping.rst +++ /dev/null @@ -1,5 +0,0 @@ -####### -Shaping -####### - -.. autoprofile:: fontbakery.profiles.shaping