Repository navigation
Documentation? #30
Description
Activity
I looked into this and built a throwaway Sphinx project against the real package to check the assumptions. Short version of what I found and what I propose.
Two obstacles to "just run autodoc"
1. pytest fixtures are not functions.
>>> type(pytest_plone.fixtures.base.portal) <class '_pytest.fixtures.FixtureFunctionDefinition'>
sphinx.ext.autodocintrospects live objects, soautofunctionsees no function here and produces nothing useful.2. Our docstrings are Markdown. They contain
```pythonfences, butsphinx.ext.autodocfeeds docstrings to the reStructuredText parser. MyST-parser's own docs state that autodoc is not compatible with MyST docstrings.Resolution:
sphinx-autodoc2sphinx-autodoc2does static AST analysis rather than runtime introspection, which dissolves both problems: it reads the function as written in the source, so the decorator is irrelevant, andautodoc2_docstring_parser_regexeslets it parse docstrings as MyST.Verified working (build succeeded, 0 warnings, signatures with resolved annotations, examples as highlighted code blocks):
extensions = ["myst_parser", "autodoc2", "sphinx_design", "sphinx_copybutton"] autodoc2_packages = [{"path": "../src/pytest_plone", "auto_mode": False}] autodoc2_render_plugin = "myst" autodoc2_docstring_parser_regexes = [(r".*", "myst")] myst_enable_extensions = ["colon_fence", "deflist", "attrs_inline", "fieldlist"] html_theme = "plone_sphinx_theme"
Two gotchas that cost me time:
autodoc2_packages[…]["path"]must be relative toconf.py, andfieldlistis required or reST field syntax (:param x:, used infixtures_factory) renders as literal text.The docs build needs no Plone
Because autodoc2 is static, it never imports the package. My spike environment had zero Plone/Zope packages installed — not even
pytest— and still produced fully resolved signatures likeportal(integration: plone.testing.layer.Layer) → PloneSite.So the docs job needs only Sphinx + theme + autodoc2. Seconds, not the ~3 minutes a Plone install costs. It also removes what would have been the strongest argument against Read the Docs ("RTD would have to install all of Plone" — it would not).
Prerequisite: the docstrings were wrong
If the docstrings become the single source of truth, every error in them gets published verbatim. So I audited them first. Four were genuinely broken —
setup_toolwas not even valid Python,get_ftiassertedisinstance(fti, IDexterityFTI)(alwaysFalse; zope interfaces needprovidedBy),get_vocabularyreferenced an undefined name, andhttp_request's example requested pytest's builtinrequestfixture. A further 14 usedselfin top-level test functions, which fails withfixture 'self' not foundon copy-paste.Fixed in #55, with a static guard (#54) so they cannot come back.
Proposed shape
Diataxis, all four quadrants, two levels deep:
docs/ ├── index.md ├── tutorials/first-test.md ├── how-to/ set-up-pytest-plone, test-addon-install, │ speed-up-the-test-suite, test-a-rest-api, │ develop-the-plugin ├── explanation/ why-pytest-for-plone, │ layers-scopes-and-isolation └── reference/ fixtures, markers, apireference/fixtures.mdis a hybrid: curated grouping and an overview table by hand (autodoc cannot produce navigation), with one{autodoc2-object}per fixture pulling the docstring in. That follows the Plone docs rule that auto-generated docs alone are not sufficient — they need curating and organizing.The README then slims to a pointer (~80 lines: badges, install, a short quickstart, link to the docs), which is the double-maintenance problem you raised.
Sequencing
- Phase 1 —
docs/scaffold +conf.py, the full reference, the setup how-to, both explanation pages,make docswith-W, CI job. - Phase 2 — tutorial, remaining how-tos, and then slim the README (gutting it before the docs are complete would leave users worse off than today).
- Deferred to their own issues — hosting (RTD vs. submodule), and Vale (bringing 620 lines of prose to Microsoft style is a project in itself and would swamp the PR).
Happy to adjust the split. The one open question I would like your take on is hosting — given that the build needs no Plone, RTD looks a lot more attractive than it did.
- Phase 1 —
- added a commit that references this issue
on Jul 13, 2026 - added a commit that references this issue
on Jul 24, 2026
Should this package have its own Sphinx documentation? It's become large enough that autodoc of its API—thanks to new docstrings—might be useful, and then you wouldn't have to update the README with usage. We could either host it separately at RTD or pull it in as a submodule.