docs: add settings documentation to otel.py and generate documentation. Fixes #751

[martynia]

This PR adds missing documentation to otel.py, and add its path to .pre-commit-config.yaml. Documentation for databases is not yet covered since the db system doesn't follow the service settings scheme. Added osx-64 platform to pixi as well.

[read-the-docs-community]

Documentation build overview

📚 diracx | 🛠️ Build #31882363 | 📁 Comparing 4f78de5 against latest (a59841d)

🔍 Preview build

Show files changed (1 files in total): 📝 1 modified | ➕ 0 added | ➖ 0 deleted

File	Status
admin/reference/env-variables/index.html	📝 modified

[fstagni]

This PR recovers the previous documentation for OTEL env variables, but there's a bit more left to be added, that was there previously:

• DIRACX_LEGACY_EXCHANGE_HASHED_API_KEY
• DIRACX_SERVICE_JOBS_ENABLED
• as mentioned, the DB ones

I think those should be recovered in order to consider the original task closed (I understand this makes the task more complex, this was clearly not foreseen).

[aldbr]

ddev:
DB should follow the same pattern as OTEL ones, it's expected to be straightforward.
for the other points, comments are expected to follow.

[chaen]

There's also DIRACX_SERVICE_DOTENV

[chaen]

DIRACX_SERVICE_JOBS_ENABLED, as well as the dbs one are dynamically constructed, so they are easy to dynamically generate for the doc too

https://github.com/DIRACGrid/diracx/blob/main/diracx-routers/src/diracx/routers/factory.py#L355

diracx/diracx-db/src/diracx/db/sql/utils/base.py

Line 134 in b9c7ea3

var_name = f"DIRACX_DB_URL_{entry_point.name.upper()}"

And the OS db as well

diracx/diracx-db/src/diracx/db/os/utils.py

Line 115 in b9c7ea3

var_name = f"DIRACX_OS_DB_{entry_point.name.upper()}"

[martynia]

@chaen generate_setings_doc is a in-house development designed to generate documentation for static-defined variables in classes that inherit from ServiceSettingsBase, which are automatically discovered. How would it cover dynamically defined environment variables?
@ryuwd, since you designed the original system, do you have any hint how to extend it to cover dynamically defined variables?

[aldbr]

@martynia from what I understand after discussing with @chaen, the documentation of these variables can't be auto-generated because they are not relying on the ServiceSettingsBase. Therefore, the documentation simply needs to be hardcoded within the template here: https://github.com/DIRACGrid/diracx/blob/3e495e11893cd14e0a3612ca175e46f16e6ae2d1/docs/admin/reference/env-variables.md.j2

[martynia]

Do expect me to create a setting class and let the template to render it or to put the text directly into the template ?

[aldbr]

Do expect me to create a setting class and let the template to render it or to put the text directly into the template ?

Put the text directly into the template

[fstagni]

Still a draft? @martynia do you need to still add something to this one?

[martynia]

No, it should be ready.

[aldbr]

Why here and not between ##Databases and SandboxStoreSettings?

[martynia]

Currently Database is after SandboxStore, if I put them between, they would belong to SandboxStore. Should those setting have their own section or sections? The dotinv one looks like a major one, shouldn't it go on top ? The same is true with DIRACX_CONFIG_BACKEND_URL. Which section should this go to ?

[aldbr]

The Core section is good. Can you also remove the duplicated DIRACX_SERVICE_DOTENV please?

[martynia]

Done.

[aldbr]

Ok sorry, one last comment, then it's ok 😅
I think we should move DIRACX_SERVICE_JOBS_ENABLED in the Core section and DIRACX_LEGACY_EXCHANGE_HASHED_API_KEY should likely go before SandboxStoreSettings as you did originally (sorry 😅 )