On Jun 15, 4:22 pm, John H Palmieri <jhpalmier...@gmail.com> wrote:
> people should be
> checking that the reference manual builds correctly before submitting
> their patches, and then also before submitting positive reviews for
> someone else's patches.
I agree 100% with John's comments on this, and he is right that there
were just three or so warnings on recent releases.
However, I have found the documentation on documentation a bit
scattered and perhaps like others, I have relied too much on just
looking at other's work for guidance, instead of carefully
understanding the nuances before using a feature of ReST, etc.
A few days ago I got halfway through a mock module, which was meant to
be a demonstration of the docstrings, with totally fictitious code,
and instruction about the docstrings contained in the docstrings
themselves. Maybe I'll get back to that in the next few days.
Nick is right that rebuilding the docs is a pain. But as has been
pointed out before, you can rebuild the HTML version once in a new
branch, then only changed files get rebuilt the next time. So as a
habit, now when I build a new branch I automatically rebuild the
reference manual right away. Then once I have some changes, it's
pretty easy to verify the effects.
The effect of
http://trac.sagemath.org/sage_trac/ticket/5653
is to show a *formatted* docstring in the notebook after using the ?
syntax to request it. If this is being done "on-the-fly" shouldn't it
be possible to format a file-at-a-time like you might when testing
localized changes?
Rob
--~--~---------~--~----~------------~-------~--~----~
To post to this group, send email to sage-devel@googlegroups.com
To unsubscribe from this group, send email to
sage-devel-unsubscr...@googlegroups.com
For more options, visit this group at http://groups.google.com/group/sage-devel
URLs: http://www.sagemath.org
-~----------~----~----~----~------~----~------~--~---
