librelist archives

« back to archive

New flask extension: Flask-Autodoc

New flask extension: Flask-Autodoc

From:
Arnaud Coomans
Date:
2013-10-01 @ 05:56
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:
https://pypi.python.org/pypi?:action=display&name=Flask-Autodoc&version=0.1.1

Please give me feedback, or better, pull requests through Github:
https://github.com/acoomans/flask-autodoc

Sincerely,
Arnaud

Re: [flask] New flask extension: Flask-Autodoc

From:
Stefane Fermigier
Date:
2013-10-01 @ 06:24
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.

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).

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.

Regards,

  S.

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: 
https://pypi.python.org/pypi?:action=display&name=Flask-Autodoc&version=0.1.1
> 
> Please give me feedback, or better, pull requests through Github: 
https://github.com/acoomans/flask-autodoc
> 
> Sincerely,
> Arnaud


--
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 - 
http://www.gt-logiciel-libre.org/
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


Re: [flask] New flask extension: Flask-Autodoc

From:
Arnaud Coomans
Date:
2013-10-01 @ 14:00
Hi Stefane,

Thanks for your feedback, it's really appreciated!

On 01 Oct 2013, at 15:24, Stefane Fermigier <sfermigier@abilian.com> 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!

> 
> Regards,
> 
>   S.
> 
> 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: 
https://pypi.python.org/pypi?:action=display&name=Flask-Autodoc&version=0.1.1
>> 
>> Please give me feedback, or better, pull requests through Github: 
https://github.com/acoomans/flask-autodoc
>> 
>> Sincerely,
>> Arnaud
> 
> 
> --
> 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 -& 
nbsp;http://www.gt-logiciel-libre.org/
> 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
> 
> 
>