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
