I assume there's no way to automatically add only those private functions that are referred to within Sphinx?
If not, I think having "_included_private_doc_" class attribute as a list of strings giving the private functions to include sounds like a fine solution. David On Sun, Apr 8, 2012 at 11:24, Florent Hivert <florent.hiv...@lri.fr> wrote: > Hi there, > > Thanks to the newly added '--warn-links' option to sage doc builder, > several patch are currently working to remove broken links in the doc. See > eg. #12810, #12767. However, there is still the problem of private methods > (the one starting with "_"). I understand that we don't want to include > them > systematically, because they don't always interest the user, they render > the > documentation much too big and make it unreadable. However, in several > places > of the doc, in particular in files dealing with infrastructure we > definitely > want to include some private members. This was asked to me at least by > three > different people. > > When you are in a module, there is a standard Sphinx way (an attribute > called > "__all__") which tells which member of the module you want to appear in the > documentation. It is only used in Sphinx in a couple of places. > > Unfortunately, it only works in a module but not in a class. I could easily > make it work in class by patching "sage_autodoc.py" but I don't think this > is > exactly what we want. I think what we really want is a specific sage > private > attribute to classes say "_included_private_doc_" which lists the private > method we want always see included in the doc. The non-private methods > will be > included as usual. > > Note that this could be done in a more standard ways: we could edit the > autogenerated ".rst" file and tell sphinx which members we want to > include. I > don't think this would be as easy as the solution I suggested before: > Sphinx > asks to write every member we want to include (not only the private ones). > > I'm Ok to provide solution; I've a prototype on the sage-combinat queue > which > seems to be working. I've to test it more before inclusion in Sage. We just > need to decide if the solution I'm suggestion is Ok and to agree on the > name > (I'm currently using '__all__' which seems bad to me). > > Any idea or better suggestion ? > > Cheers, > > Florent > > -- > To post to this group, send an email to sage-devel@googlegroups.com > To unsubscribe from this group, send an email to > sage-devel+unsubscr...@googlegroups.com > For more options, visit this group at > http://groups.google.com/group/sage-devel > URL: http://www.sagemath.org > -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
