Add docstrings to source and use sphinx.ext.autodoc

[AphonicChaos]

As it stands now, all documentation resides in a separate doc directory, which means that users that want to learn the API either have to build documentation from that directory, or visit the online documentation. It would be nice to have documentation within the code and use Sphinx's autodoc feature to generate the API documentation.

Pros:

• more idiomatic: the use of docstrings would allow tools such as pydoc and python's built-in 'help' function to work properly. Furthermore, IDE's that rely on pydocs to present documentation would then function properly.
• more complete documentation: When documenting things by hand, we've purposely left inherited members undocumented to stop from repeating ourselves. By using docstrings in conjunction with the autodoc extension, we could seamlessly integrate inherited member references in the documentation.
• more accurate documentation: In theory, by keeping the documentation right next to the code, we'll be more likely to ensure that the documentation is correct. That is, we won't have to change a separate file when we update the API. This will also allow us to keep track of deprecated members more easily.

Cons:

• makes the code messy: By adding comment strings to every class, member, etc, it makes it harder to skim through the code base.
• resulting output would be different: using autodoc, the site's layout might change dramatically, which is undesired, cosidering how much time we've put into making it look pretty.

The first con is addressed by the use of folding features in your editor of choice. The second isn't a real concern, since you are able to specify which members to include or exclude.

[intjelic]

I'm late on this one because I just noticed this issue (it didn't show up in my Github notifications :/).

I like docstrings and I think we should add them but I'm afraid we won't be able to generate documentation from them since autodoc parses Python sources while we have Cython sources. As for the first con, my IDE (Geany) handles Cython sources so no problems, it will hide them :)

[AphonicChaos]

I have it working fine on my end with cython (v. 0.17.4). I've pushed the autodoc branch demonstrating the beginnings of this in the (incomplete) documentation of the system module. I should note a couple of things:

1. I decided to use field lists [1] for attributes, as I thought it might make the documentation easier to navigate if there was a clear separation of these from methods. It's trivial to get output that looks like the current documentation by adding docstrings where applicable.
2. I didn't convert the entire module, yet.

[1]http://sphinx-doc.org/latest/domains.html#info-field-lists

[AphonicChaos]

@Sonkun could you checkout my autodoc branch, build the docs, and tell me what you think. I'll need your feedback before I am able to continue. Once I know what style of attribute documentation to use, I'll need to wait until the new api is stable enough before continuing as well.

[intjelic]

Autodoc needs your version of pySFML (with docstrings) installed in order to generate the documentation and I have uncommited local changes. I prefer to avoid messing up my workspace before I'm done with those changes so, would you mind sending the result in my mail box ? That'd be helpful :)

By the way, two days ago, I was confused when I read the documentation, I thought I forgot to document save_GL_states(), pop_GL_states() because I expected to find them in sf.RenderWindow class but it was actually documented in sf.RenderTarget, which is fine since sf.RenderWindow inherits from sf.RenderTarget. Maintaining a copy in all inherited classes is unthinkable, so I was wondering if autodoc would solve this problem ?

[AphonicChaos]

Lazy ;-). You could just do:

git stash
git checkout autodoc
cd doc
make html
<webbrowser> build/html/api/system.html
git checkout sfml_latest
git stash pop

Which would store your local changes without committing them, checkout my branch build the documentation, view the documentation, checkout the working dev branch again, then restore your changes. :-)

That said, I'll have the results in your inbox in about a minute.

My solution to issue #51[1](either solution) solves your pop_GL issue.

[1] https://github.com/Sonkun/python-sfml/issues/51#issuecomment-12236787

[AphonicChaos]

Now that sfml_latest is merged, I should be able to work on this again, right?

[intjelic]

Yes :)

[intjelic]

Actually I'm completely in favor of this! Moving to in code documentation will also be a nice opportunity to update the whole documentation all along (I'm sure there are many mistakes, outdated info and inconsistencies). The goal will be to keep the doc in sync with SFML doc. As for the resulting output which might not fit the website theme, I'm sure we can work around that by pre/post processing it or writing an extension, or I don't know but let's not limit ourselves because of that.

However, I'm not familiar with docstrings, pydoc epydoc, autodocs, etc. If you have time, can you explain me shortly their relationship ? I planned to investigate further this feature if no one takes care of it.

PS: I laughed a lot when I reread myself and I told you I didn't want to try your branch because I had local changes xD Of course... git stash, the answer is so obvious now.

[intjelic]

Hmm, just ran across that : http://docs.cython.org/src/userguide/special_methods.html#docstrings

Currently, docstrings are not fully supported in some special methods of extension types. You can place a docstring in the source to serve as a comment, but it won’t show up in the corresponding doc attribute at run time. (This seems to be is a Python limitation – there’s nowhere in the PyTypeObject data structure to put such docstrings.)