Sphinx nested class rendering.

[hivert]

This patch fixes rendering of nested class in Sage.

The particular metaclass NestedMetaclass we have to use to work around the nested class pickling bug of python get in the way of Sphinx because it change the __name__ of the nested class.
We have to make Sphinx aware of those particular classes and to update its configuration.

I also took the chance to raise a warning if someone forgot to set the metaclass leading to a unpicklable class. Several bug have been found that way. I'll add a ticket for this. Addendum: See #8452 for this.

CC: @mwhansen @nthiery @jhpalmieri

Component: documentation

Keywords: Sphinx, nested classes

Author: Florent Hivert

Reviewer: Mitesh Patel

Merged: sage-4.3.4.alpha1

Issue created by migration from https://trac.sagemath.org/ticket/7448

[mwhansen]

comment:2

See #6664. We need to figure out how to resolve the issues there.

[qed777]

comment:3

Mistaking inner classes for aliased attributes seems likely to be a Sphinx bug that we should report upstream, e.g., to sphinx-dev.

Is there a minimal example we can submit that reproduces the problem?

[hivert]

comment:4

Replying to @qed777:

Mistaking inner classes for aliased attributes seems likely to be a Sphinx bug that we should report upstream, e.g., to sphinx-dev.

Is there a minimal example we can submit that reproduces the problem?

I've made some experiments. Actually it seems that the problem is a bad interaction between sphinx and the particular metaclass NestedMetaclass we have to use to work around the nested class pickling bug of python. If you apply the attached patch, you'll see that TestParent1 is correctly rendered whereas the other parent are not. I think this is a lead which should be followed.

[hivert]

Patch to experiment the interaction Sphinx/NestedMetaclass

[hivert]

comment:5

Attachment: trac_7448-nested_class_sphinx_exper-fh.patch.gz

I've made some experiments. Actually it seems that the problem is a bad interaction between sphinx and the particular metaclass NestedMetaclass we have to use to work around the nested class pickling bug of python. If you apply the attached patch, you'll see that TestParent1 is correctly rendered whereas the other parent are not. I think this is a lead which should be followed.

More info on this: to workaround python's nested class pickle bug we put any class which contain a nested class into NestedMetaclass. The main purpose of this metaclass is to change the class __name__ with the help of the function
modify_for_nested_pickle. As a result sphinx has the impression that the class is an alias. Demonstration: if I comment line 112 of nested_class.py

diff --git a/sage/misc/nested_class.py b/sage/misc/nested_class.py
--- a/sage/misc/nested_class.py
+++ b/sage/misc/nested_class.py
@@ -108,7 +108,7 @@ def modify_for_nested_pickle(cls, name_p
             if v.__name__ == name and v.__module__ == module.__name__ and getattr(module, name, None) is not v:
                 # OK, probably this is a nested class.
                 dotted_name = name_prefix + '.' + name
-                v.__name__ = dotted_name
+                # v.__name__ = dotted_name
                 setattr(module, dotted_name, v)
                 modify_for_nested_pickle(v, dotted_name, module)

Then everything works fine. Any idea to solve this ?

[hivert]

comment:6

Things are progressing with the help of Mike Hansen on irc: The submitted patch to autodoc.py partially solve the problem. Now each nested class is documented twice ! I'm trying to remove one.

[hivert]

Author: Florent Hivert

[hivert]

comment:7

This should solve the problem:
Applying

autodoc.py.patch

to

Sphinx-0.6.3-py2.6.egg/sphinx/ext/autodoc.py

and trac_7448-nested_class_sphinx-fh.patch
should solve the problem.