Ensure core settings are documented

[kdmccormick]

Old Context

Tutor core and plugins both expose configurable settings (which are used to render the Tutor environment). Tutor's docs helpfully describe many/most of the core ones, but I do not see a way for plugins to programatically document their settings other than to write them into their README.

Would it be helpful if tutor config could list all y config settings, both for core and plugins, along with a description of each setting?

New Context

Based on the discussion below, we're going to stick with manual documentation for config settings.

Acceptance

• Document existing core config settings in the Tutor docs if they aren't already.
• (Refrain from adding any automated tooling unless we find compliance to be an issue)

Follow-up

Create issue(s) to:

• Document any config settings defined by official plugins in their READMEs.
• Add a README section to plugin template repo inviting plugin authors to document the settings that they have defined

[regisb]

Do we need a way to programmatically document settings? I'm not so sure about that. Of course documenting configuration settings and patches is a necessity, but couldn't we simply resort to good old manually written docs? This is what the Django project does with settings for instance.
If we are concerned that some settings or patches may go undocumented, then we can write a simple regex-based unit test.

[kdmccormick]

I think the acceptance criteria here could isometric to that of of https://github.com/overhangio/2u-tutor-adoption/issues/5 :

• describe Tutor settings manually in the official docs
• encourage plugin authors to document their settings in their READMEs
• maybe: add a command line tool to list all available settings
• refrain from adding any automated tooling unless we find compliance to be an issue

[kdmccormick]

@regisb Does that plan sound good to you? ^

[regisb]

Yes, sounds good :)

[Carlos-Muniz]

@regisb @kdmccormick I'll be tackling this ticket if you would like to assign it to me.

[Carlos-Muniz]

@regisb @kdmccormick
I need some help with writing docs for a couple of config parameters:

• OPENEDX_AWS_ACCESS_KEY (default: "")
• OPENEDX_AWS_SECRET_ACCESS_KEY (default: "")
• OPENEDX_CSMH_MYSQL_DATABASE (default: "{{ OPENEDX_MYSQL_DATABASE }}_csmh")
• JWT_COMMON_AUDIENCE (default: "openedx")
• JWT_COMMON_ISSUER (default: "{% if ENABLE_HTTPS %}https{% else %}http{% endif %}://{{ LMS_HOST }}/oauth2")
• JWT_COMMON_SECRET_KEY (default: "{{ OPENEDX_SECRET_KEY }}")

[kdmccormick]

@Carlos-Muniz Here are some resources to help you understand those settings. Although it probably doesn't need to be reflected in the docs, I also tried to explain how those settings are piped through Tutor and manifested in edx-platform.

OPENEDX_AWS_ACCESS_KEY, OPENEDX_AWS_SECRET_ACCESS_KEY

They are used in the auth.yml partial template in order to set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY: https://github.com/overhangio/tutor/blob/c4388e134ca4bf1961b9906dd3fb8600d197f7a5/tutor/templates/apps/openedx/config/partials/auth.yml#L2-L3

The partial template is included into the lms.env.yml and cms.env.yml templates: https://github.com/overhangio/tutor/blob/c4388e134ca4bf1961b9906dd3fb8600d197f7a5/tutor/templates/apps/openedx/config/lms.env.yml#L86

In the openedx (edx-platform) Dockerfile, we copy the output of those templates into the image: https://github.com/overhangio/tutor/blob/bb907b4de36a42de367ee144e7595243c9c323d1/tutor/templates/build/openedx/Dockerfile#L168

...and set LMS_CFG and CMS_CFG to point to them: https://github.com/overhangio/tutor/blob/5b5700eff4fd5f15c95421caca62c365c93a1c9c/tutor/templates/build/openedx/Dockerfile#L169-L170

...so that they are loaded as Django settings into edx-platform's (lms,cms)/envs/production.py: https://github.com/openedx/edx-platform/blob/9e08c5e3d2d80d2da34240862aaa7193ea9fcbe4/lms/envs/production.py#L63-L91 .

So, we know that these Tutor setting are just piped into LMS/CMS Django settings. Googling '"AWS_SECRET_ACCESS_KEY django setting', I find the django-storages library docs for Amazon S3 settings: https://django-storages.readthedocs.io/en/latest/backends/amazon-S3.html#settings

OPENEDX_CSMH_MYSQL_DATABASE

"CSMH" stands for Courseware Student-Module History. You can read some of the context here, particularly in the "Why Is A New Database Needed?" section: https://edx.readthedocs.io/projects/open-edx-release-notes/en/latest/CSMHE/CSMHE_overview.html

This setting allows you to configure the name of that separate database which will contain the potentially-gigantic CSMH table.

JWT_COMMON_AUDIENCE, JWT_COMMON_ISSUER, JWT_COMMON_SECRET_KEY

These are rendered into the JWT_AUTH dictionary within the common_all.py partial template, using keys JWT_AUDIENCE, JWT_ISSUER, and JWT_SECRET_KEY: https://github.com/overhangio/tutor/blob/2af147f9324bbf883bd158d9b08c2490d9f6595c/tutor/templates/apps/openedx/settings/partials/common_all.py#L125-L127

...which is included into common_(lms,cms).py, which in turn is included into Tutor's (lms,cms)/production.py files: https://github.com/overhangio/tutor/blob/f6b78265200a3d3ca42062ab3051841fe5410809/tutor/templates/apps/openedx/settings/lms/production.py#L5

...which are copied into the openedx Docker image: https://github.com/overhangio/tutor/blob/bb907b4de36a42de367ee144e7595243c9c323d1/tutor/templates/build/openedx/Dockerfile#L172-L173

...and then configured as the the default edx-platform settings: https://github.com/overhangio/tutor/blob/bb907b4de36a42de367ee144e7595243c9c323d1/tutor/templates/build/openedx/Dockerfile#L221

So, similar to the AWS_* settings above, we know that the JWT_* settings are piped into dictionary entries within the JWT_AUTH LMS/CMS Django setting. Googling '"JWT_AUTH" django setting", I land on this page, which has docs for each key: https://jpadilla.github.io/django-rest-framework-jwt/

[Carlos-Muniz]

@regisb @kdmccormick
Are these the plugins that need documentation? Should the documentation be in configuration.rst, or should it be in plugins.rst.

[kdmccormick]

@Carlos-Muniz Yep, those are all the official plugins. For this ticket, though, stick to the ones that add official Open edX components: mfe, forum, notes, discovery, android, xqueue, and ecommerce (roughly in order of decreasing importance). I'll likely open a follow-up ticket for the remaining official plugins.

Since they're plugins, let's keep their settings' documentation out of the core RST docs -- just document them in their corresonding repo's README. The mfe plugin already does this to a fairly solid degree and might be a good source of inspiration for the other plugins.

[kdmccormick]

I split the "document plugin settings" portion of this out into https://github.com/overhangio/2u-tutor-adoption/issues/90