Overall documentation structure

The code lacks a good big-picture overview of the project. Here's a place to sketch this out together.

• (index.rst) Introduction: the bookserver is the student-facing web app for Runestone.
  • History: it was ported from web2py
  • Design goals: modern, fast, well-architected
    • Use a modern, high-performance web framework (FastAPI). Compare to other options and explain why this.
    • async approach
    • Goal of 100% test coverage (do we agree on this?)
    • Well-documented in the code to enable collaboration / improve code quality
  • How it fits with both Runestone Components and with the web2py instructor interface
  • Roadmap
• (TOC in index.rst) Design overview
  • (db.py?) Database
    • Why sqlalchemy.
      • Why we use the sqlalchemy core instead of the ORM.
      • Use of _and, _or instead of &&, || operators.
    • Async operations
    • (crud.py) Put queries into crud.py
    • (models.py) web2py instructor interface and this app share the database; each "owns" different tables
      • (alembic/) Migration strategy
      • (routers/auth.py) Shared authentication -- same password, different cookies. (Does this belong in another section?)
  • (routing/toctree) Endpoints
    • How routing works
    • (schema.py) Pydantic to validate/convert from HTTP params to Python vars / database access
    • How Runestone Components interacts with endpoints
      • (routine/books.py) Book routing/interaction with a book built with Runestone Components.
      • (routing/assessment.py) Loading data into Runestone Components
      • (routing/rslogging.py) Storing data from Runestone Components
• Testing
  • (test/) Unit test approach
  • (.github/workflow) CI
• Coding style
  • (pyproject.toml) poetry instead of setup.py for dependency management.
  • (pre_commit_hook.py) use black, flake8, mypy?
  • (conf.py) Docs using CodeChat, posted on readthedocs. Hyperlinks between projects.

TODO: currently, only web2py can create a new account, recover passwords, etc. Is this the plan?