feat: add demonstration of Sphinx documentation system

[mattmazzola]

⚠️ This PR is not intended to be merged directly, but to demonstrate documentation from our fork ⚠️

Issue

Current documentation in Metaseq repo is very minimal.

• Given the complexity of pipeline and various entry points it can be difficult for newcomers to get started
• Documentation features are limited by Github's rendering of Markdown files viewed within the repository
• Documentation isn't centrally located
  • It is nice to co-locate doc files near the content they are documenting by placing it near in file system, but this can make it hard to understand the bigger picture which connects all information

We also had the intention of publishing results to 3rd parties and wanted the pages to look more professional than viewing a file of repository.

Solution

• Use Sphinx python documentation generation system

  • Sphinx uses the reStructuredText markup language by default, and can read MyST markdown via third-party extensions

  • Centrally locates documentation (Although can still link to markdown files in repo if desired)
  • Can generate documentation from code (and docstrings)
  • Can render Mermaid diagrams (Although I think Github can do that too now)

Testing steps

There were some errors during docs generation since we don't have correct dependencies and can't properly embed/generate docs from metaseq.cli.validate but the concept should work for a real Metaseq environment

Visuals

Screenshot of Demo Docs

Video

2023-06-09_09-29-46.mp4

Development on Documentation

Terminal A:

make serve

(Open URL and view index.html)

Terminal B:

make watch

Regenerates documentation after file changes

Related to #726

Mentioning @tupini07 for awareness and possible assistance to answer questions

[mattmazzola]

As you can see in the video of PR description, our documentation has many more files, but I removed almost all of them except for this PR

This folder to demonstrates how to use rST and markdown syntax within Sphinx to achieve what you want.