Skip to content

docs: add a Sourcey configuration for a generated API reference - #1996

Open
ASporeTeam wants to merge 2 commits into
stretchr:masterfrom
ASporeTeam:spore/sourcey-reference-docs
Open

ASporeTeam wants to merge 2 commits into
stretchr:masterfrom
ASporeTeam:spore/sourcey-reference-docs

Conversation

@ASporeTeam

Copy link
Copy Markdown

What this adds

A Sourcey configuration that builds a static, searchable API
reference for Testify's five public packages (assert, require, mock, suite, http) straight
from this repository's source.

  • docs/sourcey/sourcey.config.ts — the configuration (godoc adapter, live extraction with a
    committed-snapshot fallback).
  • docs/sourcey/README.md — how to build it, what it covers, and why it is useful.

Nothing is pre-generated: the reference is built from the tree, so it can be regenerated for any
commit and always matches the code.

Why

Testify's own documentation is one README.md plus one package comment per package; there is no
per-symbol reference in this repository, and the reference most readers use (pkg.go.dev) is
auto-generated and reports no coverage. Building one from source makes two things measurable:

  • Doc-comment coverage — 710 of 714 exported symbols carry a doc comment (99.4%).
  • Example coverage — the whole public API ships 9 runnable Example… functions, all
    attached to the five …AssertionFunc types in assert and require. mock, suite and http
    have none.

That second number is the interesting one: it shows exactly which entry points a new user cannot
find an example for.

A published instance

An instance of this configuration, built from the pinned commit
87a7b9d57689f6579db2da795ab8deeab29cb724, is live at https://testify.anonymux.org/. It is
offered as a reference implementation and as an opportunity to review the configuration — if you
would rather host it on a domain you control, the same configuration and snapshot produce the same
site.

Notes for the reviewer

  • The configuration is MIT licensed, like the rest of the repository.
  • The generated output contains only Testify's own doc comments and signatures.
  • This pull request adds documentation tooling only: no library code is touched, and no behaviour
    changes.

If you would prefer a different shape (for example a committed godoc.json snapshot, a different
package list, or the generated pages themselves), say so and I will adjust.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant