Reuse YAML Schema for documentation

[mahadi]

Hello,

is it possible to reuse the defined schema to generate a user documentation out of it?
I didnt find any options to specify descriptions in the schema options, so i dont think it is supported natively.
But from your experience can you recommend a good worflow to reuse the schema definition for documentation purposes?

Actually i have something like swagger in mind but it seems to be focused on REST APIs.

[crdoconnor]

Hi mahadi, I'm afraid theres nothing built in, although it would be great to have something. I'll have a think about how this could be implemented. One complication is that this would only work on schema objects. Anything involving revalidation would make auto generated docs impossible. Would you mind giving me some details of your use case?

…

On Fri, 10 Mar 2023, 21:32 mahadi, ***@***.***> wrote: Hello, is it possible to reuse the defined schema to generate a user documentation out of it? I didnt find any options to specify descriptions in the schema options, so i dont think it is supported natively. But from your experience can you recommend a good worflow to reuse the schema definition for documentation purposes? Actually i have something like swagger in mind but it seems to be focused on REST APIs. — Reply to this email directly, view it on GitHub <#194>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABOJKNNWZTX6XKCZ7TILZWDW3OFUDANCNFSM6AAAAAAVW5OB3A> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[mahadi]

I started creating an application which shall be easy to configure for the users with a yaml file.
But still the schema needs some documentation which should explain each directive and also give a basic example.
So i thought instead of writing a markdown file separtely it would be great to reuse the schema definition to have it "synced" with the source code.

But this would also have the downside that the definition would get more difficult to read becauseod the documentation next to it.
So i did not yet really decide what would be the best for my use case.

[crdoconnor]

Ok thanks. I'll have a think about how to implement this. I'm thinking validator.documentation() that will output markdown.

…

On Sun, 12 Mar 2023, 12:21 mahadi, ***@***.***> wrote: I started creating an application which shall be easy to configure for the users with a yaml file. But still the schema needs some documentation which should explain each directive and also give a basic example. So i thought instead of writing a markdown file separtely it would be great to reuse the schema definition to have it "synced" with the source code. But this would also have the downside that the definition would get more difficult to read becauseod the documentation next to it. So i did not yet really decide what would be the best for my use case. — Reply to this email directly, view it on GitHub <#194 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABOJKNLTTMHKZZGTCLWMT3TW3WWUJANCNFSM6AAAAAAVW5OB3A> . You are receiving this because you commented.Message ID: ***@***.***>

[DVAlexHiggs]

Why not just use JSON schema?

The python library schema has a built in way to output JSON schemas for the schemas you create there. I really like it, and I'm playing with building something similar around strictyaml, as I prefer StrictYAML for validation (the main differentiation for me being the error messages providing specific line numbers etc)

You can then use something like json-schema-for-humans to output beautiful web pages from the generated JSON schema.