Update dev docs #1243
Update dev docs #1243
Conversation
These were prone to getting out of sync. For the top-level summary, assume readers are reading the document via GitHub's markdown preview page and point them to use the interactive markdown heading navigator. For the testing section summary, replace it with a one-sentence summary of the entire section.
The project board is no longer being updated. Replace it with the issue list, which stays the most up to date.
| - Formats (Markdown and reStructuredText) | ||
| - Documentation structure | ||
| - Building documentation | ||
| Thank you for helping us to improve Augur! Use the GitHub markdown preview sidebar to navigate the sections in this document. |
There was a problem hiding this comment.
I've always missed this from our docs. The original auspice docs had this, and when it works it's amazing (it only half works on GitHub).
There was a problem hiding this comment.
The GitHub preview sidebar works fine for me, but I'm not a huge fan of relying on it.
An embedded table of contents with links to each section (and only up to a certain depth) seems beneficial to me. There's VSCode extensions that automatically insert/maintain one, but that's relying on a tool that not everyone editing this file will use, and I'm not sure those can ignore sections after a certain depth.
I'd be open to manually adding/maintaining one at the top level, something like this. Thoughts?
There was a problem hiding this comment.
Oh, I was referring to page designs which use the right margin to display a floating TOC, and then (bonus) highlight the entry you're currently reading. For example, here's a page built using docusaurus, which was what Auspice initially used for its docs.
There was a problem hiding this comment.
Oh! That does look much nicer. Probably not for this file unless we host it on RTD, but it sounds like some other of our RTD pages could benefit from this feature. Created an issue: nextstrain/docs.nextstrain.org#161
Description of proposed changes
Small touch ups. See commit messages.
Related issue(s)
N/A
Testing
N/A
Checklist
Add a message in CHANGES.md summarizing the changes in this PR that are end user focused. Keep headers and formatting consistent with the rest of the file.N/A, no functional changes