prodockit 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (58) hide show
  1. prodockit-0.1.0/.github/CODEOWNERS +8 -0
  2. prodockit-0.1.0/.github/workflows/ci.yml +33 -0
  3. prodockit-0.1.0/.github/workflows/docs.yml +32 -0
  4. prodockit-0.1.0/.github/workflows/publish.yml +33 -0
  5. prodockit-0.1.0/.gitignore +17 -0
  6. prodockit-0.1.0/LICENSE +21 -0
  7. prodockit-0.1.0/PKG-INFO +148 -0
  8. prodockit-0.1.0/PLAN-16.md +143 -0
  9. prodockit-0.1.0/README.md +118 -0
  10. prodockit-0.1.0/docs/about/changelog.md +235 -0
  11. prodockit-0.1.0/docs/about/license.md +5 -0
  12. prodockit-0.1.0/docs/extensions/citations.md +187 -0
  13. prodockit-0.1.0/docs/extensions/glossary.md +224 -0
  14. prodockit-0.1.0/docs/extensions/headings.md +229 -0
  15. prodockit-0.1.0/docs/extensions/refs.md +172 -0
  16. prodockit-0.1.0/docs/index.md +92 -0
  17. prodockit-0.1.0/docs/installation.md +69 -0
  18. prodockit-0.1.0/docs/macros.md +81 -0
  19. prodockit-0.1.0/docs/pdf.md +565 -0
  20. prodockit-0.1.0/pyproject.toml +77 -0
  21. prodockit-0.1.0/src/prodockit/__init__.py +39 -0
  22. prodockit-0.1.0/src/prodockit/_zensical.py +260 -0
  23. prodockit-0.1.0/src/prodockit/citations.py +207 -0
  24. prodockit-0.1.0/src/prodockit/glossary.py +206 -0
  25. prodockit-0.1.0/src/prodockit/headings.py +223 -0
  26. prodockit-0.1.0/src/prodockit/pdf/__init__.py +38 -0
  27. prodockit-0.1.0/src/prodockit/pdf/build.py +261 -0
  28. prodockit-0.1.0/src/prodockit/pdf/cli.py +52 -0
  29. prodockit-0.1.0/src/prodockit/pdf/config.py +189 -0
  30. prodockit-0.1.0/src/prodockit/pdf/css.py +626 -0
  31. prodockit-0.1.0/src/prodockit/pdf/html.py +499 -0
  32. prodockit-0.1.0/src/prodockit/pdf/icons.py +171 -0
  33. prodockit-0.1.0/src/prodockit/pdf/lua.py +256 -0
  34. prodockit-0.1.0/src/prodockit/pdf/mermaid.py +97 -0
  35. prodockit-0.1.0/src/prodockit/py.typed +0 -0
  36. prodockit-0.1.0/src/prodockit/refs.py +158 -0
  37. prodockit-0.1.0/src/prodockit/settings.py +66 -0
  38. prodockit-0.1.0/src/prodockit/util.py +272 -0
  39. prodockit-0.1.0/src/prodockit/wordcount.py +38 -0
  40. prodockit-0.1.0/src/prodockit/zensical_macros.py +251 -0
  41. prodockit-0.1.0/tests/test_citations.py +110 -0
  42. prodockit-0.1.0/tests/test_glossary.py +108 -0
  43. prodockit-0.1.0/tests/test_headings.py +137 -0
  44. prodockit-0.1.0/tests/test_pdf_build.py +206 -0
  45. prodockit-0.1.0/tests/test_pdf_cli.py +89 -0
  46. prodockit-0.1.0/tests/test_pdf_config.py +122 -0
  47. prodockit-0.1.0/tests/test_pdf_css.py +85 -0
  48. prodockit-0.1.0/tests/test_pdf_html.py +364 -0
  49. prodockit-0.1.0/tests/test_pdf_icons.py +62 -0
  50. prodockit-0.1.0/tests/test_pdf_lua.py +36 -0
  51. prodockit-0.1.0/tests/test_pdf_mermaid.py +59 -0
  52. prodockit-0.1.0/tests/test_refs.py +102 -0
  53. prodockit-0.1.0/tests/test_settings.py +50 -0
  54. prodockit-0.1.0/tests/test_wordcount.py +31 -0
  55. prodockit-0.1.0/tests/test_zensical.py +125 -0
  56. prodockit-0.1.0/tests/test_zensical_integration.py +395 -0
  57. prodockit-0.1.0/tests/test_zensical_macros.py +121 -0
  58. prodockit-0.1.0/zensical.toml +72 -0
@@ -0,0 +1,8 @@
1
+ # Copyright (c) 2026 Mark Buckwell and contributors
2
+ # SPDX-License-Identifier: MIT
3
+
4
+ # Every pull request needs a review from one of the owners listed below,
5
+ # regardless of which files it touches. Combine with a branch protection
6
+ # rule on main ("Require a pull request before merging" + "Require review
7
+ # from Code Owners") for this to actually block merging without approval.
8
+ * @buckwem
@@ -0,0 +1,33 @@
1
+ # Copyright (c) 2026 Mark Buckwell and contributors
2
+ # SPDX-License-Identifier: MIT
3
+
4
+ name: CI
5
+ on:
6
+ push:
7
+ branches: [main]
8
+ pull_request:
9
+ jobs:
10
+ test:
11
+ runs-on: ubuntu-latest
12
+ strategy:
13
+ matrix:
14
+ python-version: ["3.10", "3.11", "3.12", "3.13"]
15
+ steps:
16
+ - uses: actions/checkout@v5
17
+ - uses: actions/setup-python@v5
18
+ with:
19
+ python-version: ${{ matrix.python-version }}
20
+ - run: pip install -e ".[dev]"
21
+ - run: ruff check .
22
+ - run: mypy src
23
+ - run: pytest --cov=prodockit
24
+
25
+ docs:
26
+ runs-on: ubuntu-latest
27
+ steps:
28
+ - uses: actions/checkout@v5
29
+ - uses: actions/setup-python@v5
30
+ with:
31
+ python-version: "3.x"
32
+ - run: pip install -e .
33
+ - run: zensical build --clean --strict
@@ -0,0 +1,32 @@
1
+ # Copyright (c) 2026 Mark Buckwell and contributors
2
+ # SPDX-License-Identifier: MIT
3
+
4
+ name: Documentation
5
+ on:
6
+ push:
7
+ branches:
8
+ - main
9
+ workflow_dispatch:
10
+ permissions:
11
+ contents: read
12
+ pages: write
13
+ id-token: write
14
+ jobs:
15
+ deploy:
16
+ environment:
17
+ name: github-pages
18
+ url: ${{ steps.deployment.outputs.page_url }}
19
+ runs-on: ubuntu-latest
20
+ steps:
21
+ - uses: actions/configure-pages@v5
22
+ - uses: actions/checkout@v5
23
+ - uses: actions/setup-python@v5
24
+ with:
25
+ python-version: "3.x"
26
+ - run: pip install -e .
27
+ - run: zensical build --clean --strict
28
+ - uses: actions/upload-pages-artifact@v4
29
+ with:
30
+ path: site
31
+ - uses: actions/deploy-pages@v4
32
+ id: deployment
@@ -0,0 +1,33 @@
1
+ # Copyright (c) 2026 Mark Buckwell and contributors
2
+ # SPDX-License-Identifier: MIT
3
+
4
+ name: Publish to PyPI
5
+ on:
6
+ release:
7
+ types: [published]
8
+ jobs:
9
+ build:
10
+ runs-on: ubuntu-latest
11
+ steps:
12
+ - uses: actions/checkout@v5
13
+ - uses: actions/setup-python@v5
14
+ with:
15
+ python-version: "3.x"
16
+ - run: pip install build
17
+ - run: python -m build
18
+ - uses: actions/upload-artifact@v4
19
+ with:
20
+ name: dist
21
+ path: dist/
22
+ publish:
23
+ needs: build
24
+ runs-on: ubuntu-latest
25
+ environment: pypi
26
+ permissions:
27
+ id-token: write # required for PyPI trusted publishing
28
+ steps:
29
+ - uses: actions/download-artifact@v4
30
+ with:
31
+ name: dist
32
+ path: dist/
33
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,17 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ *.egg-info/
4
+ .eggs/
5
+ build/
6
+ dist/
7
+ .venv/
8
+ venv/
9
+ .pytest_cache/
10
+ .mypy_cache/
11
+ .ruff_cache/
12
+ .coverage
13
+ htmlcov/
14
+ .DS_Store
15
+ site/
16
+ docs/site_documentation.pdf
17
+ docs/.prodockit-pdf-mermaid/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Mark Buckwell and contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,148 @@
1
+ Metadata-Version: 2.4
2
+ Name: prodockit
3
+ Version: 0.1.0
4
+ Summary: A family of extensions for Zensical needed for professional and academic documentation: section cross-references, bibliography/citation handling, a glossary, a Pandoc/WeasyPrint PDF pipeline, and Jinja macros for word counts and reference-style spacing
5
+ Project-URL: Homepage, https://github.com/buckwem/prodockit-extensions
6
+ Project-URL: Documentation, https://buckwem.github.io/prodockit-extensions/
7
+ Project-URL: Issues, https://github.com/buckwem/prodockit-extensions/issues
8
+ Author: Mark Buckwell
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: extension,markdown,pandoc,pdf,python-markdown,zensical
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Topic :: Text Processing :: Markup :: Markdown
17
+ Requires-Python: >=3.10
18
+ Requires-Dist: beautifulsoup4>=4.12
19
+ Requires-Dist: click>=8.0
20
+ Requires-Dist: markdown>=3.4
21
+ Requires-Dist: zensical
22
+ Provides-Extra: dev
23
+ Requires-Dist: mypy; extra == 'dev'
24
+ Requires-Dist: pytest; extra == 'dev'
25
+ Requires-Dist: pytest-cov; extra == 'dev'
26
+ Requires-Dist: ruff; extra == 'dev'
27
+ Requires-Dist: types-beautifulsoup4; extra == 'dev'
28
+ Requires-Dist: types-markdown; extra == 'dev'
29
+ Description-Content-Type: text/markdown
30
+
31
+ # prodockit
32
+
33
+ A family of extensions for [Zensical](https://zensical.org/) needed for
34
+ professional and academic documentation: section cross-references,
35
+ bibliography/citation handling, a glossary, and a Pandoc/WeasyPrint PDF
36
+ pipeline for the downloadable, submittable document these usually need
37
+ alongside the website itself. Each piece is independent, so you only pay
38
+ for what you use.
39
+
40
+ Most of prodockit is [Python-Markdown](https://python-markdown.github.io/)
41
+ extensions, in the spirit of [pymdown-extensions](https://facelessuser.github.io/pymdown-extensions/) -
42
+ configure one the same way as any other Zensical/`pymdownx` Markdown
43
+ extension, via `zensical.toml`. `prodockit.pdf` is a command-line tool
44
+ instead (`prodockit pdf`), since a PDF build pipeline isn't a Markdown syntax
45
+ extension - it reads the same `zensical.toml` too.
46
+
47
+ > **Status:** early, but functional - `prodockit.headings`, `prodockit.refs`,
48
+ > `prodockit.citations`, `prodockit.glossary`, `prodockit.pdf`, and
49
+ > `prodockit.zensical_macros` are implemented and tested.
50
+
51
+ **[Full documentation](https://buckwem.github.io/prodockit-extensions/)**
52
+
53
+ ## Installation
54
+
55
+ ```bash
56
+ pip install prodockit
57
+ ```
58
+
59
+ ## Extensions
60
+
61
+ | Extension | Description |
62
+ |---|---|
63
+ | [`prodockit.headings`](https://buckwem.github.io/prodockit-extensions/extensions/headings/) | Gives every heading an id and a hierarchical section number ("1", "1.1", "1.2", "2", ...). |
64
+ | [`prodockit.refs`](https://buckwem.github.io/prodockit-extensions/extensions/refs/) | `\ref{id}` section cross-references, resolving to the target's current number - similar in spirit to LaTeX's `\ref`. |
65
+ | [`prodockit.citations`](https://buckwem.github.io/prodockit-extensions/extensions/citations/) | Define a source once, cite it by key anywhere with `\cite{id}` - auto-generates the bracketed, linked citation text. |
66
+ | [`prodockit.glossary`](https://buckwem.github.io/prodockit-extensions/extensions/glossary/) | Define a term once (an acronym expansion, a glossary entry), insert it by id anywhere with `\gls{id}` - similar in spirit to LaTeX's `glossaries` package. |
67
+
68
+ ```python
69
+ import markdown
70
+
71
+ html = markdown.markdown(
72
+ text,
73
+ extensions=[
74
+ "attr_list", "prodockit.headings", "prodockit.refs", "prodockit.citations", "prodockit.glossary"
75
+ ],
76
+ )
77
+ ```
78
+
79
+ ```md
80
+ # Introduction {: #intro }
81
+
82
+ See \ref{intro} for background.\cite{skou2023} This uses \gls{css}.
83
+
84
+ Skoulikari, A. (2023) *Learning Git*.
85
+ {: #skou2023 data-cite-text="Skoulikari, 2023" }
86
+
87
+ **CSS** - Cascading Style Sheets.
88
+ {: #css data-term="CSS" }
89
+ ```
90
+
91
+ `\ref{intro}` resolves to a link reading `1` - the heading's current
92
+ section number; `\cite{skou2023}` resolves to `[Skoulikari, 2023]`, linked
93
+ to that source; `\gls{css}` resolves to `CSS`, linked to its own
94
+ definition. All three stay correct if content is reordered, since
95
+ resolution happens fresh on every conversion. See the
96
+ [docs](https://buckwem.github.io/prodockit-extensions/) for options, multi-page
97
+ registry sharing, and full syntax details.
98
+
99
+ ## PDF generation
100
+
101
+ [`prodockit.pdf`](https://buckwem.github.io/prodockit-extensions/pdf/) builds a
102
+ standalone PDF from your site, via Pandoc and WeasyPrint (both need to be
103
+ installed separately - see the docs). No Python required - it reads the
104
+ same `zensical.toml` your site already has:
105
+
106
+ ```bash
107
+ prodockit pdf
108
+ ```
109
+
110
+ That's it - run it from your project root and it builds a complete PDF,
111
+ table of contents included, from every page in your `nav`. See the
112
+ [docs](https://buckwem.github.io/prodockit-extensions/pdf/) for the
113
+ `zensical.toml` settings it reads, and for the Python API
114
+ (`build_pdf()`, `prodockit.pdf.html`/`.lua`/`.css`/`.icons`/`.mermaid`) if
115
+ you're scripting your own build pipeline instead.
116
+
117
+ ## Website macros
118
+
119
+ [`prodockit.zensical_macros`](https://buckwem.github.io/prodockit-extensions/macros/)
120
+ provides a site-wide word count, the git-detected repository URL, chapter/
121
+ appendix numbering that continues across pages, and reference/acronym/
122
+ glossary spacing that matches `prodockit.pdf`'s own PDF output - as Jinja
123
+ variables/macros for Zensical's own macros plugin:
124
+
125
+ ```toml
126
+ [project.markdown_extensions.zensical.extensions.macros]
127
+ modules = ["prodockit.zensical_macros"]
128
+ ```
129
+
130
+ See the [docs](https://buckwem.github.io/prodockit-extensions/macros/) for the
131
+ full variable/macro list.
132
+
133
+ ## Development
134
+
135
+ ```bash
136
+ python -m venv .venv
137
+ source .venv/bin/activate
138
+ pip install -e ".[dev]"
139
+ pytest
140
+ ```
141
+
142
+ `zensical` is a core dependency, so `zensical serve` is available as soon as
143
+ `prodockit` is installed - no extra step needed to build the documentation
144
+ locally.
145
+
146
+ ## License
147
+
148
+ MIT - see [LICENSE](LICENSE).
@@ -0,0 +1,143 @@
1
+ # Plan: rename `zendoc` → `prodockit` (zendoc-extensions#16)
2
+
3
+ Not yet implemented - for review/agreement first, per the same
4
+ plan-then-implement pattern used for #11 (the earlier GitHub repo rename).
5
+
6
+ ## What #16 actually asks for
7
+
8
+ > I want to remove the "zen" from the name of the extension. Change
9
+ > extension name to prodockit in prodockit-extensions repo.
10
+
11
+ Two renames, not one:
12
+ 1. The **Python package/import name**: `zendoc` → `prodockit` (this repo's
13
+ own `src/zendoc/*` code, PyPI project name, CLI command, entry points).
14
+ 2. The **GitHub repo name**: `zendoc-extensions` → `prodockit-extensions`
15
+ (this repo already went through one rename this month - `zendoc-extension`
16
+ → `zendoc-extensions`, #11/#15 - so this is a second hop; see risks below).
17
+
18
+ This repo is not the only thing affected - `zendoc-template`
19
+ (github.com/buckwem/zendoc-template) depends on the `zendoc` PyPI package
20
+ directly (imports, `requirements.txt`, `zensical.toml` extension config)
21
+ and has **132 references to "zendoc"** across 20 files that would need
22
+ updating in lockstep. `zendoc-dev-dashboard` does **not** depend on the
23
+ `zendoc` package at all (checked - its dependencies are `zensical`,
24
+ `weasyprint`, etc., unrelated) - it just happens to share the naming
25
+ prefix, so it's out of scope here unless you want full branding
26
+ consistency later.
27
+
28
+ ## Decisions (resolved)
29
+
30
+ 1. **Existing `zendoc` PyPI releases**: remove the `zendoc` project from
31
+ PyPI entirely. Note this is a manual step only you can do (full project
32
+ deletion is a pypi.org web UI action, not available via API/CLI to an
33
+ agent) - and PyPI's policy is that a deleted project's exact name
34
+ generally can't be re-registered by anyone afterwards, so this is a
35
+ one-way door. Sequencing: do this *after* `prodockit` is published and
36
+ `zendoc-template` is cut over (Phase 4), so there's no gap where neither
37
+ package installs.
38
+ 2. **Version numbering for `prodockit`**: reset to `0.1.0`.
39
+ 3. **`zendoc-template` renaming**: out of scope for now (bigger plans
40
+ pending) - Phase 4 below only updates its *dependency* on the package,
41
+ not the template repo's own name/branding.
42
+
43
+ ## PyPI name check
44
+
45
+ `prodockit` is **available** on PyPI (confirmed - no existing project by
46
+ that name), so no squatting conflict to work around.
47
+
48
+ ## Sequencing (each phase is a PR, tested before moving to the next)
49
+
50
+ ### Phase 1 - `zendoc-extensions`: the package rename itself
51
+ - `src/zendoc/` → `src/prodockit/` (directory rename), all internal
52
+ imports (`headings.py`, `refs.py`, `citations.py`, `glossary.py`,
53
+ `settings.py`, `util.py`, `wordcount.py`, `zensical_macros.py`,
54
+ `_zensical.py`, `pdf/__init__.py`, `pdf/build.py`, `pdf/cli.py`,
55
+ `pdf/config.py`, `pdf/css.py`, `pdf/html.py`, `pdf/icons.py`,
56
+ `pdf/lua.py`, `pdf/mermaid.py`) updated from `zendoc.X` to `prodockit.X`.
57
+ - `pyproject.toml`: `name = "zendoc"` → `"prodockit"`; entry points
58
+ (`"zendoc.headings"` etc. → `"prodockit.headings"` etc.); `[project.scripts]
59
+ zendoc = "zendoc.pdf.cli:main"` → `prodockit = "prodockit.pdf.cli:main"`
60
+ (this is a CLI-breaking rename too - anyone running `zendoc` from a
61
+ shell gets `prodockit` instead, worth a changelog line); `packages =
62
+ ["src/zendoc"]` → `["src/prodockit"]`; ruff per-file-ignores paths;
63
+ `[project.urls]` updated to the new repo name/Pages URL (see Phase 3 -
64
+ these can be updated now even before the repo rename actually happens,
65
+ same as #11 did).
66
+ - `tests/*.py` - update every `from zendoc...`/`import zendoc` to
67
+ `prodockit`.
68
+ - `docs/*.md`, `README.md`, this repo's own `zensical.toml` (which
69
+ showcases the extension on its own docs site) - every `zendoc.headings`/
70
+ `zendoc.citations`/`pip install zendoc`/repo-URL reference updated.
71
+ - Verify: full test suite (`pytest`), `zensical build`, docs site builds
72
+ clean.
73
+
74
+ ### Phase 2 - cut a `prodockit` PyPI release
75
+ - `pyproject.toml` version reset to `0.1.0` (per decision #2).
76
+ - One-time manual step **you'll need to do yourself**: register
77
+ `prodockit` as a pending trusted publisher on pypi.org for this repo's
78
+ `publish.yml` workflow (trusted publishing is configured per-project-name
79
+ on PyPI's side and requires your own PyPI login - I can't do this part).
80
+ - Then a normal GitHub Release triggers `publish.yml` as it already does.
81
+
82
+ ### Phase 3 - rename the GitHub repo
83
+ - `zendoc-extensions` → `prodockit-extensions` (Settings → repo name, same
84
+ process as #11's `zendoc-extension` → `zendoc-extensions` rename).
85
+ - **Risk worth flagging**: GitHub redirects old→new repo URLs, but this
86
+ repo already has one redirect hop in place (`zendoc-extension` →
87
+ `zendoc-extensions`); adding a second hop (→ `prodockit-extensions`)
88
+ means anyone following the *original* pre-#11 URL now needs GitHub to
89
+ chain two redirects. GitHub does support this, but it's worth a quick
90
+ manual check afterwards that the original `zendoc-extension` URL still
91
+ lands somewhere sane.
92
+ - GitHub Pages URL moves the same way: `buckwem.github.io/zendoc-extensions/`
93
+ → `buckwem.github.io/prodockit-extensions/` (same pattern as #11 -
94
+ confirmed old URL 404s, new one resolves).
95
+ - Rename the local clone directory to match
96
+ (`~/GitHub/zendoc-extensions` → `~/GitHub/prodockit-extensions`).
97
+
98
+ ### Phase 4 - `zendoc-template`: update the dependent repo
99
+ 132 references across 20 files, roughly:
100
+ - `requirements.txt` - `zendoc>=0.10.0` → `prodockit>=<new version>`.
101
+ - `macros.py` - `from zendoc.zensical_macros import define_env` →
102
+ `from prodockit.zensical_macros import define_env`; update the
103
+ workaround comment (currently references `zendoc.zensical_macros` and
104
+ `zensical/zensical#823`, the issue number stays the same, just the
105
+ module name in the prose changes).
106
+ - `zensical.toml` - `[project.markdown_extensions."zendoc.headings"]` and
107
+ siblings (`refs`, `citations`, `glossary`) → `"prodockit.headings"` etc.
108
+ - `build_pdf.py` - any `zendoc.pdf`/`zendoc.settings`/`zendoc.wordcount`
109
+ references.
110
+ - `docs/starthere/customise.md`, `installtooling.md`, `startediting.md`,
111
+ `testing.md` - prose references, install instructions, doc links
112
+ (`buckwem.github.io/zendoc-extensions/...` → `.../prodockit-extensions/...`).
113
+ - `test/conftest.py`, `test_customisation.py`, `test_captions.py`,
114
+ `test_fences.py`, `test_links.py`, `test_pdf_structure.py`,
115
+ `test_word_count.py`, `test_zensical_basics.py`, `test/run_tests.py` -
116
+ import statements and docstring/comment references.
117
+ - `README.md`, `CONTRIBUTING.md` - prose references.
118
+ - `spike/render-pipeline-92/fix_tabs.py` - this is old spike/scratch code
119
+ from a past migration; worth checking whether it's still referenced by
120
+ anything live or safe to leave/delete rather than update in place.
121
+ - Verify: `pip install -r requirements.txt`, `python build_pdf.py`,
122
+ `zensical build --clean`, full `pytest` suite (157 tests currently) -
123
+ all need to pass against `prodockit` before merging.
124
+
125
+ ### Phase 5 - close out
126
+ - Close #16 (this repo) referencing the merged PRs.
127
+ - Remove the `zendoc` project from PyPI (decision #1 - manual, pypi.org,
128
+ after `prodockit` is live and `zendoc-template` is cut over).
129
+ - Update memory/notes if anything here should persist beyond this
130
+ conversation (e.g. the new repo name, PyPI package name).
131
+
132
+ ## Effort/risk summary
133
+
134
+ This is bigger than #11 (that was a pure find-replace on self-referential
135
+ URLs/prose, ~15 lines across 5 files). This one is a real package rename:
136
+ directory move, import rewrites, entry-point/CLI renames, a PyPI release,
137
+ a second repo rename hop, and a 132-reference cleanup in the dependent
138
+ template repo - each phase independently testable, but the whole thing
139
+ only "works" end to end once `zendoc-template` is pointed at a published
140
+ `prodockit` release, so there's a window where the two repos are
141
+ intentionally out of sync (Phase 1-2 done, Phase 4 not yet) - not a
142
+ problem as long as `zendoc-template`'s `main` isn't touched until Phase 4
143
+ actually lands.
@@ -0,0 +1,118 @@
1
+ # prodockit
2
+
3
+ A family of extensions for [Zensical](https://zensical.org/) needed for
4
+ professional and academic documentation: section cross-references,
5
+ bibliography/citation handling, a glossary, and a Pandoc/WeasyPrint PDF
6
+ pipeline for the downloadable, submittable document these usually need
7
+ alongside the website itself. Each piece is independent, so you only pay
8
+ for what you use.
9
+
10
+ Most of prodockit is [Python-Markdown](https://python-markdown.github.io/)
11
+ extensions, in the spirit of [pymdown-extensions](https://facelessuser.github.io/pymdown-extensions/) -
12
+ configure one the same way as any other Zensical/`pymdownx` Markdown
13
+ extension, via `zensical.toml`. `prodockit.pdf` is a command-line tool
14
+ instead (`prodockit pdf`), since a PDF build pipeline isn't a Markdown syntax
15
+ extension - it reads the same `zensical.toml` too.
16
+
17
+ > **Status:** early, but functional - `prodockit.headings`, `prodockit.refs`,
18
+ > `prodockit.citations`, `prodockit.glossary`, `prodockit.pdf`, and
19
+ > `prodockit.zensical_macros` are implemented and tested.
20
+
21
+ **[Full documentation](https://buckwem.github.io/prodockit-extensions/)**
22
+
23
+ ## Installation
24
+
25
+ ```bash
26
+ pip install prodockit
27
+ ```
28
+
29
+ ## Extensions
30
+
31
+ | Extension | Description |
32
+ |---|---|
33
+ | [`prodockit.headings`](https://buckwem.github.io/prodockit-extensions/extensions/headings/) | Gives every heading an id and a hierarchical section number ("1", "1.1", "1.2", "2", ...). |
34
+ | [`prodockit.refs`](https://buckwem.github.io/prodockit-extensions/extensions/refs/) | `\ref{id}` section cross-references, resolving to the target's current number - similar in spirit to LaTeX's `\ref`. |
35
+ | [`prodockit.citations`](https://buckwem.github.io/prodockit-extensions/extensions/citations/) | Define a source once, cite it by key anywhere with `\cite{id}` - auto-generates the bracketed, linked citation text. |
36
+ | [`prodockit.glossary`](https://buckwem.github.io/prodockit-extensions/extensions/glossary/) | Define a term once (an acronym expansion, a glossary entry), insert it by id anywhere with `\gls{id}` - similar in spirit to LaTeX's `glossaries` package. |
37
+
38
+ ```python
39
+ import markdown
40
+
41
+ html = markdown.markdown(
42
+ text,
43
+ extensions=[
44
+ "attr_list", "prodockit.headings", "prodockit.refs", "prodockit.citations", "prodockit.glossary"
45
+ ],
46
+ )
47
+ ```
48
+
49
+ ```md
50
+ # Introduction {: #intro }
51
+
52
+ See \ref{intro} for background.\cite{skou2023} This uses \gls{css}.
53
+
54
+ Skoulikari, A. (2023) *Learning Git*.
55
+ {: #skou2023 data-cite-text="Skoulikari, 2023" }
56
+
57
+ **CSS** - Cascading Style Sheets.
58
+ {: #css data-term="CSS" }
59
+ ```
60
+
61
+ `\ref{intro}` resolves to a link reading `1` - the heading's current
62
+ section number; `\cite{skou2023}` resolves to `[Skoulikari, 2023]`, linked
63
+ to that source; `\gls{css}` resolves to `CSS`, linked to its own
64
+ definition. All three stay correct if content is reordered, since
65
+ resolution happens fresh on every conversion. See the
66
+ [docs](https://buckwem.github.io/prodockit-extensions/) for options, multi-page
67
+ registry sharing, and full syntax details.
68
+
69
+ ## PDF generation
70
+
71
+ [`prodockit.pdf`](https://buckwem.github.io/prodockit-extensions/pdf/) builds a
72
+ standalone PDF from your site, via Pandoc and WeasyPrint (both need to be
73
+ installed separately - see the docs). No Python required - it reads the
74
+ same `zensical.toml` your site already has:
75
+
76
+ ```bash
77
+ prodockit pdf
78
+ ```
79
+
80
+ That's it - run it from your project root and it builds a complete PDF,
81
+ table of contents included, from every page in your `nav`. See the
82
+ [docs](https://buckwem.github.io/prodockit-extensions/pdf/) for the
83
+ `zensical.toml` settings it reads, and for the Python API
84
+ (`build_pdf()`, `prodockit.pdf.html`/`.lua`/`.css`/`.icons`/`.mermaid`) if
85
+ you're scripting your own build pipeline instead.
86
+
87
+ ## Website macros
88
+
89
+ [`prodockit.zensical_macros`](https://buckwem.github.io/prodockit-extensions/macros/)
90
+ provides a site-wide word count, the git-detected repository URL, chapter/
91
+ appendix numbering that continues across pages, and reference/acronym/
92
+ glossary spacing that matches `prodockit.pdf`'s own PDF output - as Jinja
93
+ variables/macros for Zensical's own macros plugin:
94
+
95
+ ```toml
96
+ [project.markdown_extensions.zensical.extensions.macros]
97
+ modules = ["prodockit.zensical_macros"]
98
+ ```
99
+
100
+ See the [docs](https://buckwem.github.io/prodockit-extensions/macros/) for the
101
+ full variable/macro list.
102
+
103
+ ## Development
104
+
105
+ ```bash
106
+ python -m venv .venv
107
+ source .venv/bin/activate
108
+ pip install -e ".[dev]"
109
+ pytest
110
+ ```
111
+
112
+ `zensical` is a core dependency, so `zensical serve` is available as soon as
113
+ `prodockit` is installed - no extra step needed to build the documentation
114
+ locally.
115
+
116
+ ## License
117
+
118
+ MIT - see [LICENSE](LICENSE).