Add support for class methods documentation

[StefanoCappellini]

I noticed that the recent commits related to the doc (the ones that try to automate the doc generation, for example #9656 ) break the old doc style. For example, the new ImageDataGenerator page does not document the ImageDataGenerator methods (fit, flow, ...) anymore, we only have some examples.
This PR adds:

• Support for automatic generation of class methods: the classes marked as "classes_with_methods" in the autogen.py file will now have all their methods (obviously not the private or the excluded ones) fully documented
• Some style enrichments in order to make the doc clearer:
  • The documented class methods will have a "method" prepended to their name: this helps distinguish between a method and a module function .
  • All the classes will have a "class" prepended to their name. This names are added using JS and so they will not pollute the menu bar.

I tried to follow a style similar to the one already adopted by the TensorFlow's docs.
In particular:

• I decided to add an additional custom label, "classes_with_methods" in order to be able to decided for which class generate the inner methods docs. At them moment, only the ImageDataGenerator class uses it
• I decided to add the "class" prefix to the class names in order to make easier to distinguish them from simple and plain methods
• The solution makes uses of some tricks in order to add the style. I decided to go for them instead of using some extensions (like for example pymdownx.extra) that would have make the generation more cumbersome.

All these decisions can obviously be changed and improved but I think PR could serve as a good base for future improvements. I have tested the docs on a mac and it is rendered wonderfully.

[fchollet]

This appears to have been overlooked in the recent changes to the preprocessing docs, but we already have a way to document class methods, which we use for instance for here. It involves listing explicitly all methods that you want to generate docs for, in autogen.py.

In order to achieve a mechanism where we automatically document a class by printing 1) the main docstring, 2) individual methods, under a "methods" header, we could reuse much of the same code.

[StefanoCappellini]

@fchollet Thank you for your feedback. As regards the code reuse, yes, I totally agree. However let me explain:

1. I was thinking about completely automated doc generation (so not partial template filling)
2. When you have a page like the one you mentioned (you have only methods from a single class and no functions), yes, I completely agree with you: you can obtain the same effect almost effortless
3. However, you can see some problems when you start having pages, like the "Image Preprocessing" and the "Text Preprocessing" pages, where you have both methods from a single class and functions. Here the process start to become slightly cumbersome:
   • First of all, without any additional style enhancement I think it would be slightly hard to visually distinguish one from the other (yes, functions could have the module name prepended [now not added], but one should check). In particular I find counter-intuitive the idea of having a separating line between the class and its methods. In the old doc we used to have clear dotted list.
   • We could prepend the class name to the methods but then they could be confused with static methods.
   • Both the methods and the functions would be listed in the side menu, without a clear way to distinguish them (this does not happened in the old doc)

• We should enforce a particular order: first the class description, then its methods and then the functions. This could be obtained by sorting all the functions appropriately but I find it pretty error-prone. Yes, you could probably obtain this effect by playing with the "all_module_functions" and "function" parts...

4. Everything breaks whenever we have two classes (obviously with methods to be documented). Here in order to have an automatic class-methods, class-methods and then function interleaving we clearly should change the code, making the class generating its own docs. Then comes the code reuse problem and that's why I put the rendering functions outside. This could be see as feature creeping but comes free trying to solve the first problems.

A possible solution would be to avoid pages mixing methods and functions.
In addition, a good edit of my code would be to allow the filtering of class methods.

Let me know what you think and if there is something I am still missing...

[fchollet]

We can definitely go with your PR. Please first edit it with these 3 things in mind:

• We should generate pure markdown, without HTML/CSS for formatting.
• We don't need to edit the site's CSS.
• We would need the ability to explicitly list which methods we would like to document for a class. For instance, we could add the ability to include dicts in the classes list, with entries "path", "methods". A possible value for "methods" would then be '*' (document all public methods of the class).

[StefanoCappellini]

@fchollet PTAL.

• The generated doc is fully markdown
• It is possible to (I added a comment to explain this syntax):
  • Document only the class: classes = [classA, classB, ...]
  • Document all class methdos: classes = [classA, (classB, "*"), ...]
  • Document some class methdos: classes = [classA, (classB, ["methodA"]), ...]
    The methods are listed as string this to save the typing of full signatures. [we could change this]
• It reuses the old classes field
• It doesn't use external CSS or JS files
• It adds a class label to all the classes (true classes)
• It adds a method label to all the methods
• In order to hide the class labels from the menu and to hide the methods, it extends the default theme

Let me know what you think, thanks.

[StefanoCappellini]

New commit: now it is possible to document class methods:

• Using strings: classes = [classA, (classB, ["methodA"]), ...]
• Using qualified names: classes = [classA, (classB, [module.classB.methodA]), ...]

Probably the second is easy to use during refactoring.

[fchollet]

Please note that the Keras docs (online) are already using a custom theme.

The changes are reasonable, but please handle this feature without changes to the theme/markup, just by generating markdown (in particular, no need for docs/custom_theme/toc.html). E.g. following this model: https://github.com/keras-team/keras/blob/master/docs/templates/models/model.md

[StefanoCappellini]

@fchollet Ok it should be ok now. PTAL again, thanks

[fchollet]

LGTM, thanks

[StefanoCappellini]

Hi @fchollet , I took a look to the 1e82a71 commit and I think that it re-introduces the problems we had before:

1. Now the doc for important utilities (load_img, img_to_array, ...) is missing. Is it intentional? Probably they should be added
2. The horizontal rules separating the class methods makes hard to distinguish them from plain module functions. Probably we should remove them (as in the original commit).

I have already a pull request ready, I just wanted to know if this was intentional, in order to avoid useless PR.
Thank you