Additional documentation topics

[cmdcolin]

• CLI - loading different synteny formats
• User guide - Faceted track selector
• User guide - LGV Basic usage: double click to zoom
• SV inspector: after adding breakpoint split view, show that you have to manually open up tracks https://jbrowse.org/jb2/docs/user_guides/sv_inspector_view/#launching-breakpoint-split-view
• Dotplot: toggling ctrl wheel
• Developer guide: display type https://jbrowse.org/jb2/docs/developer_guides/creating_display/ and track type https://jbrowse.org/jb2/docs/developer_guides/creating_track/ and view type https://jbrowse.org/jb2/docs/developer_guides/creating_view/
• Storybook: document the usage of trackId for text indexing (mentioned by @kuffelgr on chat) done
• Maybe a special section on configuring "displays": configure default height, configure color, and explain the "displays" section of the configs more?

[cmdcolin]

also, more "tutorials" like #3449

[cmdcolin]

another doc topic, plugins GMOD/jbrowse-plugin-template#30

[carolinebridge]

• improve the embedded tutorial to be more practical for generating visualizations and using the .view functions
• on the "features" page, specify which file types are supported by the embedded views

[cmdcolin]

just for context, @carolinebridge-oicr and i were talking in chat just about the setup of jbrowse with the overture team, etc. I think the embedded deployment is difficult for a number of reasons

• unclear how to load tracks (does not really use jbrowse-cli)
• difficult to hand write track configs. how can we simplify? we could make a little helper that calls guesstracktype/guessadaptertype for an array of filenames or something, e.g. make a 'simplified config format' but this creates a sort of 'parallel config schema'... or we can take larger efforts to make our standard config models simpler to instantiate (use of preprocessSnapshot to fill in things automatically perhaps?)
• several of our examples explain to 'hand configure a defaultsession' which I think is really not recommended
• need to, if not using defaultSession, call imperative APIs like showTracks, could add helper function to make it so that createViewState accepts a 'defaultTracks' type argument (this was decided against long ago, but could be reconsidered). if we don't do this, I think it is worth making more clear through more examples that using the view functions (like showTrack) is the recommended way to do things, as I don't think hand-coding the defaultSession is a good experience.

[cmdcolin]

also, it may be worth steering people to our working examples e.g. storybook and embedded_demos over the tutorial page

[carolinebridge]

I know we have the state model reference, but I think for anything embedded view relevant we should have a separate, clearly documented API for things like showTracks. Could link out to the storybooks too.

[cmdcolin]

example for variation track color GMOD/jbrowse#937 (comment)

[cmdcolin]

advanced example of config (setting color, etc) at https://jbrowse.org/jb2/docs/config_guides/quantitative_track/ (recommended by veupathdb)

[cmdcolin]

Update docs with HiDPI screenshots...many are low res

[cmdcolin]

connections #2765

[cmdcolin]

improve synteny docs #3270

[carolinebridge]

do we have enough discoverability in our documentation for cross-regional visualizations / data rendering? we've got a ton of support for it at this point might be worth having a dedicated page for it in our user guide

yes could be worthwhile, or at least expanding documentation around the features that use this mode

per #4045

[cmdcolin]

paired bedpe display needs docs

[cmdcolin]

• Document @jbrowse/react-app interaction with CLI
• Document how to add track programmatically in @jbrowse/react-app
• Document "embedded views" vs "full jbrowse app" vs "embedded @jbrowse/react-app" (on website features page)

[cmdcolin]

address #3280

[cmdcolin]

Review quickstart guide: this is an important document, and in the middle it switches from using npx serve to --out /var/www/html/jbrowse2 without explanation

https://jbrowse.org/jb2/docs/quickstart_web/

Also review this repo's README.md. could be made more minimal, as people might find it, thinking they need to apt install things when they dont really

[cmdcolin]

I also still think there is value in making a superquickstart. it could be made into a TLDR at the top of the quickstart. this was, at one point, deleted but i think it helps to orient someone about a cli workflow without a lot of prose. it is hard to scan the document at a high level

[cmdcolin]

the quickstart also does not have links to example files. it could essentially mirror the protocols paper, but with smaller files

[cmdcolin]

possible idea; use an ai to aid documentation process. AI can generate a bunch of plausible looking stuff, lowering the barrier to just getting it done. we have not established guidelines about using AI generated content in our project but if it is acceptable, it might be worth trying out

[cmdcolin]

• document PIF
• document (or add to every code example?) memo-izing createViewState in embedded. need to decide 'best' memoize method if adding to all

[cmdcolin]

mention in various places where plugins are documented e.g. https://jbrowse.org/jb2/docs/tutorials/no_build_plugin_tutorial/ that embedded apps can use a different technique

[cmdcolin]

make a better doc-type storybook page for the "observer" examples (currently it is only under source code examples)

make synteny example in the react-app storybook

[cmdcolin]

create troubleshooting guide for text indexing not working

motivated by office hours which required using --force to reindex cause existing was a 0 byte ix and ixx file

[cmdcolin]

(could also make text-index output the currently indexed tracks to make this more clear to user)

[cmdcolin]

how to load a bedMethyl track into multi-wiggle (via UI, or via hand edited config...). we could detect file extension .bedMethyl and have special behavior this but that extension is rare. more common to just be .bed unfortunately