avdoc
=====
CLI tool to generate human-readable HTML documentation for an [Apache Avro] schema AVSC file.
Want Avro schema docs? 'avdoc!
## Installation
### Requirements
Software required outside of Python package dependencies:
- [Graphviz] for the reference graph.
### Install as Python package
Install the [`avdoc` package on PyPI]:
```shell
pip install --upgrade avdoc
```
## Usage
```shell
[python -m] avdoc tests/example.avsc > out/example.html && open out/example.html
```
To provide a version ID, e.g. the current git commit:
```shell
[python -m] avdoc --schema-version $(git rev-parse --short head) example.avsc > out/example.html
```
`$ avdoc --help`
```
usage: avdoc [-h] [--schema-title SCHEMA_TITLE]
[--schema-version SCHEMA_VERSION]
avsc
CLI tool to generate HTML documentation for an Apache Avro schema
positional arguments:
avsc
options:
-h, --help show this help message and exit
--schema-title SCHEMA_TITLE
--schema-version SCHEMA_VERSION
```
## Features
- [x] graph/diagram of which record schemas reference each other
- [ ] reference graph for every complex (record) type
- [x] Markdown support in `"doc"` strings
- [ ] supports all [complex Avro types][]
- [x] record
- [x] enum
- [x] array
- [x] union
- [ ] error
- [ ] map
- [ ] request
### Design Goals
The output should:
- be well-formatted semantic HTML.
- be legible in basic browsers without styling.
- aid understanding of the underlying schema.
- be a single static file for sharing without dependencies.
- be linkable to reference specific schemas and fields.
## Development
- [devenv] for development environment
- [direnv] for automatic shell activation (optional)
`devenv shell` should set up Python & Poetry with dependencies installed.
Use `.venv/bin/python` as your Python interpreter.
### Publishing
#### Bump version
```shell
bumpversion major|minor|patch
```
#### Update documentation
Run `mdsh`.
#### Publish Python package to PyPI
[Configure Poetry credentials] with [PyPI token] and run:
```shell
poetry publish --build
```
### Architecture
Not much to speak of.
`avdoc` is a couple of hundred lines of Python script
generating static HTML, with a bit of string munging to get component outputs
into the final HTML output page.
This code is purpose-oriented.
The output is opinionated, but not much time has been spent on the code
past getting it working for my own needs.
It's not intended to be exemplary of anything in particular.
## Maintenance
I probably won't pay too much attention to `avdoc` maintenance
once it's suitable for my own needs.
I'd like to try to ensure that dependencies are kept up to date.
Fork for your own needs.
Raise a PR if you'd like me to consider including your changes.
Make sure you adhere to the [license](#license) by ensuring your users
have access to your modifications.
## License
[AGPL]:
> [[…] requires the operator of a network server to provide the source code of the modified version running there to the users of that server. Therefore, public use of a modified version, on a publicly accessible server, gives the public access to the source code of the modified version.](https://www.gnu.org/licenses/agpl-3.0.html#:~:text=It%20requires%20the%20operator%20of%20a%20network%20server)
`avdoc` is released as copyleft software.
If you modify `avdoc` then you must make changes available to your users.
If the AGPL license is an issue, and you want to relicense `avdoc` privately,
then reach out to discuss pricing.
## Prior Art
`avdoc` is intended as a replacement for [avrodoc-plus],
which itself was intended as a replacement for [avrodoc],
via a long line of forks.
To run `avrodoc-plus` and see its output:
```shell
npm install @mikaello/avrodoc-plus
node_modules/@mikaello/avrodoc-plus/bin/avrodoc-plus.js example.avsc --output out/avrodocplus.html
```
## Why?
Unfortunately the original [avrodoc] and forks are all
in varying stages of [software decay], mostly due to NodeJS ecosystem churn.
Their NPM package dependencies include packages which have themselves
gone unmaintained or had breaking changes in following versions,
with CVEs piling up against the transitive dependencies.
[avrodoc-plus] has about 10 critical CVEs in its dependency graph.
This isn't necessarily an issue in itself unless you're running these
avrodoc tools in an online capacity or on untrusted input.
But at $WORK it was generating a lot of false-positives in automatic
[SBOM] security scanners which had to be explained to infosec specialists.
The HTML output from the avrodoc tools is also rather dynamic,
requiring JS to render, when it could just be a classic HTML page.
I have taken the opportunity to implement some quality-of-life
improvements for readers.
See [§Design Goals](#design-goals) for more info.
Why the name `avdoc` specifically?
The [Apache Software Foundation protects project name trademarks]
(quite rightly) and I wanted to avoid the [kcat naming issue].
`avdoc` is "Powered by Apache Avro™" but not a part of Apache Avro™.
[//]: # (Links)
[Apache Avro]: https://avro.apache.org
[complex Avro types]: https://avro.apache.org/docs/1.11.1/specification/#complex-types-1
[avrodoc-plus]: https://github.com/mikaello/avrodoc-plus
[avrodoc]: https://github.com/ept/avrodoc
[AGPL]: https://www.gnu.org/licenses/agpl-3.0.html
[direnv]: https://direnv.net
[devenv]: https://devenv.sh
[Graphviz]: https://www.graphviz.org
[software decay]: https://en.wikipedia.org/wiki/Software_rot
[SBOM]: https://en.wikipedia.org/wiki/Software_supply_chain
[kcat naming issue]: https://github.com/edenhill/kcat#what-happened-to-kafkacat
[Apache Software Foundation protects project name trademarks]: https://www.apache.org/foundation/marks/faq/#products
[Configure Poetry credentials]: https://python-poetry.org/docs/repositories/#configuring-credentials
[PyPI token]: https://pypi.org/help/#apitoken
[`avdoc` package on PyPI]: https://pypi.org/project/avdoc/
Raw data
{
"_id": null,
"home_page": "https://github.com/jeffbr13/avdoc",
"name": "avdoc",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10,<4.0",
"maintainer_email": "",
"keywords": "avro,avro-schema",
"author": "Ben Jeffrey",
"author_email": "mail@benjeffrey.net",
"download_url": "https://files.pythonhosted.org/packages/dc/f1/00fa341e0f94df85a020e269cb1950b6290033d6b24fe2ced2c20ef7588a/avdoc-0.3.1.tar.gz",
"platform": null,
"description": "avdoc\n=====\n\nCLI tool to generate human-readable HTML documentation for an [Apache Avro] schema AVSC file.\n\nWant Avro schema docs? 'avdoc!\n\n## Installation\n\n### Requirements\nSoftware required outside of Python package dependencies:\n- [Graphviz] for the reference graph.\n\n### Install as Python package\nInstall the [`avdoc` package on PyPI]:\n```shell\npip install --upgrade avdoc\n```\n\n## Usage\n\n```shell\n[python -m] avdoc tests/example.avsc > out/example.html && open out/example.html\n```\n\nTo provide a version ID, e.g. the current git commit:\n```shell\n[python -m] avdoc --schema-version $(git rev-parse --short head) example.avsc > out/example.html\n```\n\n`$ avdoc --help`\n```\nusage: avdoc [-h] [--schema-title SCHEMA_TITLE]\n [--schema-version SCHEMA_VERSION]\n avsc\n\nCLI tool to generate HTML documentation for an Apache Avro schema\n\npositional arguments:\n avsc\n\noptions:\n -h, --help show this help message and exit\n --schema-title SCHEMA_TITLE\n --schema-version SCHEMA_VERSION\n```\n\n## Features\n- [x] graph/diagram of which record schemas reference each other\n - [ ] reference graph for every complex (record) type\n- [x] Markdown support in `\"doc\"` strings\n- [ ] supports all [complex Avro types][]\n - [x] record\n - [x] enum\n - [x] array\n - [x] union\n - [ ] error\n - [ ] map\n - [ ] request\n\n### Design Goals\nThe output should:\n- be well-formatted semantic HTML.\n- be legible in basic browsers without styling.\n- aid understanding of the underlying schema.\n- be a single static file for sharing without dependencies.\n- be linkable to reference specific schemas and fields.\n\n\n\n## Development\n- [devenv] for development environment\n- [direnv] for automatic shell activation (optional)\n\n`devenv shell` should set up Python & Poetry with dependencies installed.\nUse `.venv/bin/python` as your Python interpreter.\n\n### Publishing\n\n#### Bump version\n\n```shell\nbumpversion major|minor|patch\n```\n\n#### Update documentation\nRun `mdsh`.\n\n#### Publish Python package to PyPI\n[Configure Poetry credentials] with [PyPI token] and run:\n```shell\npoetry publish --build\n```\n\n### Architecture\nNot much to speak of. \n\n`avdoc` is a couple of hundred lines of Python script\ngenerating static HTML, with a bit of string munging to get component outputs\ninto the final HTML output page. \nThis code is purpose-oriented.\nThe output is opinionated, but not much time has been spent on the code\npast getting it working for my own needs.\nIt's not intended to be exemplary of anything in particular.\n\n\n## Maintenance\nI probably won't pay too much attention to `avdoc` maintenance \nonce it's suitable for my own needs.\nI'd like to try to ensure that dependencies are kept up to date.\n\nFork for your own needs.\nRaise a PR if you'd like me to consider including your changes.\nMake sure you adhere to the [license](#license) by ensuring your users\nhave access to your modifications.\n\n## License\n[AGPL]:\n> [[\u2026] requires the operator of a network server to provide the source code of the modified version running there to the users of that server. Therefore, public use of a modified version, on a publicly accessible server, gives the public access to the source code of the modified version.](https://www.gnu.org/licenses/agpl-3.0.html#:~:text=It%20requires%20the%20operator%20of%20a%20network%20server)\n\n`avdoc` is released as copyleft software.\nIf you modify `avdoc` then you must make changes available to your users.\n\nIf the AGPL license is an issue, and you want to relicense `avdoc` privately, \nthen reach out to discuss pricing. \n\n## Prior Art\n\n`avdoc` is intended as a replacement for [avrodoc-plus],\nwhich itself was intended as a replacement for [avrodoc],\nvia a long line of forks.\n\nTo run `avrodoc-plus` and see its output:\n\n```shell\nnpm install @mikaello/avrodoc-plus\nnode_modules/@mikaello/avrodoc-plus/bin/avrodoc-plus.js example.avsc --output out/avrodocplus.html\n```\n\n## Why?\n\nUnfortunately the original [avrodoc] and forks are all\nin varying stages of [software decay], mostly due to NodeJS ecosystem churn. \nTheir NPM package dependencies include packages which have themselves \ngone unmaintained or had breaking changes in following versions, \nwith CVEs piling up against the transitive dependencies.\n[avrodoc-plus] has about 10 critical CVEs in its dependency graph.\nThis isn't necessarily an issue in itself unless you're running these\navrodoc tools in an online capacity or on untrusted input.\nBut at $WORK it was generating a lot of false-positives in automatic\n[SBOM] security scanners which had to be explained to infosec specialists.\n\nThe HTML output from the avrodoc tools is also rather dynamic, \nrequiring JS to render, when it could just be a classic HTML page. \n\nI have taken the opportunity to implement some quality-of-life\nimprovements for readers.\nSee [\u00a7Design Goals](#design-goals) for more info. \n\nWhy the name `avdoc` specifically?\nThe [Apache Software Foundation protects project name trademarks]\n(quite rightly) and I wanted to avoid the [kcat naming issue].\n\n`avdoc` is \"Powered by Apache Avro\u2122\" but not a part of Apache Avro\u2122.\n\n\n\n[//]: # (Links)\n[Apache Avro]: https://avro.apache.org\n[complex Avro types]: https://avro.apache.org/docs/1.11.1/specification/#complex-types-1\n[avrodoc-plus]: https://github.com/mikaello/avrodoc-plus\n[avrodoc]: https://github.com/ept/avrodoc\n[AGPL]: https://www.gnu.org/licenses/agpl-3.0.html\n[direnv]: https://direnv.net\n[devenv]: https://devenv.sh\n[Graphviz]: https://www.graphviz.org\n[software decay]: https://en.wikipedia.org/wiki/Software_rot\n[SBOM]: https://en.wikipedia.org/wiki/Software_supply_chain\n[kcat naming issue]: https://github.com/edenhill/kcat#what-happened-to-kafkacat\n[Apache Software Foundation protects project name trademarks]: https://www.apache.org/foundation/marks/faq/#products\n[Configure Poetry credentials]: https://python-poetry.org/docs/repositories/#configuring-credentials\n[PyPI token]: https://pypi.org/help/#apitoken\n[`avdoc` package on PyPI]: https://pypi.org/project/avdoc/\n",
"bugtrack_url": null,
"license": "AGPL-3.0-or-later",
"summary": "CLI tool to generate HTML documentation for an Apache Avro schema",
"version": "0.3.1",
"project_urls": {
"Homepage": "https://github.com/jeffbr13/avdoc",
"Repository": "https://github.com/jeffbr13/avdoc"
},
"split_keywords": [
"avro",
"avro-schema"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fc1cc93f4861ac1e0dd61590ef665a704364a0ead82485286fd604bede413e3d",
"md5": "09e92418ed19ac391526f8f46838211d",
"sha256": "4fcccf92a405a19dd428f4bece5b02f30bbfe40117741f61e7c74385b02ee12a"
},
"downloads": -1,
"filename": "avdoc-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "09e92418ed19ac391526f8f46838211d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4.0",
"size": 20193,
"upload_time": "2023-11-22T17:46:25",
"upload_time_iso_8601": "2023-11-22T17:46:25.408690Z",
"url": "https://files.pythonhosted.org/packages/fc/1c/c93f4861ac1e0dd61590ef665a704364a0ead82485286fd604bede413e3d/avdoc-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dcf100fa341e0f94df85a020e269cb1950b6290033d6b24fe2ced2c20ef7588a",
"md5": "77ed8d5691fee5edb9046cca61c26213",
"sha256": "5c9b490cffab7ac1977fd1747f444bd246de6215a5b48e59c6380bdab201e63c"
},
"downloads": -1,
"filename": "avdoc-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "77ed8d5691fee5edb9046cca61c26213",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4.0",
"size": 18639,
"upload_time": "2023-11-22T17:46:27",
"upload_time_iso_8601": "2023-11-22T17:46:27.143464Z",
"url": "https://files.pythonhosted.org/packages/dc/f1/00fa341e0f94df85a020e269cb1950b6290033d6b24fe2ced2c20ef7588a/avdoc-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-22 17:46:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jeffbr13",
"github_project": "avdoc",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "avdoc"
}
JSON
