DOP-2649: Permit specifying an rstspec.toml file

Author: i80and

snooty/main.py

@@ -1,7 +1,7 @@
 """Snooty.
 
 Usage:
-  snooty build [--no-caching] <source-path> [<mongodb-url>] [--commit=<commit_hash> | (--commit=<commit_hash> --patch=<patch_id>)]
+  snooty build [--no-caching] <source-path> [<mongodb-url>] [options]
   snooty watch [--no-caching] <source-path>
   snooty [--no-caching] language-server
 
@@ -10,6 +10,7 @@
   --commit=<commit_hash>    Commit hash of build.
   --patch=<patch_id>        Patch ID of build. Must be specified with a commit hash.
   --no-caching              Disable HTTP response caching.
+  --rstspec=<url>           Override the reStructuredText directive & role spec.
 
 Environment variables:
   SNOOTY_PARANOID           0, 1 where 0 is default
@@ -34,7 +35,7 @@
 import watchdog.observers
 from docopt import docopt
 
-from . import __version__, language_server
+from . import __version__, language_server, specparser
 from .diagnostics import Diagnostic, MakeCorrectionMixin
 from .page import Page
 from .parser import Project, ProjectBackend
@@ -280,6 +281,15 @@ def main() -> None:
 
     logger.info(f"Snooty {__version__} starting")
 
+    if args["--rstspec"]:
+        rstspec_path = args["--rstspec"]
+        if rstspec_path.startswith("https://") or rstspec_path.startswith("http://"):
+            rstspec_bytes = HTTPCache.singleton().get(args["--rstspec"])
+            rstspec_text = str(rstspec_bytes, "utf-8")
+        else:
+            rstspec_text = Path(rstspec_path).read_text(encoding="utf-8")
+        specparser.Spec.initialize(rstspec_text)
+
     if PARANOID_MODE:
         logger.info("Paranoid mode on")
 

snooty/parser.py

@@ -492,7 +492,7 @@ def handle_tabset(self, node: n.Directive) -> None:
         line = node.start[0]
         # retrieve dictionary associated with this specific tabset
         try:
-            tab_definitions_list = specparser.SPEC.tabs[tabset]
+            tab_definitions_list = specparser.Spec.get().tabs[tabset]
         except KeyError:
             self.diagnostics.append(UnknownTabset(tabset, line))
             return

snooty/postprocess.py

@@ -1242,6 +1242,7 @@ def __init__(self, context: Context) -> None:
         super().__init__(context)
         self.project_config = context[ProjectConfig]
         self.targets = context[TargetDatabase]
+        self.spec = specparser.Spec.get()
 
     def enter_node(self, fileid_stack: FileIdStack, node: n.Node) -> None:
         """When a node of type ref_role is encountered, ensure that it references a valid target.
@@ -1265,7 +1266,7 @@ def enter_node(self, fileid_stack: FileIdStack, node: n.Node) -> None:
         if not target_candidates:
             # insert title and raise diagnostic
             line = node.span[0]
-            target_dict = specparser.SPEC.rstobject
+            target_dict = self.spec.rstobject
             target_key = f"{node.domain}:{node.name}"
             title = node.target
             # abstract title from node's target to insert into new text node

snooty/rstparser.py

@@ -1022,7 +1022,7 @@ def get(cls, default_domain: Optional[str]) -> "Registry":
         ):
             return cls.CURRENT_REGISTRY[1]
 
-        registry = register_spec_with_docutils(specparser.SPEC, default_domain)
+        registry = register_spec_with_docutils(specparser.Spec.get(), default_domain)
         cls.CURRENT_REGISTRY = (default_domain, registry)
         return registry
 

snooty/specparser.py

@@ -1,12 +1,15 @@
 """Parser for a TOML spec file containing definitions of all supported reStructuredText
    directives and roles, and what types of data each should expect."""
 
+from __future__ import annotations
+
 import dataclasses
 from dataclasses import dataclass, field
 from enum import Enum
 from typing import (
     Any,
     Callable,
+    ClassVar,
     Dict,
     FrozenSet,
     List,
@@ -271,6 +274,8 @@ class Spec:
     rstobject: Dict[str, RstObject] = field(default_factory=dict)
     tabs: Dict[str, List[TabDefinition]] = field(default_factory=dict)
 
+    SPEC: ClassVar[Optional[Spec]] = None
+
     @classmethod
     def loads(cls, data: str) -> "Spec":
         """Load a spec from a string."""
@@ -392,6 +397,16 @@ def resolve_value(key: str, inheritable: _T) -> _T:
         for key, inheritable in inheritable_index.items():
             resolve_value(key, inheritable)
 
+    @classmethod
+    def initialize(cls, text: str) -> None:
+        cls.SPEC = Spec.loads(text)
 
-GLOBAL_SPEC_PATH = util.PACKAGE_ROOT.joinpath("rstspec.toml")
-SPEC = Spec.loads(GLOBAL_SPEC_PATH.read_text(encoding="utf-8"))
+    @classmethod
+    def get(cls) -> "Spec":
+        if cls.SPEC is None:
+            path = util.PACKAGE_ROOT.joinpath("rstspec.toml")
+            cls.initialize(path.read_text(encoding="utf-8"))
+
+        spec = cls.SPEC
+        assert spec is not None
+        return spec

snooty/target_database.py

@@ -56,6 +56,8 @@ def __getitem__(self, key: str) -> Sequence["TargetDatabase.Result"]:
         key = normalize_target(key)
         results: List[TargetDatabase.Result] = []
 
+        spec = specparser.Spec.get()
+
         with self.lock:
             # Check to see if the target is defined locally
             try:
@@ -93,7 +95,7 @@ def __getitem__(self, key: str) -> Sequence["TargetDatabase.Result"]:
                     if display_name is None:
                         display_name = entry.name
 
-                        display_name = specparser.SPEC.strip_prefix_from_name(
+                        display_name = spec.strip_prefix_from_name(
                             entry.domain_and_role, display_name
                         )