Metadata-Version: 2.5
Name: prodockit
Version: 0.41.0
Summary: A family of extensions for Zensical needed for professional and academic documentation: cross-references to sections, figures and tables, bibliography/citation handling, a glossary, a back-of-book index, table headers and directory trees, a Pandoc/WeasyPrint PDF pipeline, Jinja macros for word counts and reference-style spacing, repo-metadata syncing, build-input version pinning, template syncing, and machine setup automation
Project-URL: Homepage, https://github.com/buckwem/prodockit-extensions
Project-URL: Documentation, https://buckwem.github.io/prodockit-extensions/
Project-URL: Issues, https://github.com/buckwem/prodockit-extensions/issues
Author: Mark Buckwell
License-Expression: MIT
License-File: LICENSE
Keywords: extension,markdown,pandoc,pdf,python-markdown,zensical
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: click>=8.0
Requires-Dist: markdown>=3.10.3
Requires-Dist: pymdown-extensions>=11.0.1
Requires-Dist: pypdf>=4.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: zensical>=0.0.55
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pymupdf>=1.24; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: types-beautifulsoup4; extra == 'dev'
Requires-Dist: types-markdown; extra == 'dev'
Provides-Extra: index
Requires-Dist: pymupdf>=1.24; extra == 'index'
Provides-Extra: testing
Requires-Dist: pymupdf>=1.24; extra == 'testing'
Requires-Dist: pytest>=7.0; extra == 'testing'
Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'testing'
Description-Content-Type: text/markdown

# prodockit

<!-- repo-badges:start (auto-generated by `prodockit sync-repo` - do not edit by hand) -->
<p align="center">
  <a href="https://buckwem.github.io/prodockit-extensions/"><img
    src="https://img.shields.io/website?url=https%3A%2F%2Fbuckwem.github.io%2Fprodockit-extensions%2F&label=Documentation&style=flat"
    alt="Documentation"
  /></a>
  <a href="https://github.com/buckwem/prodockit-extensions/actions"><img
    src="https://github.com/buckwem/prodockit-extensions/actions/workflows/docs.yml/badge.svg"
    alt="Build"
  /></a>
  <a href="https://github.com/buckwem/prodockit-extensions/stargazers"><img
    src="https://img.shields.io/github/stars/buckwem/prodockit-extensions?style=flat&logo=github&label=Stars"
    alt="GitHub Stars"
  /></a>
  <a href="https://github.com/buckwem/prodockit-extensions/forks"><img
    src="https://img.shields.io/github/forks/buckwem/prodockit-extensions?style=flat&logo=github&label=Forks"
    alt="GitHub Forks"
  /></a>
</p>
<!-- repo-badges:end -->

A toolkit for writing and publishing professional or academic documents with
[Zensical](https://zensical.org/). Write the content once in Markdown, publish
it as a website, and build a single downloadable or submittable PDF from the
same pages and navigation.

prodockit combines:

- nine [Python-Markdown](https://python-markdown.github.io/) authoring
  extensions for headings, references, citations, glossaries, tables,
  directories, procedures, bibliographies, and indexes;
- a Pandoc and WeasyPrint PDF pipeline;
- Zensical macros and built-output tests; and
- commands for machine setup, template updates, repository metadata, and
  reproducible build inputs.

[PyMdown Extensions](https://facelessuser.github.io/pymdown-extensions/) is a
direct part of the authoring foundation. `prodockit.steps` and
`prodockit.tree` are built with the PyMdown Blocks API, so they use its
slash-fenced block model rather than a separate, look-alike parser.

## Choose where to start

| You want to | Start here |
|---|---|
| Create and publish a document | [prodockit User Guide](https://buckwem.github.io/prodockit-userguide/) |
| Begin with a maintained report project | [prodockit-template](https://github.com/buckwem/prodockit-template) |
| Build a small local site from scratch | [Build your first site](https://buckwem.github.io/prodockit-extensions/getting-started/) |
| Look up Markdown syntax and configuration | [Authoring reference](https://buckwem.github.io/prodockit-extensions/authoring/) |
| Build a PDF or publish with CI | [Publish a document](https://buckwem.github.io/prodockit-extensions/publishing/) |
| Evaluate versions, platforms, and maturity | [Support and compatibility](https://buckwem.github.io/prodockit-extensions/about/support/) |
| Change prodockit itself | [Contributing](CONTRIBUTING.md) |

## Project status

prodockit is currently **Alpha**: its documented features are functional and
tested, but pre-1.0 releases can still make a documented breaking change when
needed to regularise the public configuration.

Bootstrap has completed manual end-to-end testing on Ubuntu, Windows, and
macOS against both the University of Surrey GitLab and GitHub.com.
That testing covered creating a new document repository and installing an
existing online repository locally. The full test suite runs on Ubuntu for
every push and pull request and is also run locally on macOS. Windows has
manual workflow coverage, but not a hosted full-suite regression job.

See [Support and compatibility](https://buckwem.github.io/prodockit-extensions/about/support/)
for the precise test depth, supported versions, and known constraints.

## Installation

prodockit requires **Python 3.10 or later** and is tested on Python 3.10–3.13:

```bash
python -m pip install prodockit
```

The base installation includes Zensical, Python-Markdown, PyMdown Extensions,
and the other Python libraries used by the Markdown extensions. Optional
extras add features with larger testing or indexing dependencies:

```bash
python -m pip install "prodockit[index]"    # PDF back-of-book index
python -m pip install "prodockit[testing]"  # checks for a built site and PDF
```

PDF and bibliography features need tools that the base installation does not
supply:

- install WeasyPrint with `python -m pip install weasyprint` and install its
  native Pango libraries;
- install Pandoc for PDF generation and BibTeX/BibLaTeX bibliographies; and
- install the optional Node tools and Chrome or Chromium only when the PDF
  contains Mermaid diagrams or TeX maths.

Follow the complete, platform-specific
[installation guide](https://buckwem.github.io/prodockit-extensions/installation/)
before building a PDF. Check the installed release with:

```bash
prodockit --version
```

## Authoring extensions

Enable only the extensions a project uses in `zensical.toml`. Each extension
has a beginner-first guide with copyable Markdown and a rendered result.

| Extension | Use it for |
|---|---|
| [`prodockit.headings`](https://buckwem.github.io/prodockit-extensions/extensions/headings/) | Numbered headings and appendices |
| [`prodockit.refs`](https://buckwem.github.io/prodockit-extensions/extensions/refs/) | Cross-references to headings, figures, and tables |
| [`prodockit.citations`](https://buckwem.github.io/prodockit-extensions/extensions/citations/) | A small reference list written directly in Markdown |
| [`prodockit.glossary`](https://buckwem.github.io/prodockit-extensions/extensions/glossary/) | Acronyms and glossary terms |
| [`prodockit.tables`](https://buckwem.github.io/prodockit-extensions/extensions/tables/) | Widths, merged cells, dense tables, and richer headers |
| [`prodockit.tree`](https://buckwem.github.io/prodockit-extensions/extensions/tree/) | Readable directory trees |
| [`prodockit.steps`](https://buckwem.github.io/prodockit-extensions/extensions/steps/) | Procedures presented as numbered steps |
| [`prodockit.bibliography`](https://buckwem.github.io/prodockit-extensions/extensions/bibliography/) | BibTeX/BibLaTeX citations formatted with CSL |
| [`prodockit.index`](https://buckwem.github.io/prodockit-extensions/extensions/index-terms/) | A PDF-only back-of-book index |

For example:

```toml
[project.markdown_extensions."prodockit.headings"]
numbering = "continuous"

[project.markdown_extensions."prodockit.refs"]

[project.markdown_extensions."prodockit.steps"]
```

The [authoring reference](https://buckwem.github.io/prodockit-extensions/authoring/)
explains the three consistent stages for each feature: enable the extension,
write the Markdown, then configure optional behaviour.

## Publishing and project commands

Run `prodockit --help` for the options installed with the current release.
The `pdk` executable is an exact shorter alias for `prodockit`; `boot` aliases
`bootstrap`, and `source` aliases `source-bundle`.

| Command | Purpose |
|---|---|
| `prodockit bootstrap` | Check or prepare a machine and document project |
| `prodockit init-tools` | Install the local Node tooling for Mermaid and maths rendering |
| `prodockit init-mathjax` | Copy the installed MathJax bundle into website assets |
| `prodockit pdf` | Build one PDF from the pages in the Zensical navigation |
| `prodockit source-bundle` | Bundle the Markdown source and configuration into a separate PDF |
| `prodockit sync-repo` | Match repository links, branding, and managed README badges to `origin` |
| `prodockit pins` | Check and update build-input versions across project files |
| `prodockit template-sync` | Review and apply later updates from prodockit-template |

The command-line reference documents
[safe first runs, write behaviour, and aliases](https://buckwem.github.io/prodockit-extensions/command-line/).
When publishing both outputs locally, build in this order:

```bash
prodockit pdf
zensical build --clean --strict
```

The PDF comes first because the site build copies the completed PDF into its
output. The maintained template includes annotated GitHub Actions and GitLab
CI workflows that perform the same clean build, test the generated files, and
deploy Pages.

## Package integrations

| Integration | Purpose |
|---|---|
| [`prodockit.zensical_macros`](https://buckwem.github.io/prodockit-extensions/macros/) | Word counts, repository data, document-wide numbering, and layout helpers for Zensical templates |
| [`prodockit.testing`](https://buckwem.github.io/prodockit-extensions/devcons/testing/) | Reusable pytest fixtures and checks for a generated site and PDF |

These are not Markdown extensions. Macros are enabled through Zensical's
macros configuration; testing support is installed with
`python -m pip install "prodockit[testing]"`.

## Development

Changes to the package, tests, automation, or technical documentation should
follow [CONTRIBUTING.md](CONTRIBUTING.md). It gives the editable installation,
external PDF prerequisites, macOS library-path setup, source gates, built-site
tests, and pull-request expectations.

## Contributing

Contributions are welcome. Search or open an issue before starting a change
beyond a small correction, and submit changes through a focused branch and
pull request. See [Contributing](CONTRIBUTING.md) for the complete workflow.

## Licence

MIT - see [LICENSE](LICENSE).
