markwork 0.1.0.dev0__py3-none-any.whl

markwork/__init__.py

@@ -0,0 +1,48 @@
+"""markwork is a Sphinx extension that renders a project's Python source
+verbatim and makes every name a link to where it is defined: a project
+symbol or a same-file name jumps to its definition, a standard-library
+member or a builtin links to docs.python.org. It replaces autodoc, not
+Sphinx.
+
+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
+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.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+
+from pathlib import Path
+
+from . import engine
+from .engine import generate
+
+__version__ = "0.1.0-dev0"
+
+__all__ = ["setup", "generate", "engine"]
+
+
+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."""
+  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.connect("builder-inited", generate)
+  static = str(Path(__file__).parent / "etc")
+  app.config.html_static_path.append(static)
+  app.add_css_file("markwork.css")
+  return {
+    "version": __version__,
+    "parallel_read_safe": False,
+    "parallel_write_safe": True,
+  }

markwork/engine/__init__.py

@@ -0,0 +1,65 @@
+"""The engine behind markwork: it reads a project's source as text,
+highlights it with Pygments, resolves every name to where it is defined,
+and writes one navigable page per file.
+
+The layer is built without 're', by design and as the tool's signature:
+the AST, the Pygments token stream, and plain string methods do all the
+work. Each leaf helper is a standalone function with no markwork state;
+the stateful 'SourceDocs' class owns the registries and paths and drives
+a whole run. Every symbol is re-exported here, so the engine is a public
+subpackage: 'generate' is the one the 'setup(app)' entry point wires to
+Sphinx, and the rest is open for reuse and is what markwork renders when
+it documents itself.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+
+#  Constants
+from ._pydocs import PYDOCS
+#  Pure rendering helpers
+from ._title import title
+from ._line_starts import lineStarts
+from ._css_class import cssClass
+from ._token_html import tokenHtml
+from ._merge_tokens import mergeTokens
+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_definitions import moduleDefinitions
+from ._nested_bound import nestedBound
+from ._bound_anywhere import boundAnywhere
+from ._add_alias_site import addAliasSite
+from ._abs_module import absModule
+#  Standard-library and builtin link helpers
+from ._is_stdlib import isStdlib
+from ._builtin_links import buildBuiltinLinks, BUILTIN_LINKS
+#  Package resolution and the run driver
+from ._detect_package import detectPackage
+from ._source_docs import SourceDocs
+from ._generate import generate
+
+__all__ = [
+  "PYDOCS",
+  "title",
+  "lineStarts",
+  "cssClass",
+  "tokenHtml",
+  "mergeTokens",
+  "highlightWithLinks",
+  "topLevelDefs",
+  "topLevelDefLines",
+  "parseInit",
+  "moduleDefinitions",
+  "nestedBound",
+  "boundAnywhere",
+  "addAliasSite",
+  "absModule",
+  "isStdlib",
+  "buildBuiltinLinks",
+  "BUILTIN_LINKS",
+  "detectPackage",
+  "SourceDocs",
+  "generate",
+]

markwork/engine/_abs_module.py

@@ -0,0 +1,44 @@
+"""
+The 'absModule' function resolves an import target to an absolute dotted
+module.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+
+from pathlib import Path
+
+
+def absModule(srcRoot: Path, pyfile: Path, level: int, module) -> str:
+  """Resolve an import target to an absolute dotted module.
+
+  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.
+
+  Parameters
+  ----------
+  srcRoot : Path
+      The source root the package lives under.
+  pyfile : Path
+      The file containing the import.
+  level : int
+      The import's relative level: 0 for an absolute import.
+  module : str or None
+      The dotted module named by the import, if any.
+
+  Returns
+  -------
+  str
+      The absolute dotted module, or the empty string when it cannot be
+      resolved.
+  """
+  if level == 0:
+    return module or ""
+  try:
+    pkgParts = pyfile.parent.relative_to(srcRoot).parts
+  except ValueError:
+    return ""
+  base = list(pkgParts[:len(pkgParts) - (level - 1)])
+  if module:
+    base += module.split(".")
+  return ".".join(base)

markwork/engine/_add_alias_site.py

@@ -0,0 +1,31 @@
+"""
+The 'addAliasSite' function records the source offset of an import alias'
+name token.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+
+import ast
+
+
+def addAliasSite(
+    sites: list, alias: ast.alias, starts: list, local: str
+) -> None:
+  """Record the source offset of an import alias' name token.
+
+  This makes the name as it appears in the 'import' line itself a link.
+  The position attributes on ast.alias are guaranteed from Python 3.10,
+  markwork's floor, so no presence guard is needed.
+
+  Parameters
+  ----------
+  sites : list
+      The list of '(offset, local)' pairs to append to.
+  alias : ast.alias
+      The import alias node.
+  starts : list of int
+      The per-line start offsets, as from 'lineStarts'.
+  local : str
+      The local name the alias binds.
+  """
+  sites.append((starts[alias.lineno - 1] + alias.col_offset, local))

markwork/engine/_bound_anywhere.py

@@ -0,0 +1,42 @@
+"""
+The 'boundAnywhere' function collects every name bound anywhere in a file.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+
+import ast
+
+
+def boundAnywhere(tree: ast.AST) -> set:
+  """Return every name bound anywhere in the file, at any scope.
+
+  This covers assignments and deletions, parameters, class and function
+  names, and import targets. A builtin whose name appears here is shadowed
+  by local code, so its uses are left unlinked.
+
+  Parameters
+  ----------
+  tree : ast.AST
+      The parsed module.
+
+  Returns
+  -------
+  set of str
+      Every bound name found anywhere in the tree.
+  """
+  names = set()
+  for node in ast.walk(tree):
+    if isinstance(node, ast.Name) and isinstance(
+        node.ctx, (ast.Store, ast.Del)
+    ):
+      names.add(node.id)
+    elif isinstance(node, ast.arg):
+      names.add(node.arg)
+    elif isinstance(
+        node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)
+    ):
+      names.add(node.name)
+    elif isinstance(node, (ast.Import, ast.ImportFrom)):
+      for alias in node.names:
+        names.add(alias.asname or alias.name.split(".")[0])
+  return names

markwork/engine/_builtin_links.py

@@ -0,0 +1,67 @@
+"""
+The 'buildBuiltinLinks' function maps every public builtin to its page on
+docs.python.org.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+
+import builtins
+
+from ._pydocs import PYDOCS
+
+_CONSTANTS = frozenset(
+    {"True", "False", "None", "NotImplemented", "Ellipsis"}
+)
+
+#  The container types are listed on the built-in functions page under a
+#  'func-<name>' anchor rather than a bare '<name>' (that bare anchor lives
+#  on the standard types page instead). Every other builtin function or
+#  type uses its plain '<name>' anchor there.
+_FUNC_ANCHOR = frozenset(
+    {
+      "bytearray", "bytes", "dict", "frozenset", "list", "memoryview",
+      "range", "set", "str", "tuple"
+    }
+)
+
+#  Builtins added by the site module: documented in their own section of
+#  the constants page rather than on the functions page.
+_SITE_CONSTANTS = frozenset(
+    {"copyright", "credits", "exit", "license", "quit"}
+)
+
+
+def buildBuiltinLinks() -> dict:
+  """Map every public builtin name to its page on docs.python.org.
+
+  Exceptions go to the exceptions page; the True/None family and the
+  site-module builtins (quit, exit, ...) go to the constants page; the
+  container types go to their 'func-<name>' anchor on the built-in
+  functions page; and every other function or type goes to its plain
+  anchor there.
+
+  Returns
+  -------
+  dict
+      A mapping of builtin name to its documentation URL.
+  """
+  links = {}
+  for name in dir(builtins):
+    if name.startswith("_"):
+      continue
+    if name in _CONSTANTS or name in _SITE_CONSTANTS:
+      links[name] = "%slibrary/constants.html#%s" % (PYDOCS, name)
+      continue
+    member = getattr(builtins, name)
+    if isinstance(member, type) and issubclass(member, BaseException):
+      links[name] = "%slibrary/exceptions.html#%s" % (PYDOCS, name)
+    elif name in _FUNC_ANCHOR:
+      links[name] = "%slibrary/functions.html#func-%s" % (PYDOCS, name)
+    else:
+      links[name] = "%slibrary/functions.html#%s" % (PYDOCS, name)
+  return links
+
+
+#  Computed once at import: the link table the resolver consults for every
+#  unshadowed builtin use.
+BUILTIN_LINKS = buildBuiltinLinks()

markwork/engine/_css_class.py

@@ -0,0 +1,32 @@
+"""
+The 'cssClass' function resolves a Pygments token type to its short CSS
+class.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+
+from pygments.token import STANDARD_TYPES
+
+
+def cssClass(ttype: object) -> str:
+  """Return the short Pygments CSS class for a token type.
+
+  When the exact type is not in the standard table, the lookup walks up to
+  a parent type. The root token maps to the empty string, meaning the
+  token gets no wrapping span.
+
+  Parameters
+  ----------
+  ttype : object
+      A Pygments token type.
+
+  Returns
+  -------
+  str
+      The CSS class, for example 'n', 'k' or 's2', or the empty string
+      for the root token.
+  """
+  node = ttype
+  while node not in STANDARD_TYPES:
+    node = node.parent
+  return STANDARD_TYPES[node]

markwork/engine/_detect_package.py

@@ -0,0 +1,47 @@
+"""
+The 'detectPackage' function resolves the package directory to document.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+
+from pathlib import Path
+
+
+def detectPackage(srcRoot: Path, name) -> Path:
+  """Resolve the package directory under the source root.
+
+  A configured name wins; otherwise the source root must hold exactly one
+  importable package and that one is used. Anything else is ambiguous and
+  raises, so a misconfigured project fails loudly rather than documenting
+  the wrong tree.
+
+  Parameters
+  ----------
+  srcRoot : Path
+      The source root to search.
+  name : str or None
+      The configured package name, or None to auto-detect.
+
+  Returns
+  -------
+  Path
+      The resolved package directory.
+
+  Raises
+  ------
+  RuntimeError
+      When no name is configured and the source root does not hold
+      exactly one importable package.
+  """
+  if name is not None:
+    return srcRoot / name
+  candidates = sorted(
+      child for child in srcRoot.iterdir()
+      if child.is_dir() and (child / "__init__.py").exists()
+  )
+  if len(candidates) == 1:
+    return candidates[0]
+  info = ("markwork could not pick a package under %s: set "
+          "markwork_package in conf.py. Found: %s")
+  names = ", ".join(child.name for child in candidates) or "none"
+  raise RuntimeError(info % (srcRoot, names))

markwork/engine/_generate.py

@@ -0,0 +1,35 @@
+"""
+The 'generate' function runs a documentation pass, resolving its paths
+from the Sphinx application.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+
+from pathlib import Path
+
+from ._detect_package import detectPackage
+from ._source_docs import SourceDocs
+
+
+def generate(app: object) -> None:
+  """Resolve the build paths from the Sphinx application and run a
+  documentation pass.
+
+  Wired to 'builder-inited' by the extension's setup(app). The project
+  root is the parent of the docs directory; the source and tests roots and
+  the package come from the markwork_* configuration values.
+
+  Parameters
+  ----------
+  app : object
+      The Sphinx application. Its 'confdir', 'srcdir' and 'config' are
+      read.
+  """
+  confdir = Path(app.confdir)
+  repoRoot = confdir.parent
+  config = app.config
+  srcRoot = repoRoot / config.markwork_src_root
+  testsRoot = repoRoot / config.markwork_tests_root
+  pkg = detectPackage(srcRoot, config.markwork_package)
+  out = Path(app.srcdir) / "_source"
+  SourceDocs(repoRoot, srcRoot, pkg, testsRoot, out).run()

markwork/engine/_highlight.py

@@ -0,0 +1,71 @@
+"""
+The 'highlightWithLinks' function renders source to highlighted HTML with
+go-to-definition anchors injected.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+
+import bisect
+
+from pygments.lexers import PythonLexer
+
+from ._css_class import cssClass
+from ._line_starts import lineStarts
+from ._merge_tokens import mergeTokens
+from ._token_html import tokenHtml
+
+_LEXER = PythonLexer()
+
+
+def highlightWithLinks(source: str, linkMap: dict) -> str:
+  """Render source to the highlighted HTML the Pygments HtmlFormatter
+  produces, wrapping linked tokens in go-to-definition anchors.
+
+  The output is a '.highlight' block with inline line numbers, each line
+  wrapped in '<span id="line-N">' as the '#line-N' jump target and the
+  ':target' highlight element. Every token whose start offset is a key of
+  'linkMap' is wrapped in an anchor. The token stream from
+  'get_tokens_unprocessed' carries each token's absolute offset, so the
+  anchors land exactly without searching the text. A token holding
+  newlines (a string or a run of blank lines) spans several line boxes and
+  is never a link target, so it is split across the lines it covers.
+
+  Parameters
+  ----------
+  source : str
+      The source text.
+  linkMap : dict
+      A mapping of absolute source offset to link target.
+
+  Returns
+  -------
+  str
+      The highlighted HTML fragment.
+  """
+  starts = lineStarts(source)
+  count = len(starts) - 1 if source.endswith("\n") else len(starts)
+  buffers = [""] * (count + 1)
+  for offset, ttype, value in mergeTokens(
+      _LEXER.get_tokens_unprocessed(source)
+      ):
+    css = cssClass(ttype)
+    if "\n" in value:
+      first = bisect.bisect_right(starts, offset)
+      for step, segment in enumerate(value.split("\n")):
+        line = first + step
+        if segment and line <= count:
+          buffers[line] += tokenHtml(css, segment, "")
+      continue
+    line = bisect.bisect_right(starts, offset)
+    buffers[line] += tokenHtml(css, value, linkMap.get(offset))
+  #  Line numbers are right-aligned to the width of the largest, matching
+  #  the Pygments HtmlFormatter so the gutter stays straight.
+  width = len(str(count))
+  parts = ['<div class="highlight"><pre><span></span>']
+  for line in range(1, count + 1):
+    parts.append(
+      '<span id="line-%d"><span class="linenos">%s</span>%s\n'
+      '</span>' % (line, str(line).rjust(width), buffers[line])
+      )
+  parts.append("</pre></div>\n")
+  return "".join(parts)

markwork/engine/_is_stdlib.py

@@ -0,0 +1,36 @@
+"""
+The 'isStdlib' function tests whether a module belongs to the standard
+library.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+
+import sys
+
+_STDLIB = sys.stdlib_module_names
+
+
+def isStdlib(module: str) -> bool:
+  """Return whether a module belongs to the standard library.
+
+  Membership is judged by the top-level package, so a submodule such as
+  'collections.abc' resolves too.
+
+  Parameters
+  ----------
+  module : str
+      A dotted module name, or the empty string.
+
+  Returns
+  -------
+  bool
+      True if the top-level package is a standard-library module.
+
+  Examples
+  --------
+  >>> isStdlib('collections.abc')
+  True
+  >>> isStdlib('')
+  False
+  """
+  return True if module and module.split(".")[0] in _STDLIB else False

markwork/engine/_line_starts.py

@@ -0,0 +1,35 @@
+"""
+The 'lineStarts' function indexes where each source line begins.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+
+
+def lineStarts(source: str) -> list:
+  """Return the character offset at which each line begins.
+
+  An AST node's '(lineno, col_offset)' is turned into an absolute offset
+  into the source as 'starts[lineno - 1] + col_offset', so the rendered
+  anchors land exactly without searching the text.
+
+  Parameters
+  ----------
+  source : str
+      The source text.
+
+  Returns
+  -------
+  list of int
+      The offset of the first character of each line. The first entry is
+      always 0.
+
+  Examples
+  --------
+  >>> lineStarts('ab\\ncd\\n')
+  [0, 3, 6]
+  """
+  starts = [0]
+  for index, char in enumerate(source):
+    if char == "\n":
+      starts.append(index + 1)
+  return starts

markwork/engine/_merge_tokens.py

@@ -0,0 +1,36 @@
+"""
+The 'mergeTokens' function coalesces consecutive tokens of identical type.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+
+
+def mergeTokens(stream) -> list:
+  """Merge consecutive tokens of identical type into one.
+
+  This is what Pygments' high-level 'get_tokens' does, so the rendered
+  spans group exactly as the stock HtmlFormatter groups them and the
+  output stays byte-identical once the anchors are stripped. The first
+  token's offset is kept, which is also where any go-to-definition link
+  for the run is anchored, since a link target always sits at a run's
+  start.
+
+  Parameters
+  ----------
+  stream : iterable of tuple
+      Tuples of '(offset, ttype, value)', as produced by
+      'get_tokens_unprocessed'.
+
+  Returns
+  -------
+  list of tuple
+      The merged tuples, in order.
+  """
+  merged = []
+  for offset, ttype, value in stream:
+    if merged and merged[-1][1] == ttype:
+      prevOff, prevType, prevVal = merged[-1]
+      merged[-1] = (prevOff, prevType, prevVal + value)
+    else:
+      merged.append((offset, ttype, value))
+  return merged

markwork/engine/_module_definitions.py

@@ -0,0 +1,42 @@
+"""
+The 'moduleDefinitions' function maps module-scope names to their first
+definition line.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+
+import ast
+
+
+def moduleDefinitions(tree: ast.AST) -> dict:
+  """Return each module-scope name mapped to the line it is defined on.
+
+  Classes, functions, simple assignments and annotated assignments with a
+  value are recorded; the first definition of a name wins. This is the
+  go-to-definition target for a later use of that name within the same
+  file.
+
+  Parameters
+  ----------
+  tree : ast.AST
+      The parsed module.
+
+  Returns
+  -------
+  dict
+      A mapping of name to its first definition line.
+  """
+  defs = {}
+  for node in tree.body:
+    if isinstance(
+        node, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)
+    ):
+      defs.setdefault(node.name, node.lineno)
+    elif isinstance(node, ast.Assign):
+      for target in node.targets:
+        if isinstance(target, ast.Name):
+          defs.setdefault(target.id, node.lineno)
+    elif isinstance(node, ast.AnnAssign):
+      if isinstance(node.target, ast.Name) and node.value is not None:
+        defs.setdefault(node.target.id, node.lineno)
+  return defs