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.
- prodockit-0.1.0/.github/CODEOWNERS +8 -0
- prodockit-0.1.0/.github/workflows/ci.yml +33 -0
- prodockit-0.1.0/.github/workflows/docs.yml +32 -0
- prodockit-0.1.0/.github/workflows/publish.yml +33 -0
- prodockit-0.1.0/.gitignore +17 -0
- prodockit-0.1.0/LICENSE +21 -0
- prodockit-0.1.0/PKG-INFO +148 -0
- prodockit-0.1.0/PLAN-16.md +143 -0
- prodockit-0.1.0/README.md +118 -0
- prodockit-0.1.0/docs/about/changelog.md +235 -0
- prodockit-0.1.0/docs/about/license.md +5 -0
- prodockit-0.1.0/docs/extensions/citations.md +187 -0
- prodockit-0.1.0/docs/extensions/glossary.md +224 -0
- prodockit-0.1.0/docs/extensions/headings.md +229 -0
- prodockit-0.1.0/docs/extensions/refs.md +172 -0
- prodockit-0.1.0/docs/index.md +92 -0
- prodockit-0.1.0/docs/installation.md +69 -0
- prodockit-0.1.0/docs/macros.md +81 -0
- prodockit-0.1.0/docs/pdf.md +565 -0
- prodockit-0.1.0/pyproject.toml +77 -0
- prodockit-0.1.0/src/prodockit/__init__.py +39 -0
- prodockit-0.1.0/src/prodockit/_zensical.py +260 -0
- prodockit-0.1.0/src/prodockit/citations.py +207 -0
- prodockit-0.1.0/src/prodockit/glossary.py +206 -0
- prodockit-0.1.0/src/prodockit/headings.py +223 -0
- prodockit-0.1.0/src/prodockit/pdf/__init__.py +38 -0
- prodockit-0.1.0/src/prodockit/pdf/build.py +261 -0
- prodockit-0.1.0/src/prodockit/pdf/cli.py +52 -0
- prodockit-0.1.0/src/prodockit/pdf/config.py +189 -0
- prodockit-0.1.0/src/prodockit/pdf/css.py +626 -0
- prodockit-0.1.0/src/prodockit/pdf/html.py +499 -0
- prodockit-0.1.0/src/prodockit/pdf/icons.py +171 -0
- prodockit-0.1.0/src/prodockit/pdf/lua.py +256 -0
- prodockit-0.1.0/src/prodockit/pdf/mermaid.py +97 -0
- prodockit-0.1.0/src/prodockit/py.typed +0 -0
- prodockit-0.1.0/src/prodockit/refs.py +158 -0
- prodockit-0.1.0/src/prodockit/settings.py +66 -0
- prodockit-0.1.0/src/prodockit/util.py +272 -0
- prodockit-0.1.0/src/prodockit/wordcount.py +38 -0
- prodockit-0.1.0/src/prodockit/zensical_macros.py +251 -0
- prodockit-0.1.0/tests/test_citations.py +110 -0
- prodockit-0.1.0/tests/test_glossary.py +108 -0
- prodockit-0.1.0/tests/test_headings.py +137 -0
- prodockit-0.1.0/tests/test_pdf_build.py +206 -0
- prodockit-0.1.0/tests/test_pdf_cli.py +89 -0
- prodockit-0.1.0/tests/test_pdf_config.py +122 -0
- prodockit-0.1.0/tests/test_pdf_css.py +85 -0
- prodockit-0.1.0/tests/test_pdf_html.py +364 -0
- prodockit-0.1.0/tests/test_pdf_icons.py +62 -0
- prodockit-0.1.0/tests/test_pdf_lua.py +36 -0
- prodockit-0.1.0/tests/test_pdf_mermaid.py +59 -0
- prodockit-0.1.0/tests/test_refs.py +102 -0
- prodockit-0.1.0/tests/test_settings.py +50 -0
- prodockit-0.1.0/tests/test_wordcount.py +31 -0
- prodockit-0.1.0/tests/test_zensical.py +125 -0
- prodockit-0.1.0/tests/test_zensical_integration.py +395 -0
- prodockit-0.1.0/tests/test_zensical_macros.py +121 -0
- 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
|
prodockit-0.1.0/LICENSE
ADDED
|
@@ -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.
|
prodockit-0.1.0/PKG-INFO
ADDED
|
@@ -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).
|