Documentation generator?

[cskilbeck]

It would be really useful to have a function which outputs some structured data which describes the schema, this could then be converted into HTML or whatever.

[tusharmakkar08]

Can you be more specific about this issue? What exactly is the input and expected output?

[cskilbeck]

Hi, Before I discovered Voluptuous I wrote a simple parameter validation layer myself which is far less capable and I'd like to move over to Voluptuous but the one feature it doesn't have is doc generation. See here: https://dev.dogstarcloud.com/docs/ This page was created (mostly) automatically - the parameter specifications are captured and the HTML is generated with some simple code. It seems like it would be possible to do something similar with Voluptuous, I'd do it myself but it would probably be much quicker if someone with prior knowledge of the code base did it. What do you think? Thanks, Charlie.

On Thu, Dec 1, 2016, at 03:36 PM, Tushar Makkar wrote: Can you be more specific about this issue? What exactly is the input and expected output? — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub[1], or mute the thread[2].

Links: 1. #251 (comment) 2. https://github.com/notifications/unsubscribe-auth/AEw3K7Q0z0rsVxo-JdJTtLCe4OpAP0MNks5rDuligaJpZM4LAVMw

[tusharmakkar08]

Hey @cskilbeck

I lost this conversation somehow. Sorry for that.

Ohh.. You mean that schema is converted to HTML format, which will enhance its accessibility. You can start off with writing a separate file for documentation generation which can use templating engine like Jinja2, which takes in input as a schema and yields out HTML content for the same. I can help you off with the integration bit for it.

Thanks

[alecthomas]

No response, closing.

[romgar]

Sad this issue has been closed :'(

A generated documentation would definitely be a killer feature for a library like voluptuous.

We currently have an API and define data validation thanks to voluptuous. Exposing the schema to potential consumers of our API would be awesome.

[xeor]

bump.. Much needed

[tusharmakkar08]

Reopening it ..

@xeor @romgar : Are you interested in developing this up?

Thanks.

[xeor]

@romgar wanna go for it?
If not, I can give this one a try, just give me a couple of weeks to finish up another project :)

[romgar]

I won't have enough time for it unfortunately.
And we created a new version of our API following the OpenAPI specification, with a really nice ecosystem around it.
For example, you can validate your data against the schema in python thanks to flex, and a lot of tools exist to generate the documentation directly from the schema (I currently use StopLight, not free but full of functionalities, and free alternatives also exist).

[svisser]

Here's a project that aims to do that: https://github.com/balloob/voluptuous-serialize.

It may make sense to develop such a project outside of the voluptuous project so that it can have its own version numbers and release schedule?

[rmorshea]

Not sure if this addresses the issue, but I wrote something simple that makes it possible to document schemas with sphinx:

class User(Model):
    username: str = Length(max=20)  #: The username
    bio: str = Any(None, Length(max=500))  #: The user's background information (optional).

u = User(username="me", bio="I'm from Timbuktu") 
print(u.username)
print(u["bio"])

Sphinx understands the #: comments as attribute docstrings. For longer descriptions you can put normal """ docstrings below the attribute assignment.