Re: [flask] New flask extension: Flask-Autodoc
- Arnaud Coomans
- 2013-10-01 @ 14:00
Thanks for your feedback, it's really appreciated!
On 01 Oct 2013, at 15:24, Stefane Fermigier <firstname.lastname@example.org> wrote:
> Thanks Arnaud.
> I have some comments / questions:
> 1. I don't understand what the 'teardown' method does. It doesn't have
side effects and returns nothing.
It comes straight from the Flask extension example.
You're probably right, I can get rid of this method.
> 2. I don't really like the idea of having to annotate the functions to
have them documented by autodoc.
> I'd rather have a way to autogenerate the doc for all endpoints (and of
course keep the option of explicit annotations for people with a different
opinion as mine).
That is what I wanted and what I did in the first place (in the prototype,
before the project was put under git).
Then I changed its behavior because I felt uncomfortable having
_everything_ documented by default. It's nice when you start developing
but you probably don't want to expose every endpoint in production.
Of course this is open for discussion. I hope to get more opinions on this.
> 3. For similar reasons, I'd rather have the 'group' metadata managed by
the docstring (using, for instance, a reStructuredText metadata directive)
that by explicit annotation.
That's great! I didn't know this was possible. Thanks for pointing it out!
> On Oct 1, 2013, at 7:56 AM, Arnaud Coomans wrote:
>> Hi everyone,
>> I just made an Flask extension to automatically create documentation
for your endpoints based on the routes, function arguments and docstring.
This can be particularly useful for developing APIs based on Flask.
>> The extension can be found on PyPi:
>> Please give me feedback, or better, pull requests through Github:
> Stefane Fermigier - http://fermigier.com/ -
http://twitter.com/sfermigier - http://linkedin.com/in/sfermigier
> Founder & CEO, Abilian - Enterprise Social Software - http://www.abilian.com/
> Co-Founder and Chairman, Systematic Free&OSS Special Interest Group -&
> Co-Founder & Vice-President, National Council for Free&OSS - http://cnll.fr/
> Vice President, Open World Forum 2013 - http://openworldforum.org/
> "Well done is better than well said." - Benjamin Franklin
> "There's no such thing as can't. You always have a choice." - Ken Gor
> "Le vrai courage, c'est de faire ce qui est juste." - Dr Benjamin Justice