Overall documentation structure

User Docs

• Basic installation instructions:
  • pip install the Bookserver
  • Download/unzip zip files for a book. (It would be nice if there's web-based way to do this automatically -- log in as admin, then have a "install book" GUI) (Brad) This is part of the long-term-ish vision of making Runestone more like readthedocs. You add a book by adding its repo on github. Webhooks will ensure that pushes to the repo result in rebuilds.
  • Run the server.
• Advanced installation instructions:
  • Run from a Docker image, which includes Postgres, celery, etc.
• Next steps
  • Point to docs for students, instructors, and book authors
  • Provide some additional instructions for managing the server. (What do we have written on this? What are the most common problems? A FAQ would be great.)

To make this happen:

• The bookserver should depend on Runestone Components, since it makes little sense to have a server without books. Or, I suppose we could post pre-built versions of each book? (But this sounds like extra work that needs to be automated.)
• The default install should use sqlite by default, so it's easy to spin up a server without configuring Postgres. (Already done.)
• On startup, the bookserver should scan for books and add a default entry to the courses table for any new books it finds. Or, the web GUI should insert entries into courses after downloading a book.

Developer Docs

• (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.

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

(Brad) 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?
   1. Give us more information to verify that you are.
   2. What course do you want to create?
3. Are you a student?
   1. 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.

(BAJ) Wow, I like it! That would be great. Even a drop-down list of available courses + an option to enter a custom course would help a lot.