Doc updates #250
Merged
Doc updates #250
Conversation
This file contains 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
1 task
rST is our standard doc format; Markdown is the legacy format.
Initial conversion performed with:
pandoc -f markdown-smart --shift-heading-level-by -1 -t rst-smart doc/installation.md > doc/installation.rst
and then I hand reviewed and made additional edits.
Use "runtime" ~exclusively in user-facing output and documentation, replacing other terms such as "computing environment", "build environment", and "runner". "Computing environment" and "ambient environment" are now used only sparingly and in the general sense. "Computing platform" is now used to describe the things on which our runtimes are based (Docker, Conda, etc). The code still makes a distinction between "runners" and "runtimes" that's, albeit, fuzzy in places, but nevertheless useful. The runtime is the environment itself (e.g. a container image or a Conda environment), while the runner is the code (Python module) which arranges for Nextstrain CLI commands to execute things inside the runtime. Runners and runtimes have a 1:1 mapping.
…tstrain.org These versions are never released and thus never make it to RTD, so use the base version instead (which we presume has been released).
At this point, other places are better for documenting specifics of our different runtimes than the --help output of `build`.
… run The Conda runner is the first that can be setup all by itself, as long as the OS is supported. The current design of check-setup doesn't really account for the separate state of supported vs. set up, so I conditionalize what we report from test_setup(). As we add more automatic setup support for runtimes¹, it will probably be good to change check-setup to consider support status and set up status separately. ¹ e.g. <#220>
Adds the standalone installation method as well as installing from Bioconda. Restructures the page headings a bit to account for those. Bumps some versions in example output to be current instead of from 2y ago so that folks see a version number closer to what they'll get.
Documents the meanings I was working from in «Standardize use of "runtime" and related terminology» (8a1e87b). Good to make explicit terms that have been largely implicit until now (with the exception of "runtime"). I tried to be precise and non-overlapping to make the relationships between these terms sensible, but nevertheless they may want clarifications or revisions later. In any case, the bigger point of the glossary is to give a broad sense of the terms, rather than definitions that would satisfy a stickler.
victorlin
approved these changes
Jan 14, 2023
| @@ -0,0 +1,211 @@ | |||
| ============ | |||
There was a problem hiding this comment.
(non-blocking)
Nice pandoc command in 1272b0e. I like it better than what I had done in nextstrain/docs.nextstrain.org@f97ae0c and other previous conversions.
| Glossary | ||
| ======== | ||
|
|
||
| Terms used by Nextstrain CLI. Primarily intended for developers new to the |
There was a problem hiding this comment.
(non-blocking)
"runner" / "runtime" / "computing platform" is a nice way to describe the different pieces 👌
Defining and standardizing these terms enables us to better communicate how things work both for users and ourselves.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
A bit of a grab bag. See commit messages.
Testing