Adds docson

[gidsi]

I would like to add some dynamic documentation for the schemas. They are linkable and also integratable.

The system behind is is docson.

[dbrgn]

Isn't this essentially what our API documentation on the website already shows?

[gidsi]

Isn't this essentially what our API documentation on the website already shows?

Yes, and we could fully replace it with this (i've tested the integreatability locally, it's quite nice), which will move the ownership of the documentation to the, for me, right place. Additionally we could also show what the next version will look like.

[dbrgn]

Does it look like this official example? Because I don't really find that easier to read, on the contrary :slightly_smiling_face:

But maybe that example just looks confusing because it's trying to show off all supported features.

[gidsi]

Does it look like this official example? Because I don't really find that easier to read, on the contrary slightly_smiling_face

But maybe that example just looks confusing because it's trying to show off all supported features.

Give me a sec, i will throw something together.

[gidsi]

Does it look like this official example? Because I don't really find that easier to read, on the contrary slightly_smiling_face But maybe that example just looks confusing because it's trying to show off all supported features.

Give me a sec, i will throw something together.

Easier then i thought: http://lbovet.github.io/docson/#https://raw.githubusercontent.com/SpaceApi/schema/master/14-draft.json

Keep in mind that you can still style the whole thing and this is just the "default" and it already gets a lot better having this on a proper website instead of just a single element.

[dbrgn]

Where do we see whether fields are required?

I just wonder, if we already have a system where we can generate HTML from a schema, and if we have that already integrated into the website, why should we use another one and spend effort again to style that until it suits our needs? Especially since it's an external system that adds more dependencies (=more complexity to maintain) and needs more infrastructure (CI, docker images that need to be kept up to date, etc).

Right now I find the docson output not readable at all and don't think the result is worth the added effort. @rnestler what do you think?

[gidsi]

Where do we see whether fields are required?

Right now required fields are displayed in bold.

I just wonder, if we already have a system where we can generate HTML from a schema, and if we have that already integrated into the website, why should we use another one and spend effort again to style that until it suits our needs? Especially since it's an external system that adds more dependencies (=more complexity to maintain) and needs more infrastructure (CI, docker images that need to be kept up to date, etc).

The system we have right now is quite basic and needs maintenance too (right now you have to run the generator script manually and we're writing html from python into an lr file). For me generating json-schema documentation is something that other people can do better (making it work with new json-schema versions etc.).

Maintaining CI and Docker container doesn't seem to be a lot of work right now (compared to maintaining the software parts we have).

I'm not bound to docson, was just the first thing i found that does the job, is maintained and easy to integrate. I've also tried json-schema-for-humans, jsonschema2md and a few online ones.

[gidsi]

limit work in progress, will come up if its important