Refactoring documentation

[cosmic-cortex]

No description provided.

[nikolay-bushkov]

Once you decide which style for docstrings to use, I can start refactoring. A look at this http://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html page shouldn't take more than 10 minutes.

[cosmic-cortex]

I took a look, I think we should follow the NumPy style. The reason for this is that the types of arguments can be lengthier (for instance Union[modAL.models.BaseLearner, modAL.models.BaseCommittee]), which is easier to read in the NumPy format.

Another important detail is that I have decided to move the repository to an organizational GitHub account (https://github.com/modAL-python). As a first step, I would like to move the website and API documentation first from the modAL repository itself to a separate one (https://github.com/modAL-python/modAL-python.github.io). I'll add you as a collaborator to this organization, so we can work there together.

[nikolay-bushkov]

Considering docstrings style, if there is type annotation (that I propose to use) in function signatures, then it is redundant to specify types also in docstrings (it will lead to inconvenient duplications which eventually result in inconsistency, http://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#type-annotations).

Considering website, both scikit-learn and PyTorch use Sphinx to build html-pages for their websites, doing commits with these artifacts to special repositories. So, after every change in your documentation sources, you should not forget to rebuild the doc and make a commmit to this special repo. You definetely should set up CI step for this, for instance in Travis. However, readthedocs suggests building documentation automatically after each commit to the repo with sources.
So, if you don't think of making quite a rich website it is possible to use a simpler solution (i.e. readthedocs).

[cosmic-cortex]

What I plan is to combine the modAL tutorial page (https://cosmic-cortex.github.io/modAL/) with the readthedocs API reference (https://modal-python.readthedocs.io/en/latest/) to a single website in the style of the PyTorch documentation. So, I would like to get rid of readthedocs completely and use Sphinx only to build the website. I'll go ahead and try to set this up.

[cosmic-cortex]

I have set up the new website at https://modal-python.github.io, the old website redirects from here also. The new one uses Sphinx instead of Jekyll.

[nikolay-bushkov]

See https://github.com/modAL-python/modAL-python.github.io/compare/notebooks_rendering?expand=1 for the demonstration of my suggestion on dealing with jupyter notebooks (make clean && make html locally). Every time documentation is built, notebooks are executed, and it is an additional way of testing and consistency checking.

This kind of deduplication could become even more efficient if sources for the doc and the code itself are stored in a single repo (i.e. main modAL repo).
I still don't understand why aren't you go with ReadTheDocs instead of GitHub Pages? RTD provides a very convenient way of triggering documentation build with webhooks from GitHub. RTD allows for better URLs (without 'build/html' in it). RTD provides hosting of several versions of the doc simultaneously...

[cosmic-cortex]

Thanks, awesome!

This GitHub pages hosted website is not a final solution. The thing is, I am not very familiar with neither Sphinx nor RTD, so in order to keep the problems manageable, I focused on converting the previous website to Sphinx. Since RTD uses Sphinx, it was the logical thing to do. I'll set up the current website on RTD soon in the main repository, then we add the API reference generated automatically from the docstrings, and finally the modAL main repository can be moved to the organizational account.

[cosmic-cortex]

Ok, I have set up the new RTD site, check it out! I have two issues however.

1. I was unable to find how to link to pages build from a Jupyter notebook from an external page.
2. Since I was unable to link documents from directories higher than the docs, I copied the Jupyter notebooks from the examples folder to docs/source/content/examples.

Do you have a solution in mind for these? Perhaps you have encountered them before.

If you have some progress in refactoring the docstrings, let me know! Now it should be easy to include the documentation in the RTD site.

[nikolay-bushkov]

Yeah, I also faced this problem... my solution was to use '.' instead of 'source' for .rst files... so docs/examples/my_notebook.ipynb looks more discoverable if you surf directly on GitHub.
Moreover, .rst files could be partially rendered by GitHub also.

I haven't started docstrings refactoring yet. Since it is semi-automatic task, I will try to make pull request tomorrow.