[update docs] documentation overhaul

[carolinebridge]

summary of changes

• overall small grammar edits, emphasis, updating screenshots where critical, updating links w new structure, etc.

• moving combined guide to above faq

• changing name of combined guide "consolidated docs"

• added jupyter page

• moved url api into api, just api now w a subheader

• adding internal folders to help organize better

  • quickstarts
  • userguides
  • devguides

• split quickstarts into starting with cli and starting via download (downloading is technically the fastest way to start using jbrowse, might be better for general users)

• moved cli config, gui config, and "superquickstart" into userguides

• removing superquickstart and condensing cli guide (my justification for this is, if an admin is familiar enough with the jbrowse CLI / genome tools / webservers to be able to properly follow this guide, they're probably just going to reference the CLI commands page, otherwise they will probably need the full CLI guide, and having two is confusing)

• revamped intro page to include new docs and better descriptions, linked to jbrowse jupyter documentation

• split dev documentation up a bit, moved some info into tutorials

• resolve #2840 with additions to FAQ

• resolve #2142 with new tutorials

  • new dev tutorial, will add more tutorials with PR

Questions for draft:

wording/review for:

/docs/devguides/developer_guide/#renderers, line 222

I added an info block to try to help explain the relationship between views, tracks, displays, and renderers; just want to make sure it's descriptive enough, clear, and accurate.

/docs/devguides/devguide_pluggable_elements/#getrefnames line 324

There was a broken link here for reference renaming and I don't see anything related other than aliasing -- is this still a thing? changed the link to ref name aliasing

[codecov[bot]]

Codecov Report

Merging #3138 (706de15) into main (8a12788) will not change coverage. The diff coverage is n/a.

@@           Coverage Diff           @@
##             main    #3138   +/-   ##
=======================================
  Coverage   59.45%   59.45%           
=======================================
  Files         671      671           
  Lines       28628    28628           
  Branches     6926     6926           
=======================================
  Hits        17020    17020           
  Misses      11286    11286           
  Partials      322      322           

Impacted Files	Coverage Δ
products/jbrowse-web/src/Loader.tsx	63.56% <ø> (ø)

:mega: We’re building smart automated test selection to slash your CI/CD build times. Learn more

[cmdcolin]

if possible, i might like to avoid doing a large overhaul but i would like to incorporate other parts of this PR. I am thinking it may be good to avoid splitting up the guides into multiple files and subfolders because moving contents around can break our existing links. if there is a strong feeling that the long documents are overwhelming, maybe we can brainstorm a solution on that but my current feeling is to try to keep some of the contents in place

[rbuels]

@cmdcolin so if I'm reading right, the main concerns you have with this PR is that it breaks existing links, and it might be breaking the documentation into too many pages?

[cmdcolin]

basically yes. my thinking is influenced by jbrowse 1 with it's large configuration guide http://gmod.org/wiki/JBrowse_Configuration_Guide which gives you almost everything you need on a single page

[cmdcolin]

this is sort of just a "feeling" about the look and feel of the docs but the docusaurus webdesign could also be taken into account. I have thought multiple times that the web design of the docusaurus docs are a little "claustrophobic" with it's multiple sidebars on both the left and right side of the page, and that this "claustrophobic" feeling may influence a desire to break up the docs

[carolinebridge]

Most modern software guides have broken-up documentation in lieu of (and sometimes accompanied by) an index. That is, the left sidebar kind of operates as an index to help guide someone to the answers to their questions. Some examples: docker, AWS, Azure.

This was, for example, the spirit behind breaking "using the bookmark widget" out of the "User guide" because it draws attention to a big feature that new or returning users might need a reference on; placing it in its own page makes it easier to find.

The JB1 documentation, while all on one page, has a huge index that emulates this idea of accessibility to answers at a glance (i.e. it's basically the left sidebar without being on the left or the sidebar).

Comprehensive summary of pages moved/changed in this PR as of right now:

• JBrowse 2 combined guide > Consolidated docs (moved from position 1 to position 10)

Quickstart guides

• Super-quick start guide for JBrowse web > User guides/Configure JBrowse using the CLI (combined with "Config editing quick start - command-line interface)
• JBrowse web quick start > link is the same, however contents change to not use the CLI
• Config editing quick start - command-line interface > User guides/Configure JBrowse using the CLI
• Config editing quick start - graphical interface > User guides/Configure JBrowse using the GUI
• Quick start for JBrowse desktop > JBrowse desktop quickstart (phrasing in line with the other guides, link unchanged)
• NEW JBrowse web quick start via CLI > basically the old "JBrowse web quick start" page, uses "quickstart_cli" link

User guides

• NEW Configure JBrowse using the GUI (userguide_gui) (content from Config editing quick start - graphical interface)
• NEW Configure JBrowse using the CLI (userguide_cli) (content from Super-quick start guide for JBrowse web and Config editing quick start - command-line interface)
• Pages broken from the original user_guide page:
  • User guide > Navigating JBrowse and how to use genome tracks (more descriptive, moved some subheadings out)
  • NEW Using the bookmark widget (content from User guide)
  • NEW Using the plugin store (content from User guide)
  • NEW Getting the protein sequence for features (content from User guide)

Config guide

• used to be one page, now several underneath "User guides"
  • Config guide > Understanding the config.json (most of the content in here)
  • NEW configuring the theme (content from Config guide)
  • NEW configuring callbacks (content from Config guide)
  • NEW Disabling analytics (content from Config guide)
  • NEW Configuring plugins (content from Config guide)
  • NEW Customizing the feature details panel (content from Config guide)

Developer guide

• used to be one page, now several underneath "Developer guides"
  • Developer guide > Core concepts and pluggable elements
  • NEW Understanding the configuration model (used to be Configuration model concepts in Developer guide)
  • NEW Creating your own pluggable elements (used to be Common plugin use cases, Creating Adapters, Creating Custom Renderers, Creating custom track types in Developer guide)

API

• separate urlparams page moved into API

(( there are other new pages that are mostly new content and would not be involved in above feedback ))

Current broken links:

• quickstarts
• /user_guide, /developer_guide, /config_guide
• urlparams
• any link that uses a hash reference # to a header that's been moved to a new doc (this doesn't lead to a broken page however, and I would argue this is minor / would stipulate we can never change the headers of sections in the docs)

Proposed solutions:

• remove the internal organization to preserve original links (e.g. jbrowse.org/jb2/docs/quickstart_web)
• change /userguide_comp back to just /user_guide, and similar changes where a page was broken up (i.e. majority of content is still in that page; developer_guide, config_guide)
• move configuration guides into their own subheading/dropdown, remove "advanced configuration guides" (no internal linkage, so the links would just be /docs/config_guide format) to resolve that the original jbrowse.org/jb2/docs/config_guide link will link to what is now titled "Understanding the config.json", would contain the gui and cli config guides and all "advanced" guides
• revert change moving url params into api

To help visualize what's in the PR right now and in this comment without spinning it up:

JBrowse.org/jb2/docs presently:

With current PR changes without the proposed changed in this comment:

[cmdcolin]

I acknowledge it is a common pattern to break up docs, but it is sometimes hard to define the right boundaries for what constitutes a new article. it also relies a bit on SEO or a search engine inside the docs (which we don't have) to lead people to the right place (otherwise, you have to poke through the sidebar a lot). to me, the current system, with user guide, config guide, developer guide, is at least conceptually simple because there is basically no question where new contents go (fairly straightforward to categorize new content as user, config, or developer related) for devs adding new docs, and for users looking for stuff, it is relatively clear which thing applies to them.

currently, basically all main doc links are changed (quickstarts,userguide,developerguide,configguide,etc), so this is a pretty big change. of course, change can be good, but I do think stability is important because we link to docs from external sites. one way to ensure more stability is to use versioned docs but this will generate lots of contents in the s3 bucket and needs a bit of dev work to put in place. just from browsing, the docker and azure links do not have versions in their url but the aws does, pinned to latest (which means we would assume that link is somewhat stable)

[carolinebridge]

Most links have been reverted back and guides re-consolidated.

Changes that have been maintained thus far that differs from current docs state:

• developer guide is split into three pages: developer_guide, devguide_config, and devguide_pluggable_elements ; named "Core concepts and intro to pluggable elements", "Understanding the configuration model" and "Creating your own pluggable elements" respectively
• pages that were formerly quickstart_gui, quickstart_cli, and superquickstart_web have been moved into User tutorials under config_gui and config_cli respectively (superquickstart has been absorbed into config_cli) ; named "Configure JBrowse using the GUI" and "Configure JBrowse using the CLI" respectively

These changes from the current docs state are those that I feel most profoundly enhance discoverability and clarity of our documentation without breaking existing links. That being said, I am still open to discussion on these points, and any others e.g. rewrites in the docs, tutorials, etc.

[cmdcolin]

made some misc updates here

https://github.com/GMOD/jbrowse-components/tree/docs-updates-merge-main

• merged origin/main
• fixed or silenced a message complaining that miniplugins was not found (changed @site/src/components/MiniPlugins to ../../components/MiniPlugins)
• Restored urlparams.md
• Renamed userguide->user_guide
• Moved urlparams and API into the developer guides subsection. Not sure if that is helpful, but could reduces the cognitive load of lots of sidebar content

[cmdcolin]

brief chat with @carolinebridge-oicr and i think this pr can be merged as is but we may move towards broken up pages in a next iteration, i do think that there is some value to breaking the pages up :)