Provide JSON Schemas for the different configuration files

[jeliebig]

I've been working on generating JSON schemas for the different configuration files of riptide and would like to get your opinion on a few issues.

I'd like to make the final schemas available to everyone else as well, so they need to be distributed or at least available somewhere.
There are a few ways we could do this, but I'd like to know what you prefer:

• The schema files could be added to the riptide-lib package and referenced from the local filesystem. But that's not exactly ideal since the path would be different for everyone.
• The schema files could be generated by a workflow in riptide-docs and made accessible via "Read the Docs"? That would create stable schema URLs, which could be updated easily as well.
• The schema files could be added to https://www.schemastore.org/? I haven't interacted with schemastore before, so I wouldn't know what that entails exactly, but it's an option nonetheless.

As an aside: How schemas could be referenced

How a schema can be referenced for the configuration files is different for most IDEs and code editors. Most have options to add schema patterns globally or for a certain workspace, but they could also be referenced in the configuration file itself.
This is pretty similar to how it's done for JSON files as well.

In JetBrains IDEs you could add a comment with a $schema keyword:

# $schema: /path/or/url/to/schema.json
project:
[...]

And editors using the yaml-language-server allow you to reference a schema by adding a "modeline":

# yaml-language-server: $schema=/path/or/url/to/schema.json
project:
[...]

Since you already build the whole schema with the python package schema, we can use that as a basis and only need to make a few modifications to generate a nicer schema.
I mostly want to add titles and descriptions to the different properties, so IDEs can show them when I hover over a keyword.

schema already allows you to do that by replacing property keys with Literal objects for example. So the schema method would change like this:

return Schema(
    {
        'proxy': {
        Literal('url', description='Base-URL for the proxy server. The name of projects and/or services will be appended to it.'): str,
        [...]
        },
    [...]
    },
    name='System configuration',
    description='Contains basic settings for Riptide.')

My first idea was to just use the descriptions you already provide in the docstrings, but that would require you to apply changes to two different locations when you want to update them. And it would also make the schema code pretty unreadable.
I also thought about removing them from the docstrings afterwards, especially since some editors don't seem to be able to render the indents and references correctly anyway. But I found out that they are used by the documentation webpage and were probably written only to be rendered there.

So another idea I had was to get the docstrings with inspect.get_doc(self.schema), parse and provide the descriptions in a dict, so they can be added to the schema.
But there are few issues with that. Should you ever change the format of the docstring, the parser would need to be updated as well. Since the docstring is just a comment it's easy to make mistakes and not conform to your own format. And parsing docstrings seems like a bad idea in general, since comments are just not meant to be used like that.

My last idea would be to add a ConfigSchema class for the document class Config, which contains the whole schema as properties with docstrings, so the docstring of Config.schema() could reference/include them instead of duplicating everything. The descriptions and titles of the schema could then also take advantage of the new class and get the strings from it as well.

Which way would you prefer or do you have a better idea?

I'd like to add most of the changes to the schema method of the document classes, so the script which generates the JSON schemas wouldn't need to apply too many changes on top of that.

[theCapypara]

Hi! Thanks for looking into this!

I think the best approach is to ditch the docstring and either use the solution via Literal or an extra schema class like you outlined. I don't have a strong preference for etiher, you can do what feels best to read and work with.

This would be better anyway since I migrated the docs repo from RestructuredText to MysT recently, and the docstring is still rst., which is annoying that I need to mix both now.

In that case riptide-lib would need to be extended to provide one or two modules that render the Schema JSON and also to generate the docuemntation string from the Schema. Then we can load that both into the docs repo, like we already do with the nix module documentation: https://github.com/theCapypara/riptide-all/blob/master/.github/workflows/build-docs.yml

We should also add info about the JSON schemas to the docs.

[theCapypara]

I'll probably also look into creating an LSP server based on this for the new version, that should help writing configuration files even more.