generating docs for views

[Jonathan Vanasco]

I had a small Pyramid project which has grown into a much larger one.

Many Views service multiple Routes (multiple calls to `@view_config()`), typically offering a default HTML version on a "bare" url, and a JSON version with a ".json" suffix to the url.

Documenting these routes has become increasingly burdensome, and I really need to simplify it.  For clarity, the docs are served by the application itself and in a structured format.

Right now I have two types of documentation, and I'd like to consolidate it into a single one.

* The original documentation was built off a Python file, `/lib/docs.py`, which just notes the routes which have JSON endpoints, gives an "about" docstring, and offers a dict about how the route functions (GET vs POST, is it self-documenting, etc).

* As the project progressed, the routes started self-documenting.  Forms were moved to POST only, with GET offering structured details (instructions, required vs optional form elements, etc). Most of this is defined by just returning a dict on GET operations.

I've been trying to figure out the best ways to consolidate this. Perhaps using a custom decorator to declare and track this information into a namespace?

Has anyone else worked on a scenario like this?  How did you handle it?

[Steve Piercy]

My first thought was to use docstrings and Sphinx, but I don't think that's what you want.

It sounds like you want to document an API, something like pyramid_openapi3.

https://github.com/Pylons/pyramid_openapi3/

RealWorld.io app API Demo (it might take a while to start up the app, as it is on-demand only).

https://pyramid-realworld.herokuapp.com/api

--steve

> --
> You received this message because you are subscribed to the Google Groups "pylons-discuss" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to pylons-discus...@googlegroups.com <mailto:pylons-discus...@googlegroups.com>.
> To view this discussion on the web visit https://groups.google.com/d/msgid/pylons-discuss/2cc3c09f-037a-4cf0-9a18-b464540a2305n%40googlegroups.com <https://groups.google.com/d/msgid/pylons-discuss/2cc3c09f-037a-4cf0-9a18-b464540a2305n%40googlegroups.com?utm_medium=email&utm_source=footer>.

[Jonathan Vanasco]

Yes, it is much closer to your pyramid_openapi3 demos.  I'm not sure that project is a good candidate for my requirements or bandwidth, but I will dig into it - thanks!