markwork 0.1.1.dev0__py3-none-any.whl → 0.1.2.dev0__py3-none-any.whl

markwork/__init__.py

@@ -9,12 +9,12 @@ A project enables it with a single line in conf.py:
     extensions = ["markwork"]
 
 The generator then runs at 'builder-inited', writing one page per source
-file into the docs source tree before Sphinx reads it. Three configuration
+file into the docs source tree before Sphinx reads it. Four configuration
 values steer it: markwork_package names the package to document (or it is
 auto-detected when a single package sits under the source root),
 markwork_src_root and markwork_tests_root give the source and test roots
-relative to the project, which is taken to be the parent of the docs
-directory.
+relative to the project, and markwork_repo_root names the project root,
+relative to the docs directory, which defaults to that directory's parent.
 """
 #  Apache-2.0 license
 #  Copyright (c) 2026 Asger Jon Vistisen
@@ -22,9 +22,9 @@ directory.
 from pathlib import Path
 
 from . import engine
-from .engine import generate
+from .engine import collapseNavigation, generate
 
-__version__ = "0.1.1-dev0"
+__version__ = "0.1.2-dev0"
 
 __all__ = ["setup", "generate", "engine"]
 
@@ -33,16 +33,31 @@ def setup(app: object) -> dict:
   """Register markwork as a Sphinx extension: declare its configuration
   values, run the generator before Sphinx reads sources, and ship the
   stylesheet that styles the go-to-definition anchors and the line-jump
-  highlight, so a project manages no CSS paths of its own."""
+  highlight, so a project manages no CSS paths of its own.
+
+  markwork_repo_root pins the documented project root; left unset it
+  defaults to the parent of the docs directory, so an in-tree docs build
+  needs no extra configuration while the 'markwork' CLI can point the
+  engine at an arbitrary repository from a throwaway conf directory.
+  markwork_collapse_navigation (True by default) keeps every page's
+  navigation tree to its own branch; see 'collapseNavigation'."""
   app.add_config_value("markwork_package", None, "env")
   app.add_config_value("markwork_src_root", "src", "env")
   app.add_config_value("markwork_tests_root", "tests", "env")
+  app.add_config_value("markwork_repo_root", None, "env")
+  app.add_config_value("markwork_collapse_navigation", True, "html")
   app.connect("builder-inited", generate)
+  #  Ahead of the theme's own handler (default priority 500), so the
+  #  theme builds its sidebar from the collapsed tree.
+  app.connect("html-page-context", collapseNavigation, priority=400)
   static = str(Path(__file__).parent / "etc")
   app.config.html_static_path.append(static)
   app.add_css_file("markwork.css")
+  #  The generator runs once, at builder-inited, before any source is
+  #  read, and keeps nothing in the build environment, so reading and
+  #  writing may both run in parallel ('sphinx-build -j auto').
   return {
     "version": __version__,
-    "parallel_read_safe": False,
+    "parallel_read_safe": True,
     "parallel_write_safe": True,
   }

markwork/__main__.py

@@ -0,0 +1,11 @@
+"""
+Run markwork as a module: 'python -m markwork <repo>' is the same
+ephemeral build as the 'markwork' console script.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+
+from ._cli import main
+
+if __name__ == "__main__":
+  raise SystemExit(main())

markwork/_cli.py

@@ -0,0 +1,279 @@
+"""
+The markwork command line: point it at a repository and it generates the
+click-through Sphinx docs, with no conf.py, index.rst or scaffolding left
+behind in the project.
+
+The build is ephemeral. A throwaway conf.py and index.rst are written into
+a temporary directory that doubles as the Sphinx source directory; the
+'markwork_repo_root' config value points the engine back at the real
+project, so its source is read in place and only the rendered HTML is
+produced. The temporary directory is removed afterwards, so the repository
+is never touched.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+
+import argparse
+import importlib.util
+import os
+import shutil
+import sys
+import tempfile
+import webbrowser
+from pathlib import Path
+
+from sphinx.application import Sphinx
+from sphinx.errors import SphinxError
+
+from ._layout import detectLayout, readPyproject
+
+
+def projectMeta(repoRoot) -> tuple:
+  """Read the project name and version from a repo's pyproject.toml.
+
+  Falls back to the repository directory name and an empty version when
+  there is no pyproject.toml or it names neither, so the build always has a
+  heading to render.
+
+  Parameters
+  ----------
+  repoRoot : str or Path
+      The repository root to read.
+
+  Returns
+  -------
+  tuple
+      A pair '(name, version)' of strings.
+  """
+  repoRoot = Path(repoRoot)
+  project = readPyproject(repoRoot).get("project", {})
+  name, version = project.get("name"), project.get("version")
+  return name or repoRoot.name, version or ""
+
+
+def defaultTheme() -> str:
+  """Return furo when it is installed, else Sphinx's built-in alabaster,
+  so the command works even where furo was left out.
+
+  Returns
+  -------
+  str
+      The HTML theme name.
+  """
+  return "furo" if importlib.util.find_spec("furo") else "alabaster"
+
+
+def writeWorkspace(
+    work: Path, repoRoot: Path, srcRoot: str, testsRoot: str, package,
+    project: str, release: str, theme: str
+) -> None:
+  """Write the throwaway conf.py and index.rst into the work directory.
+
+  The conf enables only the markwork extension and the chosen theme, and
+  hands the engine the repo root and the source, tests and package
+  settings. The index gives the build its title and pulls in the package
+  index the engine writes during the build.
+
+  Parameters
+  ----------
+  work : Path
+      The temporary Sphinx source directory.
+  repoRoot : Path
+      The repository being documented.
+  srcRoot : str
+      The source root, relative to the repo root.
+  testsRoot : str
+      The tests root, relative to the repo root.
+  package : str or None
+      The package name, or None to auto-detect.
+  project : str
+      The documentation title.
+  release : str
+      The version string shown in the header.
+  theme : str
+      The Sphinx HTML theme.
+  """
+  conf = "\n".join(
+      [
+        "#  Generated by markwork; ephemeral, safe to delete.",
+        "project = %r" % project,
+        "release = %r" % release,
+        "version = %r" % release,
+        'extensions = ["markwork"]',
+        "html_theme = %r" % theme,
+        "markwork_repo_root = %r" % str(repoRoot),
+        "markwork_src_root = %r" % srcRoot,
+        "markwork_tests_root = %r" % testsRoot,
+        "markwork_package = %r" % package,
+        'exclude_patterns = ["_build", ".doctrees"]',
+        #  A page's rST is a generated wrapper around its source, so the
+        #  theme's "view source" link and the copies behind it add weight
+        #  and show nothing worth reading.
+        "html_copy_source = False",
+        "html_show_sourcelink = False",
+        "",
+      ]
+  )
+  (work / "conf.py").write_text(conf, encoding="utf-8")
+  heading = project or repoRoot.name
+  index = "\n".join(
+      [
+        heading,
+        "=" * len(heading),
+        "",
+        ".. include:: _source/_packages.txt",
+        "",
+      ]
+  )
+  (work / "index.rst").write_text(index, encoding="utf-8")
+
+
+def build(
+    repo, *, srcRoot=None, testsRoot=None, package=None, output=None,
+    theme=None, quiet=False, jobs=None
+) -> Path:
+  """Generate the markwork HTML for a repository and return the output dir.
+
+  The source root and package are resolved by 'detectLayout' from what the
+  project declares and from convention, and the tests are taken from
+  'tests/'; each can be named instead. A temporary directory holds the generated conf.py and
+  index.rst and serves as the Sphinx source directory; the engine reads the
+  project's source in place via 'markwork_repo_root' and the HTML is built
+  into the output directory. The temporary directory is removed afterwards,
+  so the repository is left untouched.
+
+  Parameters
+  ----------
+  repo : str or Path
+      The repository root to document.
+  srcRoot : str, optional
+      The source root relative to the repo; auto-detected when omitted.
+  testsRoot : str, optional
+      The tests root relative to the repo; 'tests' when omitted.
+  package : str, optional
+      The package name; auto-detected when omitted.
+  output : str or Path, optional
+      The HTML output directory; a temporary one is made when omitted.
+  theme : str, optional
+      The Sphinx HTML theme; 'defaultTheme' picks one when omitted.
+  quiet : bool
+      Suppress Sphinx's progress output when True.
+  jobs : int, optional
+      The number of parallel Sphinx workers, one per CPU when omitted.
+      markwork does its own work before Sphinx starts and declares itself
+      safe for parallel writing, which is where a large project spends its
+      time, so the pages come out identical either way.
+
+  Returns
+  -------
+  Path
+      The output directory the HTML was written to.
+  """
+  repoRoot = Path(repo).resolve()
+  if not repoRoot.is_dir():
+    raise NotADirectoryError(str(repoRoot))
+  srcRoot, testsRoot, package = detectLayout(
+      repoRoot, src=srcRoot, tests=testsRoot, package=package
+  )
+  project, release = projectMeta(repoRoot)
+  theme = theme or defaultTheme()
+  if not quiet:
+    where = "the repo root" if srcRoot == "." else "%s/" % srcRoot
+    print(
+        "markwork: documenting %s under %s, tests: %s"
+        % (package, where, testsRoot or "(none)")
+    )
+  if output is None:
+    output = tempfile.mkdtemp(prefix="markwork-html-")
+  output = Path(output).resolve()
+  work = Path(tempfile.mkdtemp(prefix="markwork-conf-"))
+  try:
+    writeWorkspace(
+        work, repoRoot, srcRoot, testsRoot or "tests", package, project,
+        release, theme
+    )
+    workers = jobs if jobs is not None else os.cpu_count() or 1
+    app = Sphinx(
+        str(work), str(work), str(output), str(work / ".doctrees"), "html",
+        status=None if quiet else sys.stdout, warning=sys.stderr,
+        parallel=workers if workers > 1 else 0,
+    )
+    app.build()
+  finally:
+    shutil.rmtree(work, ignore_errors=True)
+  return output
+
+
+def main(argv=None) -> int:
+  """Parse arguments and run an ephemeral markwork build.
+
+  Parameters
+  ----------
+  argv : list of str, optional
+      The argument vector; sys.argv is used when omitted.
+
+  Returns
+  -------
+  int
+      The process exit code.
+  """
+  parser = argparse.ArgumentParser(
+      prog="markwork",
+      description="Generate click-through Sphinx docs for a repository, "
+                  "with no project setup.",
+  )
+  parser.add_argument(
+      "repo", nargs="?", default=".", help="repository root (default: .)"
+  )
+  parser.add_argument(
+      "-o", "--output", default=None,
+      help="HTML output directory (default: a temporary directory)",
+  )
+  parser.add_argument(
+      "--src", default=None,
+      help="source root relative to the repo (default: auto-detect)",
+  )
+  parser.add_argument(
+      "--tests", default=None,
+      help="tests root relative to the repo (default: tests)",
+  )
+  parser.add_argument(
+      "--package", default=None,
+      help="package to document (default: auto-detect)",
+  )
+  parser.add_argument(
+      "--theme", default=None,
+      help="Sphinx HTML theme (default: furo if installed, else alabaster)",
+  )
+  parser.add_argument(
+      "--open", action="store_true", dest="open_browser",
+      help="open the rendered docs in a browser when done",
+  )
+  parser.add_argument(
+      "-q", "--quiet", action="store_true",
+      help="suppress Sphinx progress output",
+  )
+  parser.add_argument(
+      "-j", "--jobs", type=int, default=None,
+      help="parallel Sphinx workers (default: one per CPU)",
+  )
+  args = parser.parse_args(argv)
+  try:
+    output = build(
+        args.repo, srcRoot=args.src, testsRoot=args.tests,
+        package=args.package, output=args.output, theme=args.theme,
+        quiet=args.quiet, jobs=args.jobs,
+    )
+  except (RuntimeError, NotADirectoryError) as error:
+    print(str(error), file=sys.stderr)
+    return 1
+  except SphinxError as error:
+    #  A bad theme, a broken extension and the like: Sphinx's own message
+    #  is clear, so it is shown without the traceback.
+    print("markwork: Sphinx stopped: %s" % error, file=sys.stderr)
+    return 2
+  index = output / "index.html"
+  print("markwork: wrote %s" % index)
+  if args.open_browser:
+    webbrowser.open(index.as_uri())
+  return 0

markwork/_layout.py

@@ -0,0 +1,214 @@
+"""
+Layout discovery for the markwork command line: work out where a
+repository keeps its source, reading what the project already declares
+before falling back to convention.
+
+The source root and package come from the build configuration in
+pyproject.toml (setuptools 'packages.find.where' / 'package-dir', with the
+distribution name disambiguating when several packages qualify). When it
+is not declared, convention decides: 'src/' if it holds a package and the
+repo root otherwise. The tests are expected in 'tests/'. Nothing searches
+for them: a project that keeps them elsewhere names the folder. Explicit
+overrides always win, and an ambiguous package fails loudly rather than
+guessing. Nothing here imports the documented project; it only reads
+files.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+
+import tomllib
+from pathlib import Path
+
+#  Conventional top-level directory names that hold tests, docs or tooling
+#  rather than the package, consulted only to settle an ambiguity in a
+#  flat layout.
+_NOT_PACKAGES = frozenset(
+    {
+      "tests", "test", "testing", "docs", "doc", "examples", "example",
+      "benchmarks", "scripts", "tools",
+    }
+)
+
+
+def readPyproject(repoRoot) -> dict:
+  """Parse a repo's pyproject.toml, or return an empty mapping.
+
+  Returns an empty dict when there is no file or when it cannot be parsed,
+  so callers degrade to convention rather than fail.
+
+  Parameters
+  ----------
+  repoRoot : str or Path
+      The repository root to read from.
+
+  Returns
+  -------
+  dict
+      The parsed pyproject.toml, or an empty mapping.
+  """
+  path = Path(repoRoot) / "pyproject.toml"
+  if not path.is_file():
+    return {}
+  try:
+    with path.open("rb") as handle:
+      return tomllib.load(handle)
+  except (OSError, tomllib.TOMLDecodeError):
+    return {}
+
+
+def _hasPackage(directory: Path) -> bool:
+  """Return whether a directory holds at least one importable package."""
+  return any(
+      child.is_dir() and (child / "__init__.py").is_file()
+      for child in directory.iterdir()
+  )
+
+
+def detectSrcRoot(repoRoot, data: dict) -> str:
+  """Return the source root, relative to the repo root.
+
+  The setuptools 'packages.find.where' and 'package-dir' settings are read
+  first; failing that, 'src' is used when it holds a package and the repo
+  root ('.') otherwise.
+
+  Parameters
+  ----------
+  repoRoot : str or Path
+      The repository root.
+  data : dict
+      The parsed pyproject.toml.
+
+  Returns
+  -------
+  str
+      The source root relative to the repo root.
+  """
+  setuptools = data.get("tool", {}).get("setuptools", {})
+  packages = setuptools.get("packages", {})
+  if isinstance(packages, dict):
+    where = packages.get("find", {}).get("where")
+    if isinstance(where, list) and where:
+      return where[0]
+  packageDir = setuptools.get("package-dir", {})
+  if isinstance(packageDir, dict) and isinstance(packageDir.get(""), str):
+    return packageDir[""]
+  srcDir = Path(repoRoot) / "src"
+  if srcDir.is_dir() and _hasPackage(srcDir):
+    return "src"
+  return "."
+
+
+def detectPackageName(srcDir, hint) -> str:
+  """Return the single package under a source root, or raise.
+
+  A hint (the distribution name) is honoured when it matches a package,
+  matching case-insensitively; otherwise a lone package wins. In a flat
+  layout the tests or docs often hold an __init__.py too, so when exactly
+  one candidate is left after setting aside the conventional names for
+  those ('tests', 'docs', 'examples' and the like), that one wins.
+  Anything else is ambiguous and raises, so a multi-package source root
+  fails loudly rather than documenting the wrong tree.
+
+  Parameters
+  ----------
+  srcDir : str or Path
+      The resolved source root directory.
+  hint : str or None
+      The expected package name, or None.
+
+  Returns
+  -------
+  str
+      The package name.
+
+  Raises
+  ------
+  RuntimeError
+      When the source root does not exist or holds no single package and
+      the hint does not pick one.
+  """
+  srcDir = Path(srcDir)
+  if not srcDir.is_dir():
+    raise RuntimeError("markwork: source root %s does not exist" % srcDir)
+  candidates = sorted(
+      child.name for child in srcDir.iterdir()
+      if child.is_dir() and (child / "__init__.py").is_file()
+  )
+  if hint:
+    lowered = {name.lower(): name for name in candidates}
+    match = lowered.get(hint.lower())
+    if match is not None:
+      return match
+  if len(candidates) == 1:
+    return candidates[0]
+  narrowed = [name for name in candidates if name.lower() not in _NOT_PACKAGES]
+  if len(narrowed) == 1:
+    return narrowed[0]
+  found = ", ".join(candidates) or "none"
+  raise RuntimeError(
+      "markwork could not pick a package under %s (found: %s); pass "
+      "--package (or set markwork_package)" % (srcDir, found)
+  )
+
+
+def detectLayout(repoRoot, *, src=None, tests=None, package=None) -> tuple:
+  """Resolve the source root, tests root and package for a repository.
+
+  Each explicit argument is honoured as given. The source root and the
+  package are otherwise detected from what the project declares, then from
+  convention; the tests are taken from 'tests/' and never searched for.
+  The package is resolved to a concrete name (raising when ambiguous), so
+  the build is deterministic and fails before Sphinx is invoked rather
+  than during it.
+
+  Parameters
+  ----------
+  repoRoot : str or Path
+      The repository root.
+  src : str, optional
+      An explicit source root relative to the repo.
+  tests : str, optional
+      The tests root relative to the repo, for a project that keeps its
+      tests somewhere other than 'tests/'.
+  package : str, optional
+      An explicit package name.
+
+  Returns
+  -------
+  tuple
+      A triple '(srcRoot, testsRoot, package)'. 'srcRoot' and 'package' are
+      strings; 'testsRoot' is a string, or None when no tests root is
+      named and the repository has no 'tests/' folder.
+
+  Raises
+  ------
+  RuntimeError
+      When the package cannot be resolved, or when a named tests root
+      does not exist.
+  """
+  repoRoot = Path(repoRoot)
+  data = readPyproject(repoRoot)
+  srcRoot = src if src is not None else detectSrcRoot(repoRoot, data)
+  srcDir = repoRoot / srcRoot
+  if package is not None:
+    if not (srcDir / package).is_dir():
+      raise RuntimeError(
+          "markwork: package %r not found under %s" % (package, srcDir)
+      )
+    resolved = package
+  else:
+    name = data.get("project", {}).get("name")
+    hint = (
+        name.replace("-", "_").replace(".", "_")
+        if isinstance(name, str) else None
+    )
+    resolved = detectPackageName(srcDir, hint)
+  if tests is None:
+    testsRoot = "tests" if (repoRoot / "tests").is_dir() else None
+  elif (repoRoot / tests).is_dir():
+    testsRoot = tests
+  else:
+    raise RuntimeError(
+        "markwork: tests root %r not found under %s" % (tests, repoRoot)
+    )
+  return srcRoot, testsRoot, resolved

markwork/engine/__init__.py

@@ -16,22 +16,28 @@ it documents itself.
 
 #  Constants
 from ._pydocs import PYDOCS
+#  Reading source
+from ._read_source import readSource
+from ._parse_source import parseSource
 #  Pure rendering helpers
+from ._rst_text import rstText
 from ._title import title
 from ._line_starts import lineStarts
+from ._char_offset import charOffset
 from ._css_class import cssClass
 from ._token_html import tokenHtml
 from ._merge_tokens import mergeTokens
+from ._lex_tokens import lexTokens
 from ._highlight import highlightWithLinks
 #  Pure AST helpers
-from ._top_level_defs import topLevelDefs
-from ._top_level_def_lines import topLevelDefLines
-from ._parse_init import parseInit
+from ._module_statements import moduleStatements
 from ._module_definitions import moduleDefinitions
-from ._nested_bound import nestedBound
-from ._bound_anywhere import boundAnywhere
-from ._add_alias_site import addAliasSite
+from ._parse_init import parseInit
+from ._attribute_chain import attributeChain
 from ._abs_module import absModule
+#  Scope resolution
+from ._scope import Scope
+from ._resolve_scopes import resolveScopes
 #  Standard-library and builtin link helpers
 from ._is_stdlib import isStdlib
 from ._builtin_links import buildBuiltinLinks, BUILTIN_LINKS
@@ -39,27 +45,33 @@ from ._builtin_links import buildBuiltinLinks, BUILTIN_LINKS
 from ._detect_package import detectPackage
 from ._source_docs import SourceDocs
 from ._generate import generate
+from ._collapse_navigation import collapseNavigation
 
 __all__ = [
   "PYDOCS",
+  "readSource",
+  "parseSource",
+  "rstText",
   "title",
   "lineStarts",
+  "charOffset",
   "cssClass",
   "tokenHtml",
   "mergeTokens",
+  "lexTokens",
   "highlightWithLinks",
-  "topLevelDefs",
-  "topLevelDefLines",
-  "parseInit",
+  "moduleStatements",
   "moduleDefinitions",
-  "nestedBound",
-  "boundAnywhere",
-  "addAliasSite",
+  "parseInit",
+  "attributeChain",
   "absModule",
+  "Scope",
+  "resolveScopes",
   "isStdlib",
   "buildBuiltinLinks",
   "BUILTIN_LINKS",
   "detectPackage",
   "SourceDocs",
   "generate",
+  "collapseNavigation",
 ]

markwork/engine/_abs_module.py

@@ -13,7 +13,8 @@ def absModule(srcRoot: Path, pyfile: Path, level: int, module) -> str:
 
   Relative imports (level >= 1) are resolved against the file's package. A
   relative import in a file outside the source root (for example a test)
-  cannot name a project symbol, so it resolves to the empty string.
+  cannot name a project symbol, and one that climbs above the top-level
+  package fails at runtime, so both resolve to the empty string.
 
   Parameters
   ----------
@@ -38,7 +39,10 @@ def absModule(srcRoot: Path, pyfile: Path, level: int, module) -> str:
     pkgParts = pyfile.parent.relative_to(srcRoot).parts
   except ValueError:
     return ""
-  base = list(pkgParts[:len(pkgParts) - (level - 1)])
+  keep = len(pkgParts) - (level - 1)
+  if keep < 1:
+    return ""
+  base = list(pkgParts[:keep])
   if module:
     base += module.split(".")
   return ".".join(base)