Set up Read The Docs (RTD) Scaffolding and Sketch Docs Website

[jhiemstrawisc]

This sets up some of the basics the SPRAS team has discussed w.r.t. building an official documentation website. I tried to focus on organization/scaffolding for the docs, and not so much the content (which I'm less qualified to write).

I also spent some time putting together some meta docs to explain to others how to write/build/visualize any documentation changes they may choose to make. My hope is that I can help the group with formatting, structure, and hosting, and others can work on the biology

While the changes in this PR function to generate documentation, this doesn't yet address the actual hosting of any documentation, which is outside the scope of what I can accomplish in a PR because it requires RTD account creation and the generation of github secrets.

Here's a screenshot of the landing page these changes currently produce:

[jhiemstrawisc]

A few questions I have at this point:

1. What should we do about the existing doc/ folder, that holds a few markdown files and an image that's linked into the root README? It'll be confusing to have both a doc/ and a docs/ folder, but the contents of doc/ really don't belong in docs/ because they're not built into the website.
2. Funny enough, we already had a lot of the sphinx and read the docs dependencies baked into our pyproject.toml and environment.yml. I suspect these really aren't dependencies unless you're planning to work on documentation. Does anyone foresee any issues moving these into the "optional" sections of those dependency declarations?

[agitter]

The initially structure looks really great. I understand most of the pieces but not necessarily how every single file fits together.

What should we do about the existing doc/ folder

I believe we can convert all the markdown files there into something that would be part of the SPRAS docs. Would that involve converting to rst?

[agitter]

I logged in to readthedocs to see if I could provide authorization. I found that "Read the Docs Community (readthedocs.org)" has already been granted organization access by Reed-CompBio because, as Anna told us, they've used it for other projects.

Then I added a project and found the Reed-CompBio/spras GitHub repo. The setup wants us to add .readthedocs.yaml to the root of this repo. Their example file is

# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Set the OS, Python version, and other tools you might need
build:
  os: ubuntu-24.04
  tools:
    python: "3.13"

# Build documentation in the "docs/" directory with Sphinx
sphinx:
   configuration: docs/conf.py

# Optionally, but recommended,
# declare the Python requirements required to build your documentation
# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
# python:
#    install:
#    - requirements: docs/requirements.txt

Then it tried to run a build, which failed because we are missing that config file.

Config file not found at default path The required .readthedocs.yaml configuration file was not found at repository's root. Learn how to use this file in our [configuration file tutorial](https://docs.readthedocs.io/en/stable/config-file/index.html).

[agitter]

I noticed in the GitHub Actions test that the pip install spras command installed several packages I already expected to be installed in the conda environment:

Successfully installed charset-normalizer-2.0.12 commonmark-0.9.0 jinja2-3.1.0 matplotlib-3.6.0 mock-4.0.0 networkx-2.8 pandas-1.5.0 pip-22.1 recommonmark-0.7.0 requests-2.28.0 scikit-learn-1.2.0 seaborn-0.12.0 spras-0.2.0 spython-0.2.0

We can explore that after merging this. In some cases it looks like minor version differences. conda installs scikit-learn-1.2.2 and pip installs scikit-learn-1.2.0. We pin 1.2.

I'll have to read more about version matching