markwork publishes your source as your documentation. The page for a file is that file: rendered verbatim, syntax-highlighted, and with every name turned into a link to wherever it is defined. It replaces autodoc, not Sphinx.
Stop documenting your code. Start publishing it.
- Installation
- Point It at a Repo
- You Already Wrote the Docs
- Click a Name, Land on the Definition
- Every Page Ends With Its Tests
- Quickstart
- Themes
- Contributing
- License
Install with pip:
pip install markworkThis 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.
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:
markwork path/to/repo --openThat 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:
markwork . -o public/ # build the current repo into ./publicmarkwork 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.
Here is a function. It is documented. You have written a hundred like it:
def fib(n: int) -> int:
"""Return the nth Fibonacci number.
Parameters
----------
n : int
Position in the sequence, counting from zero.
Returns
-------
int
The nth Fibonacci number.
Examples
--------
>>> fib(10)
55
"""
a, b = 0, 1
for _ in range(n):
a, b = b, a + b
return a
class IsEven(metaclass=type('_', (), {'__call__': lambda *a: not a[1] % 2})):
"""
Parity test of integers.
Parameters
----------
n : int
The integer to test.
Returns
-------
bool
True if 'n' is even, False otherwise.
Examples
--------
>>> IsEven(4)
True
>>> IsEven(7)
False
"""Then the ceremony starts. A .rst stub. An automodule directive. A
docstring style your theme half-renders. A [source] link that ejects the
reader into a separate viewer to see the four lines that actually matter.
Wouldn't it be easier if you wrote that docstring and were just done?
Now you are. Add one line to conf.py:
extensions = ["markwork"]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.
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:
widget.py click Point → geometry.py:14 (the def, highlighted)
geometry.py click hypot → docs.python.org/3/library/math.html
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, 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.
Scroll to the bottom of any symbol's page and the tests that exercise it 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()
Usage in testing
────────────────
tests/test_sequences.py: 12, 19, 27
Click 19 and you land on that line of the test. Per function, you can
see exactly what is covering it. You did write tests, right?
A complete src/-layout project, zero to rendered docs in about a minute.
acme/
├─ src/acme/__init__.py # re-exports your public names, sets __all__
├─ src/acme/widget.py
├─ tests/test_widget.py
└─ docs/
├─ conf.py # extensions = ["markwork"]
└─ index.rst
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. A re-export is followed however far it goes, through
subpackages, aliases and star imports, to the file that really defines
it:
# src/acme/__init__.py
from .widget import Widget
__all__ = ["Widget"]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/:
acme
====
.. include:: _source/_packages.txtBuild it:
pip install markwork
sphinx-build -b html docs docs/_build/htmlOpen docs/_build/html/index.html. One page per source file, every name a
link, the test suite mirrored alongside.
The defaults assume a single package under src/ and a tests/ directory
beside it; the project root is the parent of the folder holding conf.py.
Override when needed:
markwork_package = "acme" # auto-detected when src/ holds one package
markwork_src_root = "src" # source root, relative to the project
markwork_tests_root = "tests" # test root, relative to the projectEach 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:
html_copy_source = False
html_show_sourcelink = FalseFlat layout, with the package at the project root instead of under src/?
Point the source root at the root and name the package explicitly:
markwork_src_root = "."
markwork_package = "acme"Requires Python 3.12 or newer.
markwork is theme-independent and works with any Sphinx theme: furo,
sphinx_rtd_theme, the PyData theme, the built-in alabaster, or your own.
The rendered source is a stock Pygments block, so its syntax colours come
from the active theme's own Pygments style, and the bundled stylesheet
uses inherited and fixed colours so the go-to-definition underlines and
the line-jump highlight read on a light or a dark theme alike.
These docs are built with furo as a preference, not a requirement. To
preview under a different installed theme, set MARKWORK_THEME:
MARKWORK_THEME=alabaster sphinx-build -b html docs docs/_build/htmlContributions are welcome. Open an issue or a pull request at github.com/AsgerJon/markwork.
markwork is released under the Apache License 2.0 (Apache-2.0). See LICENSE for the full text.