Skip to content

docs: a README in the website's words that sends readers to the site - #25

Merged
Paururo merged 2 commits into
mainfrom
docs/readme-site
Oct 17, 2026
Merged

Paururo merged 2 commits into
mainfrom
docs/readme-site

Conversation

@Paururo

@Paururo Paururo commented Oct 17, 2026 •

Copy link
Copy Markdown
Member

What changes

The README now reads like the website and sends people there:

  • the same opening as the site ("Missing from the matrix. Still in the genome."), an Open the website button and a link into each part of it: Install, Your command, Try it, How it works, Docs, Reference;
  • an animated preview of How it works (assets/how-it-works.gif, 156 KB, the seven steps captured from the page), linking to the interactive version;
  • short numbered steps as on the site: install, one command, the one-minute example with the counts it should give, the four files, and the one setting that matters;
  • the full documentation list, the citation and the licence stay, in a few lines.

The website link is the GitHub Pages address, which starts working once the repository is public and Pages serves main /docs. Until then the README says how to open docs/index.html from a clone.

Authors and contributors

  • Below the header, the authors block the lab's other tools use: Paula Ruiz-Rodriguez and Mireia Coscolla, I2SysBio, University of Valencia-CSIC, FISABIO Joint Research Unit Infection and Public Health (the affiliation line of karyon, fstic, distree and AMAP).
  • At the end, the all-contributors table with both of them, as in get_MNV, fstic, karyon and AMAP.
  • The citation reads "Ruiz-Rodriguez P, Coscolla M." in the README, on the citation page and its BibTeX, and in every footer of the website; Cargo.toml lists both authors, as get_MNV, eskaks and snpick do.

Checks

tools/check_site.py now also checks the README: every link into the repository exists, every link into the website lands on a real page and anchor, every option in its recore commands exists in recore --help, its Try-it block and promised counts are the website's (the website's block is the one CI runs), and every page of the website cites Recore the way the README does. It was broken on purpose ten ways and caught all ten. The documentation workflow now also runs when README.md or assets/ change.

Locally fmt, clippy, the tests, the build, check_site.py --run-tutorial and the auto-merge gate check all pass. I checked the rendering with GitHub's own markdown API in light and dark.

The README opens like the website, with the same headline, an animated preview of How it works and a link into each part of the site, and keeps only the install, one command, the one-minute example, the four files and the policies. check_site.py now checks its links into the repository and the website, the options of its commands, and that its Try-it block and counts are the website's, and the documentation workflow runs when the README or its pictures change.
@Paururo Paururo added documentation Improvements or additions to documentation ci Workflows, automation config, and the tools/ scripts labels Oct 17, 2026
The README carries the authors block the lab's other tools use, Paula Ruiz-Rodriguez and Mireia Coscolla of I2SysBio, and the all-contributors table with both of them. The citation reads Ruiz-Rodriguez P, Coscolla M. in the README, on every page of the website and in the BibTeX, Cargo.toml lists both authors, and check_site.py fails if a page cites differently from the README.
@github-actions github-actions Bot added the packaging Cargo metadata, the lockfile, licensing, release label Oct 17, 2026
@Paururo
Paururo merged commit 177d04a into main Oct 17, 2026
7 checks passed
@Paururo
Paururo deleted the docs/readme-site branch October 18, 2026 08:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci Workflows, automation config, and the tools/ scripts documentation Improvements or additions to documentation packaging Cargo metadata, the lockfile, licensing, release

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant