On Tuesday, April 10, 2012 3:45:01 PM UTC-7, Nicolas M. Thiéry wrote:
>
> On Mon, Apr 09, 2012 at 05:03:08PM -0700, John H Palmieri wrote:
> > I agree that it would be nice if __*__ and _*_ showed up in the
> > documentation.
> > David
> >
> > Then run "sage --docbuild -u reference html". According to "sage
> > --docbuild help":
> >
> > -u, --underscore include variables prefixed with '_' in
> reference
> > manual; may be slow, may fail for PDF output
> >
> > (It should probably say something other than "variables" here.") This
> > increases the size of the reference manual, slows down the build (as
> > noted), and will likely produce many warnings, since docstrings for
> > underscore methods haven't received as much attention as for
> non-private
> > methods, so many of them are misformatted.
>
> Not quite: I only want the .__*__ and ._*_ methods. Not the other ._*,
> for which it was indeed settled that there were too many of them.
>
As an experiment, in the following lines from devel/doc/common/conf.py
if 'SAGE_DOC_UNDERSCORE' in os.environ:
if name.split('.')[-1].startswith('_'):
return False
-- "False" means that we should *not* skip these methods when building the
reference manual -- I changed the second line to
if name.split('.')[-1].startswith('_') and
name.split('.')[-1].endswith('_'):
Then I built the reference manual with the -u flag. It took a little
longer, not much (13 minutes vs. 11 minutes). The html documentation was a
bit larger (215M vs. 177M). Sphinx produced 145 warnings. Except for the
warnings, this is not too bad. If someone (not me!) wants to fix these
warnings, I wouldn't mind including these methods (etc.) in the reference
manual.
(I didn't bother trying to build the pdf version of the reference manual,
because isn't it too unwieldy already, even without these extra methods?)
--
John
--
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
