Document what "compatible with nextstrain run" means

[joverlee521]

Follow up to nextstrain/measles#90 (comment)

[victorlin]

Brief list, worded more like a migration guide:

• Remove any workdir: directives. (these are overridden)
• Relative paths to existing files must be resolved to absolute paths. Options:
  1. Resolve in workflow with a single, fixed search path. Example
  2. Resolve in workflow by calling resolve_config_path(). Example
     • Note: The relative paths themselves may need to be updated to remove defaults/. Example
  3. Resolve in Augur by setting AUGUR_SEARCH_PATHS. (WIP, currently only used by augur subsample)
• Declare compatibility in nextstrain-pathogen.yaml.

[joverlee521]

Notes based on changes in nextstrain/zika#85:

• Use default workflow config in repo and overlay custom config from analysis dir. Example
• Resolve custom_rules paths for include directive. Example
• Resolve paths to custom scripts
  1. directly within rule shell block. Example
  2. using custom scripts() and provide as param. Example

[jameshadfield]

The above describe the code changes needed, but nextstrain run is a conceptual shift for the user too. Our docs states

[nextstrain run] does not require knowledge of ... source code

so I'd think to be compatible with nextstrain run we have to have some docs explaining what the repo does, where the data's sourced from, and perhaps how to modify it. We've schemed about auto-generated docs etc, but for starters I think what zika does with the phylo README is enough. How does this get surfaced to the user? Is there a listing somewhere of the pathogens which support nextstrain run are and pointers to their docs (readmes)?

[victorlin]

Rather than each pathogen having its own copy of nextstrain run instructions, which should be identical across pathogens minus the pathogen name itself, we could point to a central docs page (e.g. an extension of Pathogens). This page would have the detailed instructions, and maybe a static list of the supported pathogens/workflows for starters (until we have an easy way to generate the list, see below).

Is there a listing somewhere of the pathogens which support nextstrain run are and pointers to their docs (readmes)?

I remember an idea floating around of adding a Nextstrain CLI command to show the list, but can't find any links.

[jameshadfield]

we could point to a central docs page (e.g. an extension of Pathogens). This page would have the detailed instructions, and maybe a static list of the supported pathogens/workflows for starters

I think this would be great. Something more like an introduction / overview of nextstrain run rather than the current reference-like docs, followed by a list of pathogens / workflows, with each workflow linking out to its README file like zika's.

[victorlin]

I remember an idea floating around of adding a Nextstrain CLI command to show the list, but can't find any links.

Created an issue nextstrain/cli#502 and took a stab at implementing it.

[joverlee521]

Rather than each pathogen having its own copy of nextstrain run instructions, which should be identical across pathogens minus the pathogen name itself, we could point to a central docs page (e.g. an extension of Pathogens). This page would have the detailed instructions, and maybe a static list of the supported pathogens/workflows for starters (until we have an easy way to generate the list, see below).

Adding this to nextstrain/docs.nextstrain.org#259