Hi there,
In the process of trying to help fixing broken links in the documentation, I'd
like to share some info and call for a vote:
> > > I think "_included_private_doc_" attribute would be great.
I was writing a patch to allows for including private methods through an
attribute "_included_private_doc_". I just discovered that adding an
"automethod" directive does the job. For example:
.. automethod:: _foo
.. automethod:: _bar
to the end of the main doc of a class document those two special
functions. There is a drawback: The documentation of those methods is placed
here in the given order. So maintaining alphabetic order is at the doc writer
charge. Still I think that this is better than relies on a special sage
attribute. I'm Ok to add this trick to sage devel doc if chosen. So I see two
choices here. Please vote:
[ ] use the Sphinx automethod standard trick.
[ ] use a special Sage attribute "_included_private_doc_"
> > While we are speaking about documentation for ``._*`` methods it, a
> > related question. I consider Python's (``.__*__``) and Sage's
> > (``._*_``) special methods as public, and would be very much in favor
> > of including them by default in the Sphinx documentation.
> >
> > What do you think?
This is a second question: It seems that several Sage developers consider
Python's (``.__*__``) and Sage's (``._*_``) *special* methods as public so
that they should be included in the doc by default. On the opposite, *private*
methods starts by ``_`` but doesn't end with one. I'd like to call a vote for
including them by default in the doc. Some informations (thanks to John H
Palmieri): Compiling the doc with those special functions, take a little
longer, not much (13 minutes vs. 11 minutes). The html documentation was a bit
larger (215M vs. 177M). Sphinx produced 145 warnings which should be fixed.
I see the following choices:
[ ] leave things as they are and rely on the preceding "automethod" or
"_included_private_doc_" trick to document special methods.
[ ] include __*__ and _*_ method by default in the doc.
Thanks for helping having a better doc,
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
