Skip to content

Commit c0f4bf2

Browse files
bnmnetpbnmnetp
committed
Documentation updates
1 parent d9287bd commit c0f4bf2

19 files changed

+242
-232
lines changed

‎components/rsptx/configuration/core.py

+26-14
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
1-
# ********************************************
2-
# |docname| - Configuring Runestone BookServer
3-
# ********************************************
4-
# Many thing about Runestone BookServer are configurable. This is the place to change
5-
# the configuration for most things. **Private** things should be configured in the
6-
# environment so they are not accidentally committed to Github.
7-
# Defaults provided here may be overridden by environment variables `Per <https://fastapi.tiangolo.com/advanced/settings/>`_.
1+
"""
2+
Configuring Runestone Servers
3+
=============================
4+
5+
Many things about Runestone servers are configurable. This is the place to change
6+
the configuration for most things. **Private** things should be configured in the
7+
environment so they are not accidentally committed to Github.
8+
Defaults provided here may be overridden by environment variables `Per <https://fastapi.tiangolo.com/advanced/settings/>`_.
9+
"""
810
#
911
#
1012
# Imports
@@ -44,13 +46,15 @@ class DatabaseType(Enum):
4446

4547

4648
class Settings(BaseSettings):
47-
# Pydantic provides a wonderful utility to handle settings. The beauty of it
48-
# is that you can specify variables with or without default values, and Pydantic
49-
# will check your environment variables in a case-insensitive way. So that
50-
# if you have ``PROD_DBURL``` set in the environment it will be set as the value
51-
# for ``prod_dburl``` in settings.
52-
# This is a really nice way to keep from
53-
# committing any data you want to keep private.
49+
"""
50+
Pydantic provides a wonderful utility to handle settings. The beauty of it
51+
is that you can specify variables with or without default values, and Pydantic
52+
will check your environment variables in a case-insensitive way. So that
53+
if you have ``PROD_DBURL``` set in the environment it will be set as the value
54+
for ``prod_dburl``` in settings.
55+
This is a really nice way to keep from
56+
committing any data you want to keep private.
57+
"""
5458

5559
class Config:
5660
env_file = ".env"
@@ -148,6 +152,14 @@ def database_type(self) -> DatabaseType:
148152
# This is the private key web2py uses for hashing passwords.
149153
@property
150154
def web2py_private_key(self) -> str:
155+
"""Get the web2py private key.
156+
Prefer to get it from the environment. This allows us to avoid introducing a secret
157+
into the codebase, and it also avoids the need to mount a volume to the container to
158+
store the key in a file.
159+
160+
:return: The web2py private key.
161+
:rtype: str
162+
"""
151163
# Put the cache here; above the def, it produces ``TypeError: unhashable type: 'Settings'``.
152164
@lru_cache
153165
def read_key():

‎components/rsptx/logging/applogger.py

+9-3
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,12 @@
1-
# ************************************************
2-
# |docname| - Configure logging for the BookServer
3-
# ************************************************
1+
"""
2+
Configure logging for the application
3+
=====================================
4+
5+
We keep the logging configuration quite simple as we want everything to go to stdout
6+
so that the docker logs command will work. We also want to be able to set the log level
7+
from the environment variable ``LOG_LEVEL```. The default is ``INFO``.
8+
"""
9+
410
#
511
# Imports
612
# =======

‎components/rsptx/response_helpers/core.py

+26-3
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
1-
# *****************************
2-
# |docname| - Utility functions
3-
# *****************************
1+
"""
2+
Response Helpers for FastAPI
3+
============================
4+
"""
5+
46
#
57
# Imports
68
# =======
@@ -48,6 +50,15 @@ def canonicalize_tz(tstring: str) -> str:
4850
def make_json_response(
4951
status: int = status.HTTP_200_OK, detail: Any = None
5052
) -> JSONResponse:
53+
"""Format a proper JSON response for the API.
54+
55+
:param status: status code of the response, defaults to status.HTTP_200_OK
56+
:type status: int, optional
57+
:param detail: detailed values for the response. Note that the contents of the detail are api independent, but the goal is for all API calls to use this format., defaults to None
58+
:type detail: Any, optional
59+
:return: Return the JSON response object that FastAPI expects.
60+
:rtype: JSONResponse
61+
"""
5162
# content is a required parameter for a JSONResponse
5263
return JSONResponse(
5364
status_code=status, content=jsonable_encoder({"detail": detail})
@@ -62,4 +73,16 @@ def http_422error_detail(
6273
# this is the specific error that was raised. e.g. value_error, type_error, integrity_error.
6374
err_type: str,
6475
) -> List[dict]:
76+
"""The 422 indicates that the request was not formatted correctly. This function provides
77+
the details on what was missing. Based on information we get from Pydantic.
78+
79+
:param loc: the location of the error in the request
80+
:type loc: List[str]
81+
:param msg: A descriptive message about the error.
82+
:type msg: str
83+
:param err_type: the specific error that was raised. e.g. value_error, type_error, integrity_error.
84+
:type err_type: str
85+
:return: A list of dictionaries that can be used to construct the detail for the response.
86+
:rtype: List[dict]
87+
"""
6588
return [{"loc": loc, "msg": msg, "type": err_type}]

‎docs/source/configuration.core.rst

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
configuration.core module
2+
=========================
3+
4+
.. automodule:: configuration.core
5+
:members:
6+
:undoc-members:
7+
:show-inheritance:

‎docs/source/configuration.rst

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
configuration package
2+
=====================
3+
4+
Submodules
5+
----------
6+
7+
.. toctree::
8+
:maxdepth: 4
9+
10+
configuration.core
11+
12+
Module contents
13+
---------------
14+
15+
.. automodule:: configuration
16+
:members:
17+
:undoc-members:
18+
:show-inheritance:

‎docs/source/developing.rst

+3-3
Original file line numberDiff line numberDiff line change
@@ -255,7 +255,7 @@ into your ``poetry shell`` environment you may not want to install this plugin.
255255

256256
.. note:: Host Side Development Notes
257257

258-
When you are starting one or more servers on the host (not in docker) then you will also want to define most of the docker only variables in order for your servers. This is another good reason to use the dot-env plugin for poetry.
258+
When you are starting one or more servers on the host (not in docker) then you will also want to define most of the docker only variables on the host side in order for your servers to be configured properly. This is another good reason to use the dot-env plugin for poetry. You may want to review the section on database environment variables so that you can be set up properly for both development and docker.
259259

260260

261261
Database Setup
@@ -270,7 +270,7 @@ The database is a critical component as it is the glue that ties together the va
270270
Install Postgresql locally
271271
~~~~~~~~~~~~~~~~~~~~~~~~~~
272272

273-
My currently recommended option is number 3. It is what you are probably going to want for production anyway, and I think it gives you the most flexibility for development. I simply installed it on my mac using ``homebrew.`` Linux users can use ``apt`` or whatever. You could even install it in its own `docker container <https://www.baeldung.com/ops/postgresql-docker-setup>`_ and access it as if it was installed natively. It is easy for services running in docker to access the database service running on the host. Using a URL like ``postgresql://user:[email protected]/runestone_dev`` The key there is the ``host.docker.internal`` tells the process running in the container to connect to the host. Running it on the host also makes it far less surprising when you do a rebuild and suddenly your test data is gone because you dumped the image.
273+
My currently recommended option is number 3. It is what you are probably going to want for production anyway, and I think it gives you the most flexibility for development. I simply installed postgresql on my mac using ``homebrew.`` Linux users can use ``apt`` or whatever. You could even install it in its own `docker container <https://www.baeldung.com/ops/postgresql-docker-setup>`_ separate from the composed app and access it as if it was installed natively. It is easy for services running in docker to access the database service running on the host. Using a URL like ``postgresql://user:[email protected]/runestone_dev`` The key there is the ``host.docker.internal`` tells the process running in the container to connect to the host. Running it on the host also makes it far less surprising when you do a rebuild and suddenly your test data is gone because you dumped the image.
274274

275275
You can connect to the database with one of 3 URLs depending on your server configuration (``SERVER_CONFIG``) environment variable - production, development, or test. Test is really just for unit testing. So you will most often want to use development. The environment variables to set are ``DBURL``, ``DEV_DBURL`` or ``TEST_DBURL``.
276276

@@ -290,7 +290,7 @@ Install Postgresql with Docker
290290

291291
If you do not want to install postgresql on your host, or maybe you are just looking to run an installation of Runestone for a couple of courses at your school, here is how to proceed.
292292

293-
1. Before you build the rest of the services run the command ``docker compose -f docker-compose.yml -f author.compose.yml -f db.compose.yml up -d db`` This will start just the database service in the set of composed services. It will also use the default settings for ``POSTGRES_PASSWORD`` (runestone), ``POSTGRES_USER`` (runestone), and ``POSTGRES_DBNAME`` (runestone_dev). You should change these if you are running a production server, but if you are just getting set up for development for the first time just leave them alone.
293+
1. Before you build the rest of the services run the command ``docker compose -f docker-compose.yml -f author.compose.yml -f db.compose.yml up -d db`` This will start just the database service in the set of composed services. It will also use the default settings for ``POSTGRES_PASSWORD`` (runestone), ``POSTGRES_USER`` (runestone), and ``POSTGRES_DB`` (runestone_dev). You should change these if you are running a production server, but if you are just getting set up for development for the first time just leave them alone.
294294
2. Run ``docker compose run rsmanage rsmanage initdb`` This will build the image in docker for the rsmanage command and then run it to create the database and initialize it with the tables and data that you need. You can use ``docker compose run rsmanage rsmanage ...`` to run any of the rsmanage commands in the composed app. If you prefer you can install ``rsmanage`` on the host and run it there, but you will need to be mindful of your environment variables related to the database.
295295
3. You will also need to have the minimal set of environment variables set up. See the section below. If you want to use the defaults you can set ``SERVER_CONFIG`` to ``development`` and ``DEV_DBURL`` to ``postgresql://runestone:runestone@localhost:2345/runestone_dev`` rsmanage will tell you if you are missing any environment variables.
296296
4. You can run ``poetry install --with=dev`` from the top level directory to get a working virtual environment with the ``rsmanage`` command installed. Run ``poetry shell`` to enable the newly created virtual environment. Then try to run ``rsmanage`` You may get some errors about missing database libraries, this is normal, but you will have to read the error messages and install the dependencies if you want to run ``rsmanaage`` directly.

‎docs/source/logging.applogger.rst

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
logging.applogger module
2+
========================
3+
4+
.. automodule:: rsptx.logging.applogger
5+
:members:
6+
:undoc-members:
7+
:show-inheritance:

‎docs/source/logging.core.rst

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
logging.core module
2+
===================
3+
4+
.. automodule:: rsptx.logging.core
5+
:members:
6+
:undoc-members:
7+
:show-inheritance:

‎docs/source/logging.rst

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
logging package
2+
===============
3+
4+
Submodules
5+
----------
6+
7+
.. toctree::
8+
:maxdepth: 4
9+
10+
logging.applogger
11+
logging.core
12+
13+
Module contents
14+
---------------
15+
16+
.. automodule:: rsptx.logging
17+
:members:
18+
:undoc-members:
19+
:show-inheritance:

‎docs/source/modules.rst

+6-1
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,12 @@ Components are shared pieces of code that can be used by multiple bases. They a
1717
.. toctree::
1818
:maxdepth: 4
1919

20-
db
2120
cl_utils
21+
configuration
22+
db
23+
logging
24+
response_helpers
25+
templates
26+
validation
2227

2328
More to come. The API documentation is a work in progress.

‎docs/source/response_helpers.core.rst

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
response\_helpers.core module
2+
=============================
3+
4+
.. automodule:: response_helpers.core
5+
:members:
6+
:undoc-members:
7+
:show-inheritance:

‎docs/source/response_helpers.rst

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
response\_helpers package
2+
=========================
3+
4+
Submodules
5+
----------
6+
7+
.. toctree::
8+
:maxdepth: 4
9+
10+
response_helpers.core
11+
12+
Module contents
13+
---------------
14+
15+
.. automodule:: response_helpers
16+
:members:
17+
:undoc-members:
18+
:show-inheritance:

‎docs/source/templates.rst

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
Templates
2+
=========
3+
4+
Each service may have a folder heirarchy for the Jinja2 templates used in the user interface.
5+
6+
In addition the template component has a common folder ``staticAssets`` for static assets such as images, css and javascript.
7+
The static assets are copied to a static folder in the nginx service during the build process so that nginx can serve them.
8+

‎docs/source/validation.core.rst

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
validation.core module
2+
======================
3+
4+
.. automodule:: validation.core
5+
:members:
6+
:undoc-members:
7+
:show-inheritance:

‎docs/source/validation.rst

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
validation package
2+
==================
3+
4+
Submodules
5+
----------
6+
7+
.. toctree::
8+
:maxdepth: 4
9+
10+
validation.core
11+
validation.schemas
12+
13+
Module contents
14+
---------------
15+
16+
.. automodule:: validation
17+
:members:
18+
:undoc-members:
19+
:show-inheritance:

‎docs/source/validation.schemas.rst

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
validation.schemas module
2+
=========================
3+
4+
.. automodule:: validation.schemas
5+
:members:
6+
:undoc-members:
7+
:show-inheritance:

0 commit comments

Comments
 (0)