Compute RP feedback - improve ReadTheDocs web navigation of docs

[mollycule]

This PR is meant to satisfy #67 for improving navigation of roadmaps and their grouped tasks by utilizing toctree.

Additionally, some auxiliary improvements have been included in this PR:

• rename ReadtheDocs project from readthedocs.access-ci.org --> "ACCESS Integration Roadmaps"
• convert index.rst and tasks/index.rst from rst --> md
• simplify folder structure for Roadmap Tracks

I had wanted to use the toctree :numbered: feature rather than hard-coding the numbers for Roadmap tasks, but I wasn't able to figure out how to get the automatic numbering to be accurate/consistent. This might be due to the fact that multiple Roadmap Tracks reference to the same task file. I've decided that it can be out of the scope of this PR, but I'm happy to incorporate a solution if anyone knows what's needed!

NOTE: This PR is scoped for all current Roadmap Tracks (Cloud, Compute, Storage, Science Gateways, and Online Services).

[mollycule]

This build appears to fail because .readthedocs.yaml has sphinx:fail_on_warning set to true, and it's failing on this warning: checking consistency... /home/docs/checkouts/readthedocs.org/user_builds/integration-roadmaps/checkouts/68/docs/source/tasks/index.md: WARNING: document isn't included in any toctree

I've already verified my changes in my test environment where warnings don't cause build failures.

I had intentionally excluded tasks/index.md from the higher-level index.md's toctrees because it messes up the navigation of Roadmap tasks within the "parent" Roadmap Track. When tasks/index.md was included, clicking a Roadmap task link would cause the desired sidebar navigation of Roadmap Track/Roadmap Task (e.g. Cloud -> Phases -> Integration phase -> 6. Coordination Knowledge Base) to be this broken sidebar navigation of showing all the Roadmap Tasks (e.g. ACCESS Integration Roadmap Tasks/Knowledge Base v2). The reason I still want the files included somewhere (i.e in tasks/index.md) is because I want to make sure that all Roadmap Tasks are available for searching purposes without getting in the way of the sidebar navigation.

If anyone has a clue how to circumvent this issue without setting sphinx:fail_on_warning to false, then I'd appreciate the help!

One option could potentially be to remove the glob in tasks/index.md and logically separate tasks that are references in Roadmap Tracks (e.g. Knowledge_Base_v1.md) from tasks that aren't referenced in any Roadmap Tracks (e.g Netsage_Integration_v1.md), but that would be yet another thing to maintain and could accidentally result in duplicate Tasks.

[mollycule]

@c-mart an additional pair of eyes would be great!

Note: this issue may be resolved with the recent discussion to switch from sphinx to mkdocs.

[c-mart]

Tried this out locally to understand (I'm new to reST toctree). Comparison screenshots have main on left, this branch on right.

The navigation pane now goes deeper, showing each task on the left-hand side.

What happens after I click on a task? On main, the navigation ends up in the "All Roadmap Tasks" top-level tree, into a list of tasks. With this branch, the nav collapses entirely for me.

To fix the build warning, I tried adding docs/source/tasks/index.md to the toctree in /docs/source/index.md. This didn't appear to change the behavior when clicking on a task -- same as the right-hand window in screenshots above. (Am I looking in the wrong place?)

Things that me unsure how to proceed:

• We may switch from Sphinx to MkDocs, which has an explicitly-defined navigation layout instead of dynamically-generated navigation from the toctree. Less magic, might be an easier time for us.
• It's unclear to me exactly what #67 is asking for.
• We're refactoring roadmaps into badges anyway.

How about this plan?

• Leave this PR be for now.
• Separate, tightly-scoped PR that converts the remaining reST source files to Markdown. (It sounds like we want this regardless of which site generator we use.)
• Separate PR (building on above) that explores replacing Sphinx with MkDocs.
• Evaluate with group, decide how to proceed.

[mollycule]

@c-mart, thank you for the detailed response! Your plan looks great, and I'll begin the process of breaking components into separate PR(s).

67 is the RP feedback that was provided. I've interpreted it to be similar to a Jira User Story and this subsequent PR (#68) being similar to the technical efforts to try to meet the expectations of the feedback.

I understand that the badging initiative will eventually deprecate a decent bit of this documentation organizing effort, but I believe we should still make strides to improving the current roadmap method to support current RPs that are actively integrating into ACCESS.