markwork 0.1.1rc0__tar.gz → 0.1.2.dev0__tar.gz

{markwork-0.1.1rc0 → markwork-0.1.2.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: markwork
-Version: 0.1.1rc0
+Version: 0.1.2.dev0
 Summary: Sphinx docs without autodoc: your source, made click-through.
 Author-email: Asger Jon Vistisen <asgerjon2@gmail.com>
 License-Expression: Apache-2.0
@@ -13,25 +13,25 @@ Classifier: Framework :: Sphinx :: Extension
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Topic :: Documentation :: Sphinx
 Classifier: Topic :: Software Development :: Documentation
-Requires-Python: >=3.10
+Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: sphinx>=7
 Requires-Dist: pygments
+Requires-Dist: furo
 Dynamic: license-file
 
 [![PyPI version](https://badge.fury.io/py/markwork.svg)](https://pypi.org/project/markwork/)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Framework: Sphinx](https://img.shields.io/badge/Sphinx-extension-1A5276.svg)](https://www.sphinx-doc.org/)
 
-# markwork v0.1.0 (alpha)
+# markwork v0.1.2-dev0 (development build)
 
 **markwork** publishes your source as your documentation. The page for a
 file *is* that file: rendered verbatim, syntax-highlighted, and with every
@@ -43,6 +43,7 @@ Stop documenting your code. Start publishing it.
 # Table of Contents
 
 - [Installation](#installation)
+- [Point It at a Repo](#point-it-at-a-repo)
 - [You Already Wrote the Docs](#you-already-wrote-the-docs)
 - [Click a Name, Land on the Definition](#click-a-name-land-on-the-definition)
 - [Every Page Ends With Its Tests](#every-page-ends-with-its-tests)
@@ -59,8 +60,46 @@ Install with pip:
 pip install markwork
 ```
 
-This pulls in Sphinx and Pygments. markwork rides on Sphinx for the HTML
-shell, search, theme, and hosting. What it replaces is autodoc.
+This pulls in Sphinx, Pygments and the furo theme. markwork rides on
+Sphinx for the HTML shell, search, theme, and hosting. What it replaces is
+autodoc.
+
+# Point It at a Repo
+
+Want to see it before wiring anything up? Point markwork at a repository
+and it renders the whole thing, with no `conf.py`, no `index.rst` and
+nothing scaffolded into the project:
+
+```bash
+markwork path/to/repo --open
+```
+
+That generates a throwaway Sphinx config in a temporary directory, reads
+the project's source in place, builds the click-through HTML, and opens it
+in your browser. The repository is left untouched; only the rendered HTML
+is written, to a temporary directory by default or wherever `-o` points:
+
+```bash
+markwork . -o public/        # build the current repo into ./public
+```
+
+markwork auto-detects the layout from what your project already declares.
+The source root and package come from your build configuration (setuptools
+`packages.find.where` / `package-dir` in `pyproject.toml`, with the
+distribution name picking the package when several qualify), falling back
+to `src/` (or the repo root) and the lone package it finds. The tests are
+expected in `tests/`. markwork does not go looking for them, so a project
+that keeps them elsewhere says where with `--tests`. It prints what it
+resolved, and an ambiguous package stops the build with a clear message
+rather than guessing. Override any of it with `--src`,
+`--tests`, `--package` or `--theme` (`markwork --help` lists them; the
+theme is furo when installed, alabaster otherwise). Sphinx writes the
+pages with one worker per CPU; `-j 1` builds serially. The same build
+runs as `python -m markwork`.
+
+This zero-config command is for previews and one-off renders. To **host**
+the docs (for example on Read the Docs), commit a `docs/conf.py` with the
+one-line extension instead; see [Quickstart](#quickstart).
 
 # You Already Wrote the Docs
 
@@ -126,7 +165,7 @@ Now you are. Add one line to `conf.py`:
 extensions = ["markwork"]
 ```
 
-markwork publishes the function — docstring, signature, body, all of it —
+markwork publishes the function (docstring, signature, body, all of it)
 exactly as you wrote it. The page is the source. You already finished the
 documentation; you just did not know it yet.
 
@@ -134,7 +173,7 @@ documentation; you just did not know it yet.
 
 markwork reads your syntax tree, so every name on the page is wired to
 where it comes from. You do not read the docs by scrolling. You read them
-the way you read code — by following definitions:
+the way you read code, by following definitions:
 
 ```
 widget.py     click Point  →  geometry.py:14   (the def, highlighted)
@@ -143,15 +182,18 @@ sequences.py  click fib    →  sequences.py:30  (back to its own def)
 ```
 
 Project symbols and same-file names jump inside your docs, at the exact
-line. Standard-library members and builtins jump to the official Python
-documentation. A name shadowed by a local binding stays unlinked, so a
-link never sends you somewhere wrong.
+line, and so does the `Thing` in `pkg.mod.Thing`. Standard-library members
+and builtins jump to the official Python documentation. Names are resolved
+by Python's own scoping rules: a parameter, a method or an `except ... as`
+name shadows only the scope it lives in. Anything markwork cannot pin down
+for certain, such as a name a star import may have replaced or one bound
+two ways, stays unlinked, so a link never sends you somewhere wrong.
 
 # Every Page Ends With Its Tests
 
 Scroll to the bottom of any symbol's page and the tests that exercise it
-are waiting there — listed for you, no digging, file and line, each line a
-link straight to the assertion:
+are waiting there. They are listed for you by file and line, with no
+digging, and each line is a link straight to the assertion:
 
 ```
 fib()
@@ -181,7 +223,9 @@ acme/
 markwork follows your **public API**: every name in the package's `__all__`
 becomes a page, a re-exported symbol pulls in its defining file, and the
 `tests/` tree is mirrored for you. So the package's `__init__.py` is your
-table of contents:
+table of contents. A re-export is followed however far it goes, through
+subpackages, aliases and star imports, to the file that really defines
+it:
 
 ```python
 # src/acme/__init__.py
@@ -190,8 +234,14 @@ from .widget import Widget
 __all__ = ["Widget"]
 ```
 
-`docs/index.rst` needs a single include — markwork writes the tree into
-`_source/`:
+No `__all__`? Then the public names are the ones without a leading
+underscore: whatever `__init__.py` defines or imports, then its
+submodules and subpackages. A name in `__all__` that leads nowhere is a
+build warning, never a silently missing page; silence those with
+`suppress_warnings = ["markwork"]` if you must.
+
+`docs/index.rst` needs a single include, since markwork writes the tree
+into `_source/`:
 
 ```rst
 acme
@@ -203,7 +253,7 @@ acme
 Build it:
 
 ```bash
-pip install markwork furo
+pip install markwork
 sphinx-build -b html docs docs/_build/html
 ```
 
@@ -220,6 +270,19 @@ markwork_src_root = "src"      # source root, relative to the project
 markwork_tests_root = "tests"  # test root, relative to the project
 ```
 
+Each page's sidebar holds the top level and the branch the page is on,
+not the whole site: with a page per source file, a full tree on every
+page grows the site with the square of its size (it was two thirds of
+worktoy's 61 MB). Set `markwork_collapse_navigation = False` to keep your
+theme's own choice. Since each page's rST is a generated wrapper around a
+source file, these two lines are worth adding too; the `markwork` command
+sets them for you:
+
+```python
+html_copy_source = False
+html_show_sourcelink = False
+```
+
 Flat layout, with the package at the project root instead of under `src/`?
 Point the source root at the root and name the package explicitly:
 
@@ -228,7 +291,7 @@ markwork_src_root = "."
 markwork_package = "acme"
 ```
 
-Requires Python 3.10 or newer.
+Requires Python 3.12 or newer.
 
 # Themes
 

{markwork-0.1.1rc0 → markwork-0.1.2.dev0}/README.md

@@ -2,7 +2,7 @@
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Framework: Sphinx](https://img.shields.io/badge/Sphinx-extension-1A5276.svg)](https://www.sphinx-doc.org/)
 
-# markwork v0.1.0 (alpha)
+# markwork v0.1.2-dev0 (development build)
 
 **markwork** publishes your source as your documentation. The page for a
 file *is* that file: rendered verbatim, syntax-highlighted, and with every
@@ -14,6 +14,7 @@ Stop documenting your code. Start publishing it.
 # Table of Contents
 
 - [Installation](#installation)
+- [Point It at a Repo](#point-it-at-a-repo)
 - [You Already Wrote the Docs](#you-already-wrote-the-docs)
 - [Click a Name, Land on the Definition](#click-a-name-land-on-the-definition)
 - [Every Page Ends With Its Tests](#every-page-ends-with-its-tests)
@@ -30,8 +31,46 @@ Install with pip:
 pip install markwork
 ```
 
-This pulls in Sphinx and Pygments. markwork rides on Sphinx for the HTML
-shell, search, theme, and hosting. What it replaces is autodoc.
+This pulls in Sphinx, Pygments and the furo theme. markwork rides on
+Sphinx for the HTML shell, search, theme, and hosting. What it replaces is
+autodoc.
+
+# Point It at a Repo
+
+Want to see it before wiring anything up? Point markwork at a repository
+and it renders the whole thing, with no `conf.py`, no `index.rst` and
+nothing scaffolded into the project:
+
+```bash
+markwork path/to/repo --open
+```
+
+That generates a throwaway Sphinx config in a temporary directory, reads
+the project's source in place, builds the click-through HTML, and opens it
+in your browser. The repository is left untouched; only the rendered HTML
+is written, to a temporary directory by default or wherever `-o` points:
+
+```bash
+markwork . -o public/        # build the current repo into ./public
+```
+
+markwork auto-detects the layout from what your project already declares.
+The source root and package come from your build configuration (setuptools
+`packages.find.where` / `package-dir` in `pyproject.toml`, with the
+distribution name picking the package when several qualify), falling back
+to `src/` (or the repo root) and the lone package it finds. The tests are
+expected in `tests/`. markwork does not go looking for them, so a project
+that keeps them elsewhere says where with `--tests`. It prints what it
+resolved, and an ambiguous package stops the build with a clear message
+rather than guessing. Override any of it with `--src`,
+`--tests`, `--package` or `--theme` (`markwork --help` lists them; the
+theme is furo when installed, alabaster otherwise). Sphinx writes the
+pages with one worker per CPU; `-j 1` builds serially. The same build
+runs as `python -m markwork`.
+
+This zero-config command is for previews and one-off renders. To **host**
+the docs (for example on Read the Docs), commit a `docs/conf.py` with the
+one-line extension instead; see [Quickstart](#quickstart).
 
 # You Already Wrote the Docs
 
@@ -97,7 +136,7 @@ Now you are. Add one line to `conf.py`:
 extensions = ["markwork"]
 ```
 
-markwork publishes the function — docstring, signature, body, all of it —
+markwork publishes the function (docstring, signature, body, all of it)
 exactly as you wrote it. The page is the source. You already finished the
 documentation; you just did not know it yet.
 
@@ -105,7 +144,7 @@ documentation; you just did not know it yet.
 
 markwork reads your syntax tree, so every name on the page is wired to
 where it comes from. You do not read the docs by scrolling. You read them
-the way you read code — by following definitions:
+the way you read code, by following definitions:
 
 ```
 widget.py     click Point  →  geometry.py:14   (the def, highlighted)
@@ -114,15 +153,18 @@ sequences.py  click fib    →  sequences.py:30  (back to its own def)
 ```
 
 Project symbols and same-file names jump inside your docs, at the exact
-line. Standard-library members and builtins jump to the official Python
-documentation. A name shadowed by a local binding stays unlinked, so a
-link never sends you somewhere wrong.
+line, and so does the `Thing` in `pkg.mod.Thing`. Standard-library members
+and builtins jump to the official Python documentation. Names are resolved
+by Python's own scoping rules: a parameter, a method or an `except ... as`
+name shadows only the scope it lives in. Anything markwork cannot pin down
+for certain, such as a name a star import may have replaced or one bound
+two ways, stays unlinked, so a link never sends you somewhere wrong.
 
 # Every Page Ends With Its Tests
 
 Scroll to the bottom of any symbol's page and the tests that exercise it
-are waiting there — listed for you, no digging, file and line, each line a
-link straight to the assertion:
+are waiting there. They are listed for you by file and line, with no
+digging, and each line is a link straight to the assertion:
 
 ```
 fib()
@@ -152,7 +194,9 @@ acme/
 markwork follows your **public API**: every name in the package's `__all__`
 becomes a page, a re-exported symbol pulls in its defining file, and the
 `tests/` tree is mirrored for you. So the package's `__init__.py` is your
-table of contents:
+table of contents. A re-export is followed however far it goes, through
+subpackages, aliases and star imports, to the file that really defines
+it:
 
 ```python
 # src/acme/__init__.py
@@ -161,8 +205,14 @@ from .widget import Widget
 __all__ = ["Widget"]
 ```
 
-`docs/index.rst` needs a single include — markwork writes the tree into
-`_source/`:
+No `__all__`? Then the public names are the ones without a leading
+underscore: whatever `__init__.py` defines or imports, then its
+submodules and subpackages. A name in `__all__` that leads nowhere is a
+build warning, never a silently missing page; silence those with
+`suppress_warnings = ["markwork"]` if you must.
+
+`docs/index.rst` needs a single include, since markwork writes the tree
+into `_source/`:
 
 ```rst
 acme
@@ -174,7 +224,7 @@ acme
 Build it:
 
 ```bash
-pip install markwork furo
+pip install markwork
 sphinx-build -b html docs docs/_build/html
 ```
 
@@ -191,6 +241,19 @@ markwork_src_root = "src"      # source root, relative to the project
 markwork_tests_root = "tests"  # test root, relative to the project
 ```
 
+Each page's sidebar holds the top level and the branch the page is on,
+not the whole site: with a page per source file, a full tree on every
+page grows the site with the square of its size (it was two thirds of
+worktoy's 61 MB). Set `markwork_collapse_navigation = False` to keep your
+theme's own choice. Since each page's rST is a generated wrapper around a
+source file, these two lines are worth adding too; the `markwork` command
+sets them for you:
+
+```python
+html_copy_source = False
+html_show_sourcelink = False
+```
+
 Flat layout, with the package at the project root instead of under `src/`?
 Point the source root at the root and name the package explicitly:
 
@@ -199,7 +262,7 @@ markwork_src_root = "."
 markwork_package = "acme"
 ```
 
-Requires Python 3.10 or newer.
+Requires Python 3.12 or newer.
 
 # Themes
 

{markwork-0.1.1rc0 → markwork-0.1.2.dev0}/pyproject.toml

@@ -7,10 +7,10 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "markwork"
-version = "0.1.1-rc0"
+version = "0.1.2-dev0"
 description = "Sphinx docs without autodoc: your source, made click-through."
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.12"
 license = "Apache-2.0"
 license-files = ["LICENSE"]
 authors = [{ name = "Asger Jon Vistisen", email = "asgerjon2@gmail.com" }]
@@ -18,6 +18,7 @@ keywords = ["sphinx", "documentation", "autodoc", "pygments", "source"]
 dependencies = [
   "sphinx>=7",
   "pygments",
+  "furo",
 ]
 classifiers = [
   "Development Status :: 3 - Alpha",
@@ -25,11 +26,10 @@ classifiers = [
   "Intended Audience :: Developers",
   "Operating System :: OS Independent",
   "Programming Language :: Python :: 3",
-  "Programming Language :: Python :: 3.10",
-  "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
   "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.15",
   "Topic :: Documentation :: Sphinx",
   "Topic :: Software Development :: Documentation",
 ]
@@ -39,12 +39,20 @@ Homepage = "https://github.com/AsgerJon/markwork"
 Repository = "https://github.com/AsgerJon/markwork"
 Issues = "https://github.com/AsgerJon/markwork/issues"
 
+[project.scripts]
+markwork = "markwork._cli:main"
+
 [tool.setuptools.packages.find]
 where = ["src"]
 
 [tool.setuptools.package-data]
 markwork = ["etc/*.css"]
 
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+#  The suite runs from a checkout without installing the package first.
+pythonpath = ["src"]
+
 [tool.coverage.run]
 branch = true
 source = ["markwork", "tests"]

{markwork-0.1.1rc0 → markwork-0.1.2.dev0}/src/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-rc0"
+__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-0.1.2.dev0/src/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())