Give stadion documentation - #5
Merged
Merged
Conversation
Every other library in the organisation publishes a documentation site. stadion did not, so its homepage pointed at PyPI and the README carried everything. Five pages, all built from the README rather than newly invented: what the project is and what a run looks like, the six tasks with their headroom table, writing an agent, the protocol, and the self-check. Two things the README did not say plainly enough to leave implicit: A score slightly above 1 is sampling noise - the optimum is optimal in expectation, and a finite run scatters around its mean. Only a score clearly above 1, with an interval that does not reach back down, is a bug report. Left unqualified, the first reader to see 1.02 would file the wrong issue. `report.degenerate` is worth handling rather than ignoring, so the agent page says so and links the protocol section that explains why the scale sometimes has no denominator. Also corrected: the Status section said "Not yet on PyPI" four lines under an install command that reads `pip install stadion-rl`. It has been on PyPI since the 0.1.0 release. Built with `--strict`, which fails on a broken internal link or a page outside the navigation. The theme is configured `font: false` and the built HTML makes no third-party request - verified against the output, not assumed.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Every other library in the organisation publishes a documentation site. stadion did not — its
homepagepointed at PyPI and the README carried everything.Five pages, built from the README rather than newly invented:
index.mdtasks.mdagents.mdact(view)contract, both surfaces, reading the scoreprotocol.mdverify.mdstadion verifyand why it is the check that mattersTwo things stated plainly that the README left implicit
A score slightly above 1 is sampling noise. The optimum is optimal in expectation, and a finite run scatters around its mean. Only a score clearly above 1, with an interval that does not reach back down to it, is a bug report. Left unqualified, the first reader to see
1.02files the wrong issue.report.degenerateis worth handling rather than ignoring. The agent page says so and links the protocol section explaining why the scale sometimes has no denominator.Corrected
The Status section said "Not yet on PyPI" — four lines under an install command that reads
pip install stadion-rl, and after the 0.1.0 release went out. It now links PyPI and the documentation.Verified
mkdocs build --strictpasses: six pages, no broken internal link, nothing outside the navigation.The theme is configured
font: falseand the built HTML makes no third-party request — checked against the output rather than assumed. The only externalhrefin a built page is the canonical link. No Google Fonts.site/added to.gitignore, since the site is published from CI rather than committed.After merging
Pages has to be pointed at Actions, and the repository homepage moved off PyPI:
Once that is live, the organisation site can link it — the front page deliberately does not yet, because
https://drobyshevdev.github.io/stadion/is currently a 404.