pirant
pirant copied to clipboard
aayush26
Generate Docs
One awesome (but sometimes painful) way of creating documentation in python is with sphinx. The cool thing about it is that it can be hosted in https://readthedocs.org/, so it will look like this: http://docs.readthedocs.io/en/latest/getting_started.html. readthedocs works like travis, so the server will build the documentation every time we push to github.
Maybe we can wait until there is actually something to document, but I leave this here for the future
@joserc87 Cool. Great idea. Lets push some more codes and release a production ready version 1. Then we will look into it.
Barebones done. working url for documentation: http://pirant.readthedocs.io
I have added docstrings in my PR #29 - you could auto-generate the API reference with autodocs, if you guys are using sphinx ?
@nlsdfnbch Thanks for adding docstrings. We are using sphinx and hosting it at readthedoc, though its in very initial stage with almost no documentation. All setup has been done. Your PR seems to add good amount of docstring. I am looking into it.
I am looking for someone who likes and writes good documentation ( I really wonder if I can find one though considering everyone hate documenting and I am very poor in it.) Including Getting started and code examples. Most probably, I will end up doing it. Haha..
@aayush26 , luckily you'll only need to document the public methods properly (with examples and such). The private methods and objects don't need that sort of documentation - usually a brief explanation of params and their expected type is sufficient.
Since you guys are using sphinx then, you should be able to build the documentation (from the docstrings) doing this:
.. automodule:pirant
:members:
.. automodule:pirant.apps
:members:
etc
That would allow you to write the documentation directly in the source code as well, sparing you the need to maintain two documentations.
Hello: I'd like to help the community with some doc help. WHat are you looking for at this point?
@radhikasundararaman24 Sure. You can look the existing docstrings and check if they are generating docs correctly. If no, you can add automodule:* as mentioned above to create docs.