Package: avdoc
avdocCLI tool to generate human-readable HTML documentation for anApache Avroschema AVSC file.Want Avro schema docs? 'avdoc!InstallationRequirementsSoftware required outside of Python package dependencies:Graphvizfor the reference graph.Install as Python packageInstall theavdocpackage on PyPI:pipinstall--upgradeavdocUsage[python-m]avdoctests/example.avsc>out/example.html&&openout/example.htmlTo provide a version ID, e.g. the current git commit:[python-m]avdoc--schema-version$(gitrev-parse--shorthead)example.avsc>out/example.html$ avdoc --helpusage: 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_VERSIONFeaturesgraph/diagram of which record schemas reference each otherreference graph for every complex (record) typeMarkdown support in"doc"stringssupports allcomplex Avro typesrecordenumarrayunionerrormaprequestDesign GoalsThe 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.Developmentdevenvfor development environmentdirenvfor automatic shell activation (optional)devenv shellshould set up Python & Poetry with dependencies installed.
Use.venv/bin/pythonas your Python interpreter.PublishingBump versionbumpversionmajor|minor|patchUpdate documentationRunmdsh.Publish Python package to PyPIConfigure Poetry credentialswithPyPI tokenand run:poetrypublish--buildArchitectureNot much to speak of.avdocis 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.MaintenanceI probably won't pay too much attention toavdocmaintenance
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 thelicenseby ensuring your users
have access to your modifications.LicenseAGPL:[…] 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.avdocis released as copyleft software.
If you modifyavdocthen you must make changes available to your users.If the AGPL license is an issue, and you want to relicenseavdocprivately,
then reach out to discuss pricing.Prior Artavdocis intended as a replacement foravrodoc-plus,
which itself was intended as a replacement foravrodoc,
via a long line of forks.To runavrodoc-plusand see its output:npminstall@mikaello/avrodoc-plus
node_modules/@mikaello/avrodoc-plus/bin/avrodoc-plus.jsexample.avsc--outputout/avrodocplus.htmlWhy?Unfortunately the originalavrodocand forks are all
in varying stages ofsoftware 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-plushas 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 automaticSBOMsecurity 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 Goalsfor more info.Why the nameavdocspecifically?
TheApache Software Foundation protects project name trademarks(quite rightly) and I wanted to avoid thekcat naming issue.avdocis "Powered by Apache Avro™" but not a part of Apache Avro™.