Skip to main content

Sites Used For Inspiration

This page keeps the useful parts of the docs research in one short maintainer note. It is not a roadmap; it is a reference for the documentation patterns we liked and the decisions they influenced.

Python Documentation Inspiration​

  • Hydra Deep, task-oriented docs with tutorials, reference material, plugins, developer notes, and runnable examples.
  • Great Expectations Clear audience paths, tested examples, and a strong distinction between learning material and reference material.
  • Flet Generated API/reference pages and a polished Docusaurus presentation for a Python package.
  • Apache Superset Audience-lane docs for users, administrators, and developers.
  • dlt Source-backed examples, generated docs artifacts, cookbook-style guidance, and agent-readable docs output.
  • Dagster A practical split between user guide, examples, deployment/integration topics, and API lookup.

Site Tooling Inspiration​

  • Docusaurus Explicit sidebars, generated category indexes, broken-link checks, local search options, and a straightforward static-site build model.

Packaging And Release Inspiration​

  • Python Packaging User Guide: GitHub Actions publishing Tag-triggered distribution builds, artifact handoff between jobs, and PyPI publishing through GitHub Actions.
  • PyPI Trusted Publishers OpenID Connect publishing without long-lived PyPI API tokens.
  • setuptools-scm Tag-derived package versions through dynamic = ["version"] in pyproject.toml.
  • uv GitHub Actions guide uv setup and caching patterns for CI that match PyPlyne's local development workflow.
  • PyPA version specifiers PEP 440-compatible version syntax, including why release tags should use Python-compatible versions such as v0.1.0, v0.2.0a1, and v0.2.0rc1.
  • GitHub Flow A simple branch-and-PR model where main is the integration branch and release readiness is proved by checks, review, and tags.
  • git-flow releases Useful contrast for larger projects that need separate release branches, even though PyPlyne does not need a permanent dev branch right now.
  • release-please Release-prep PR precedent: prepare changelogs and release metadata in a PR, then publish from the accepted release state.
  • python-semantic-release Python-specific automation precedent for CI-checked releases from GitHub.

What PyPlyne Borrowed​

  • Keep the first-time path short: install, create one file, run it, then branch into deeper docs.
  • Separate learning pages from lookup pages.
  • Keep runnable examples in examples/ and generate the examples page from those source files.
  • Generate CLI and Python API references so docs do not drift from code.
  • Keep cookbook recipes task-shaped instead of turning Quickstart into a manual.
  • Publish a concise llms.txt so agents can find the right docs without reading the whole site.
  • Derive package versions from release tags instead of hand-editing version strings.
  • Use release-prep pull requests on main instead of maintaining a permanent dev branch.
  • Keep PyPI publishing as a future tagged-release step; Git source installs stay documented until a package release exists.
  • Treat main as development that may be ahead of the latest release; tags are the stable points users can pin.

Maintenance Notes​

PyPlyne keeps a small, explicit sidebar in site/sidebars.js. Hand-written guides live in docs/. Generated pages and site/static/llms.txt should be refreshed through the site scripts before release:

cd site
npm run docs:generate
npm run docs:highlighting
npm run docs:check

Use npm run build for a production-shaped docs check.