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
  • (routing/toctree) Endpoints
    • How routing works
      • overview of a request for a page
      • overview of an api call
    • (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
  • Security
    • (routers/auth.py) Shared authentication -- same password, different cookies. (Does this belong in another section?)
  • (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
• 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? - I think that is fine initially. But I do have a project that a student group may pick up for the summer that would modify the registration process slightly but would I think make it more clear.

1. Register for an account on Runestone
2. Are you an instructor? a. Give us more information to verify that you are. a. What course do you want to create?
3. Are you a student? a. What course do you want to register for?

The page to select the course will be much more user friendly and organized that just giving a list of values to type into a registration field.