Sphinx docs

[benelot]

• Setup sphinx
• Configure the sphinx extensions (comment extraction etc.)
• Format the code comments

I set the format style to numpy style, even though we are still far from it. For this to change I certainly need your help to know which parts have to be commented.

[benelot]

The current state can be uploaded to readthedocs as soon as the repository is public. I think we have to discuss which parts of the library are meant to be public and as such need intensive documentation and which parts are not meant to be internal and thus do need less documentation.

[WillemWybo]

I get an error when trying to compile the sphinx file with sh renew-sphinxdoc.sh

Sphinx error:
master file /Users/wybo/Code/NEAT_public/docs/source/contents.rst not found
make: *** [html] Error 2

[benelot]

weird, there is contents.rst in my folder and it should not be required...can you see what happens if you put an empty contents.rst file into the source folder and run the script again?

[WillemWybo]

If I do that it works. Seems like it does quite a reasonable job already for many functions (although some docstrings seem to be randomly missing, not sure why. It prints a lot of warnings but not necessarily on the missing functions.

[benelot]

Yes, we can work through the warnings and see what they are caused by. If some of your files contain code that is not either in a function, class or if name == 'main': condition, then they might be executed during the sphinx inspection.

[benelot]

Ready to merge!

[WillemWybo]

It seems that getting rid of all non-API modules i.e. neat.tools.kernelextraction or neat.tools.fittools.zerofinding would already remove a lot of the warnings. The website that is rendered for me is also not in the nice format of https://networkx.github.io/documentation/networkx-1.10/overview.html

[benelot]

You are right, we could just exclude that from the documentation, there is a feature for that. The format is just a theme I think, I will check how to do it from the sphinx source they have at their github repository.