Sage: Ticket #7549: Reference manual: class hierarchy, inherited members, underscore variables
https://trac.sagemath.org/ticket/7549
<p>
In the Sage reference manual, it might be useful to
</p>
<ul><li>List the base classes for a class.
</li><li>List inherited members but not their docstrings.
</li><li>Include docstrings for "private" variables (e.g., <code>__init__</code>, <code>_foo</code>).
</li><li>Include inheritance diagrams.
</li></ul><p>
Sphinx extensions of interest: <a class="ext-link" href="http://sphinx.pocoo.org/ext/autodoc.html"><span class="icon"></span>autodoc</a>, <a class="ext-link" href="http://sphinx.pocoo.org/ext/inheritance.html"><span class="icon"></span>inheritance_diagram</a>.
</p>
<p>
See <a class="ext-link" href="http://groups.google.com/group/sage-devel/browse_thread/thread/a34a80097ad47805/2e57eb60d7f9881d?#2e57eb60d7f9881d"><span class="icon"></span>sage-devel</a> for some discussions.
</p>
en-usSagehttps://trac.sagemath.org/chrome/site/logo_sagemath_trac.png
https://trac.sagemath.org/ticket/7549
Trac 1.1.6mpatelSat, 28 Nov 2009 13:55:05 GMTattachment set
https://trac.sagemath.org/ticket/7549
https://trac.sagemath.org/ticket/7549
<ul>
<li><strong>attachment</strong>
set to <em>trac_7549-doc_inheritance_underscore.patch</em>
</li>
</ul>
<p>
Doc build options for inherited members, private variables. Inheritance diagrams. Apply to sage repo.
</p>
TicketmpatelSat, 28 Nov 2009 14:20:34 GMTcc set
https://trac.sagemath.org/ticket/7549#comment:1
https://trac.sagemath.org/ticket/7549#comment:1
<ul>
<li><strong>cc</strong>
<em>hivert</em> <em>jhpalmieri</em> <em>nthiery</em> added
</li>
</ul>
<p>
The patch, which may depend weakly on <a class="closed ticket" href="https://trac.sagemath.org/ticket/7473" title="defect: Sphinx hangs when making a clone (closed: fixed)">#7473</a>'s "builder" patch,
</p>
<ul><li>Adds a <code>sage -docbuild</code> option <code>-i</code> to include inherited members, mostly without docstrings.
</li></ul><ul><li>Adds a <code>sage -docbuild</code> option <code>-u</code> to include "private" variables.
</li></ul><ul><li>Uses Sphinx's <code>:show-inheritance:</code> <a class="ext-link" href="http://sphinx.pocoo.org/ext/autodoc.html"><span class="icon"></span>autodoc</a> option to list the base classes of a class.
</li></ul><ul><li>Sets up Sphinx's <a class="ext-link" href="http://sphinx.pocoo.org/ext/inheritance.html"><span class="icon"></span>inheritance_diagram</a> extension. See <a class="attachment" href="https://trac.sagemath.org/attachment/ticket/6586/inheritance_example.patch" title="Attachment 'inheritance_example.patch' in Ticket #6586">this attachment</a><a class="trac-rawlink" href="https://trac.sagemath.org/raw-attachment/ticket/6586/inheritance_example.patch" title="Download"></a> for an example. This requires <a class="ext-link" href="http://www.graphviz.org/"><span class="icon"></span>Graphviz</a>.
</li></ul><p>
It's likely that the attached patch needs work. In particular, <code>sage.doc.common.conf.process_inherited</code> would benefit from expert intervention.
</p>
<p>
Note: To force a rebuild when toggling <code>-u</code>, add <code>-S -aE</code> to the command-line. For example,
</p>
<pre class="wiki">sage -docbuild reference html -juv3 -S -aE
</pre><p>
Toggling <code>-i</code> should automatically trigger a rebuild.
</p>
TicketmpatelSat, 28 Nov 2009 14:20:52 GMTstatus changed
https://trac.sagemath.org/ticket/7549#comment:2
https://trac.sagemath.org/ticket/7549#comment:2
<ul>
<li><strong>status</strong>
changed from <em>new</em> to <em>needs_review</em>
</li>
</ul>
TicketmpatelSat, 28 Nov 2009 14:30:48 GMT
https://trac.sagemath.org/ticket/7549#comment:3
https://trac.sagemath.org/ticket/7549#comment:3
<p>
Running
</p>
<pre class="wiki">sage -docbuild reference html -juiv3
</pre><p>
I encountered
</p>
<pre class="wiki">reading sources... [ 27%] sage/combinat/lyndon_wordtor_weightedturesnssis_basis
Sphinx error:
'ascii' codec can't decode byte 0xc3 in position 811: ordinal not in range(128)
</pre><p>
Are <a class="closed ticket" href="https://trac.sagemath.org/ticket/6674" title="defect: [with patch, positive review] only use ASCII characters in patches (closed: fixed)">#6674</a> and <a class="closed ticket" href="https://trac.sagemath.org/ticket/6682" title="defect: Support non-ASCII characters in Sage sources (closed: fixed)">#6682</a> relevant?
</p>
TicketmpatelSat, 28 Nov 2009 16:36:05 GMTcc changed
https://trac.sagemath.org/ticket/7549#comment:4
https://trac.sagemath.org/ticket/7549#comment:4
<ul>
<li><strong>cc</strong>
<em>mvngu</em> added
</li>
</ul>
<p>
Putting
</p>
<pre class="wiki"># -*- coding: utf-8 -*-
</pre><p>
at the beginning of <code>sage.combinat.lyndon_word</code> seems to placate Sphinx.
</p>
<p>
Should we do this with every Sage library .py and .pyx file?
</p>
TicketjhpalmieriSun, 29 Nov 2009 05:03:13 GMT
https://trac.sagemath.org/ticket/7549#comment:5
https://trac.sagemath.org/ticket/7549#comment:5
<p>
After adding the "utf-8" line to lyndon_word.py, I got this error:
</p>
<pre class="wiki">reading sources... [ 51%] sage/interfaces/singular ismsm
reST markup error:
/Applications/sage/local/lib/python2.6/site-packages/sage/interfaces/singular.py:docstring of sage.interfaces.singular.SingularFunctionElement._sage_doc_:8: (SEVERE/4) Unexpected section title.
</pre><p>
After fixing this (by ripping out a doctest), things built fine. The html version of the reference manual looks good, and seems to have all of the methods we want, with the inherited ones having no docstrings.
</p>
<p>
Here are some timings on my iMac. Between each build, I removed the directory doc/output:
</p>
<pre class="wiki">sage -docbuild reference html -j 11 minutes
sage -docbuild reference html -ji 22 minutes
sage -docbuild reference html -ju 13 minutes
sage -docbuild reference html -jiu 63 minutes!
</pre><p>
Also
</p>
<pre class="wiki">sage -docbuild reference pdf -iu
</pre><p>
took too long on my iMac. On sage.math, it took about 2 hours and then bombed when trying to run pdflatex: there was one error (a missing "r" before a triple-quoted docstring with backslashes); once this was fixed, it ran for a while and then said
</p>
<pre class="wiki">! TeX capacity exceeded, sorry [pool size=1165810].
</pre><p>
I don't know if there is a way of fixing this, short of <a class="closed ticket" href="https://trac.sagemath.org/ticket/6495" title="enhancement: Build the reference manual incrementally (closed: fixed)">#6495</a>. (I think that the tex installation on sage.math is somewhat old, which doesn't help.)
</p>
TicketjhpalmieriSun, 29 Nov 2009 06:36:56 GMT
https://trac.sagemath.org/ticket/7549#comment:6
https://trac.sagemath.org/ticket/7549#comment:6
<p>
I have yet to succeed making a pdf version of the reference manual. On the two machines I've tried, it takes ages and then crashes with "TeX capacity exceeded". This happened just with the "-i" option on my iMac. I haven't tried all of the possibilities on all of the machines.
</p>
<p>
So I wonder if it makes sense, at least until something like <a class="closed ticket" href="https://trac.sagemath.org/ticket/6495" title="enhancement: Build the reference manual incrementally (closed: fixed)">#6495</a> is in place, to disable the "-i" and "-u" flags for the pdf version of the manual. If not disable them, then at least print a warning saying it's going to take a long time and then might very well crash?
</p>
TicketmpatelSun, 29 Nov 2009 07:54:56 GMT
https://trac.sagemath.org/ticket/7549#comment:7
https://trac.sagemath.org/ticket/7549#comment:7
<p>
Sure, I have no problem with either course. We could also make <code>-i</code> and <code>-u</code> "Advanced" options.
</p>
<p>
Aside: I can't even build the HTML manual with <code>-iu</code> on my local machine. It requires too much memory.
</p>
TicketmpatelSun, 29 Nov 2009 07:59:29 GMT
https://trac.sagemath.org/ticket/7549#comment:8
https://trac.sagemath.org/ticket/7549#comment:8
<p>
Maybe we can use Sphinx's <a class="ext-link" href="http://sphinx.pocoo.org/latest/ext/intersphinx.html"><span class="icon"></span>intersphinx extension</a> to implement a HTML analogue of <a class="closed ticket" href="https://trac.sagemath.org/ticket/6495" title="enhancement: Build the reference manual incrementally (closed: fixed)">#6495</a>?
</p>
TicketmpatelSun, 29 Nov 2009 08:38:33 GMT
https://trac.sagemath.org/ticket/7549#comment:9
https://trac.sagemath.org/ticket/7549#comment:9
<p>
For links to <a class="ext-link" href="http://trac.sagemath.org/sage_trac"><span class="icon"></span>Sage tickets</a>, we could use Sphinx's <a class="ext-link" href="http://sphinx.pocoo.org/latest/ext/extlinks.html"><span class="icon"></span>extlinks extension</a>.
</p>
TickethivertSun, 29 Nov 2009 08:45:13 GMT
https://trac.sagemath.org/ticket/7549#comment:10
https://trac.sagemath.org/ticket/7549#comment:10
<blockquote class="citation">
<p>
Also
</p>
<pre class="wiki">sage -docbuild reference pdf -iu
</pre><p>
took too long on my iMac. On sage.math, it took about 2 hours and then bombed when trying to run pdflatex: there was one error (a missing "r" before a triple-quoted docstring with backslashes); once this was fixed, it ran for a while and then said
</p>
<pre class="wiki">! TeX capacity exceeded, sorry [pool size=1165810].
</pre><p>
I don't know if there is a way of fixing this, short of <a class="closed ticket" href="https://trac.sagemath.org/ticket/6495" title="enhancement: Build the reference manual incrementally (closed: fixed)">#6495</a>. (I think that the tex installation on sage.math is somewhat old, which doesn't help.)
</p>
</blockquote>
<p>
Did you try to launch lex with more memory ? I remember doing a
</p>
<pre class="wiki">export extra_mem_bot=8000000; latex ...
</pre><p>
in a similar situation.
</p>
TicketmpatelSun, 29 Nov 2009 09:03:37 GMTattachment set
https://trac.sagemath.org/ticket/7549
https://trac.sagemath.org/ticket/7549
<ul>
<li><strong>attachment</strong>
set to <em>trac_7549-doc_inheritance_underscore_v2.patch</em>
</li>
</ul>
<p>
Set up intersphinx for Python docs. <em>Replaces</em> previous patch. sage repo.
</p>
TicketmpatelSun, 29 Nov 2009 09:11:42 GMTauthor set
https://trac.sagemath.org/ticket/7549#comment:11
https://trac.sagemath.org/ticket/7549#comment:11
<ul>
<li><strong>author</strong>
set to <em>Mitesh Patel</em>
</li>
</ul>
<p>
Version 2, which replaces the previous patch,
</p>
<ul><li>Enables <code>intersphinx</code> for the Python docs. This is <em>easy</em> to use, e.g.,
<pre class="wiki">For more information, please consult :mod:`subprocess`. Blah, blah, whatever...
</pre></li><li>Adds <code># -*- coding: utf-8 -*-</code> to the top of <code>sage.combinat.lyndon_word</code>.
</li><li>Drops a <code>sage.interfaces.singular.SingularFunctionElement._sage_doc_</code> doctest.
</li><li>Prepares for <code>extlinks</code>. Sphinx 1.0 will include this new extension.
</li></ul>
TicketmpatelSun, 29 Nov 2009 09:29:06 GMT
https://trac.sagemath.org/ticket/7549#comment:12
https://trac.sagemath.org/ticket/7549#comment:12
<p>
It seems that <code>:show-inheritance:</code> shows just the immediate super classes, not the entire hierarchy. I do not know whether this is easy to change.
</p>
TicketmpatelSun, 29 Nov 2009 19:53:39 GMT
https://trac.sagemath.org/ticket/7549#comment:13
https://trac.sagemath.org/ticket/7549#comment:13
<p>
Please see <a class="closed ticket" href="https://trac.sagemath.org/ticket/6495" title="enhancement: Build the reference manual incrementally (closed: fixed)">#6495</a> for progress on incrementally building the reference manual.
</p>
TicketmpatelFri, 04 Dec 2009 08:18:50 GMTattachment set
https://trac.sagemath.org/ticket/7549
https://trac.sagemath.org/ticket/7549
<ul>
<li><strong>attachment</strong>
set to <em>trac_7549-doc_inheritance_underscore_v3.patch</em>
</li>
</ul>
<p>
Rebased for 4.3.alpha1. Replaces previous patches.
</p>
TicketmpatelSun, 06 Dec 2009 00:38:58 GMTcc changed
https://trac.sagemath.org/ticket/7549#comment:14
https://trac.sagemath.org/ticket/7549#comment:14
<ul>
<li><strong>cc</strong>
<em>jason</em> added
</li>
</ul>
<p>
I should add that we can also link directly to <a class="ext-link" href="http://matplotlib.sourceforge.net/contents.html"><span class="icon"></span>matplotlib's docs</a> from the Sage documentation. We just need to update <code>doc.common.conf.intersphinx_mapping</code> (the object inventory is <a class="ext-link" href="http://matplotlib.sourceforge.net/objects.inv"><span class="icon"></span>here</a>). Perhaps there are others of interest in <a class="ext-link" href="http://sphinx.pocoo.org/examples.html"><span class="icon"></span>this list</a>?
</p>
TicketmpatelMon, 01 Feb 2010 09:34:33 GMT
https://trac.sagemath.org/ticket/7549#comment:15
https://trac.sagemath.org/ticket/7549#comment:15
<p>
Against 4.3.2.alpha1:
</p>
<pre class="wiki">applying trac_7549-doc_inheritance_underscore_v3.patch
patching file doc/common/conf.py
Hunk #5 succeeded at 378 with fuzz 2 (offset 5 lines).
now at: trac_7549-doc_inheritance_underscore_v3.patch
</pre><p>
</p>
TicketjhpalmieriTue, 09 Feb 2010 00:02:25 GMT
https://trac.sagemath.org/ticket/7549#comment:16
https://trac.sagemath.org/ticket/7549#comment:16
<p>
Replying to <a class="ticket" href="https://trac.sagemath.org/ticket/7549#comment:14" title="Comment 14">mpatel</a>:
</p>
<blockquote class="citation">
<p>
I should add that we can also link directly to <a class="ext-link" href="http://matplotlib.sourceforge.net/contents.html"><span class="icon"></span>matplotlib's docs</a> from the Sage documentation. We just need to update <code>doc.common.conf.intersphinx_mapping</code> (the object inventory is <a class="ext-link" href="http://matplotlib.sourceforge.net/objects.inv"><span class="icon"></span>here</a>). Perhaps there are others of interest in <a class="ext-link" href="http://sphinx.pocoo.org/examples.html"><span class="icon"></span>this list</a>?
</p>
</blockquote>
<p>
Cython, mpmath, and Sphinx are possibilities. Building Sage shouldn't rely on an internet connection, though, and it seems to me that intersphinx does. So should we also include the object inventories so that we can build the docs without an internet connection? This would rely on keeping those up to date. Can we have it check for an internet connection and fail gracefully if there isn't one?
</p>
<p>
Right now I don't know what I'm doing wrong, but I can't get private methods to be included in the docs. This is with 4.3.2. I put in a print statement in <code>skip_underscore</code> to make sure it was finding the correct methods, and it was. But I didn't see them in the documentation afterwards. I'll try again later.
</p>
TicketmpatelSun, 14 Feb 2010 08:22:07 GMTattachment set
https://trac.sagemath.org/ticket/7549
https://trac.sagemath.org/ticket/7549
<ul>
<li><strong>attachment</strong>
set to <em>trac_7549-doc_inheritance_underscore_v4.patch</em>
</li>
</ul>
<p>
Rebased vs. 4.3.3.alpha0. See comment. Apply only this patch. sage repo.
</p>
TicketmpatelSun, 14 Feb 2010 08:44:20 GMT
https://trac.sagemath.org/ticket/7549#comment:17
https://trac.sagemath.org/ticket/7549#comment:17
<p>
V4
</p>
<ul><li>Rebased vs. 4.3.3.alpha0.
</li><li>Combines the skip member handlers, since Sphinx takes the first answer that's not <code>None</code>. (I suppose we could keep them separate but return <code>None</code> when a test is inconclusive).
</li><li>Detects changes in <code>-u</code>, too. Toggling either new option should trigger a rebuild.
</li></ul><p>
Should we move the new options to the "Advanced" section? Add "may use lots of memory"?
</p>
<p>
Note: I still haven't done a complete build in each configuration.
</p>
TicketmpatelSun, 14 Feb 2010 09:40:03 GMT
https://trac.sagemath.org/ticket/7549#comment:18
https://trac.sagemath.org/ticket/7549#comment:18
<p>
I should add that I've disabled the intersphinx extension, for now. It <a class="ext-link" href="http://sphinx.pocoo.org/latest/ext/intersphinx.html"><span class="icon"></span>can cache inventories</a>, but I don't know whether it fails gracefully if the cache has "expired" but there's no connection.
</p>
TicketmpatelSun, 14 Feb 2010 18:23:56 GMT
https://trac.sagemath.org/ticket/7549#comment:19
https://trac.sagemath.org/ticket/7549#comment:19
<p>
The HTML manual builds with <code>-i</code>, <code>-u</code>, and <code>-iu</code>.
</p>
<p>
Building the PDF manual with <code>-u</code> on sage.math yields
</p>
<pre class="wiki">[4811] [4812] [4813] [4814] [4815] [4816]
! TeX capacity exceeded, sorry [pool size=1165811].
\Hy@pstringdef ...->\edef #1{\pdfescapestring {#2}
}
l.392012 ...matrix0.Matrix.multiplicative_order}{}
\begin{methoddesc}{multipl...
! ==> Fatal error occurred, no output PDF file produced!
Transcript written on reference.log.
make: *** [reference.pdf] Error 1
</pre><p>
after I suppress problems with underscored methods in
</p>
<ul><li>sagenb.notebook.worksheet
</li><li>structure.formal_sum
</li><li>sage.combinat.crystals.tensor_product
</li><li>sage.combinat.species.set_species
</li><li>sage.combinat.words.word_generators
</li><li>sage.rings.number_field.number_field
</li><li>sage.rings.number_field.number_field_ideal
</li><li>sage.rings.polynomial.multi_polynomial_libsingular
</li><li>sage.rings.polynomial.infinite_polynomial_ring
</li><li>sage.rings.polynomial.infinite_polynomial_element
</li></ul><p>
I'll fix the first problem in a separate ticket and leave the others for someone else.
</p>
TicketjhpalmieriWed, 17 Feb 2010 16:37:21 GMT
https://trac.sagemath.org/ticket/7549#comment:20
https://trac.sagemath.org/ticket/7549#comment:20
<p>
I get the html manual to build, too, although with 1517 warnings when built with "-u", and more than 28,000 warnings with "-iu": either because the docstrings for underscore methods are sloppily formatted (not a surprise) or messages along the lines of those in <a class="closed ticket" href="https://trac.sagemath.org/ticket/8244" title="defect: Annoying warnings when building the HTML reference manual (closed: fixed)">#8244</a>.
</p>
<p>
I noticed that after I built with "-j -iu", edited a few files and ran "sage -b", then when I built the manual again with "-j -iu", in the "reading sources" portion of the build, it only processes the changed files, but in the "writing output" phase, it rewrites all of the files. This could be a little annoying; can it be avoided?
</p>
<p>
I haven't had the time to try a pdf build yet, but I'll work on that later today.
</p>
TicketjhpalmieriWed, 17 Feb 2010 23:20:43 GMT
https://trac.sagemath.org/ticket/7549#comment:21
https://trac.sagemath.org/ticket/7549#comment:21
<p>
Now I've tried building the pdf, and I run into the same "TeX capacity exceeded" message. I've tried altering "extra_mem_top" and "extra_mem_bot", but it's not helping. (I may not be doing this right, though.)
</p>
<p>
I had to fix more problems to get the PDF to build: everywhere there was an email address, pdflatex was crashing on the @ sign, so I had to enclose the address in double backquotes. So I ended up changing these files (in addition to sagenb.notebook.worksheet: I applied the patch from <a class="closed ticket" href="https://trac.sagemath.org/ticket/8265" title="defect: LaTeX-friendly Unicode characters in underscored methods' docstrings (closed: fixed)">#8265</a> to deal with this one):
</p>
<ul><li>sage/combinat/species/set_species.py
</li><li>sage/combinat/words/word_generators.py
</li><li>sage/misc/hg.py
</li><li>sage/misc/lazy_attribute.py
</li><li>sage/misc/preparser.py
</li><li>sage/rings/number_field/number_field.py
</li><li>sage/rings/number_field/number_field_ideal.py
</li><li>sage/rings/padics/padic_generic.py
</li><li>sage/rings/padics/tutorial.py
</li><li>sage/rings/polynomial/infinite_polynomial_element.py
</li><li>sage/rings/polynomial/infinite_polynomial_ring.py
</li><li>sage/rings/polynomial/multi_polynomial_libsingular.pyx
</li><li>sage/rings/polynomial/pbori.pyx
</li><li>sage/rings/polynomial/symmetric_ideal.py
</li><li>sage/rings/polynomial/symmetric_reduction.pyx
</li><li>sage/structure/formal_sum.py
</li><li>sage/structure/sequence.py
</li></ul><p>
I don't think that fixing these is a high priority, since the PDF manual doesn't build anyway with the "-u" option.
</p>
<hr />
<p>
Aside from my question about why "-iu" rewrites all of the output when it shouldn't have to, I'm happy with this. (I haven't tested this with "-i" or "-u".) I agree that there should be a comment about "-i" and "-u" taking a lot of memory, and perhaps saying that they don't work with the pdf build. I don't think they need to be in the "advanced" options.
</p>
TickethivertThu, 18 Feb 2010 00:04:18 GMT
https://trac.sagemath.org/ticket/7549#comment:22
https://trac.sagemath.org/ticket/7549#comment:22
<p>
Hi !
</p>
<p>
Just to make you aware of <a class="closed ticket" href="https://trac.sagemath.org/ticket/7448" title="defect: Sphinx nested class rendering. (closed: fixed)">#7448</a> (Sphinx rendering of nested classes) which is related. Notice that our patches certainly do not commute but rebasing should be trivial.
</p>
<p>
Cheers,
</p>
<p>
Florent
</p>
TicketmpatelThu, 18 Feb 2010 23:38:35 GMT
https://trac.sagemath.org/ticket/7549#comment:23
https://trac.sagemath.org/ticket/7549#comment:23
<p>
Replying to <a class="ticket" href="https://trac.sagemath.org/ticket/7549#comment:20" title="Comment 20">jhpalmieri</a>:
</p>
<blockquote class="citation">
<p>
I noticed that after I built with "-j -iu", edited a few files and ran "sage -b", then when I built the manual again with "-j -iu", in the "reading sources" portion of the build, it only processes the changed files, but in the "writing output" phase, it rewrites all of the files. This could be a little annoying; can it be avoided?
</p>
</blockquote>
<p>
I've also seen this behavior, but I've been unable reproduce it with certainty --- at least, with a version of <a class="closed ticket" href="https://trac.sagemath.org/ticket/6187" title="enhancement: [with patch, positive review] Fix post-cloning docbuild problems and ... (closed: fixed)">#6187</a>'s <a class="ext-link" href="http://trac.sagemath.org/sage_trac/attachment/ticket/6187/trac_6187_testreference.patch"><span class="icon"></span>"testreference" patch</a>. Are there particular types of changes that usually trigger the problem?
</p>
<p>
I don't think Sphinx is especially smart about updating files affected by a change in other files, but this may be irrelevant.
</p>
TicketmpatelSat, 20 Feb 2010 21:14:27 GMT
https://trac.sagemath.org/ticket/7549#comment:24
https://trac.sagemath.org/ticket/7549#comment:24
<p>
To do: Rebase the patch against 4.3.3.alpha1 + <a class="closed ticket" href="https://trac.sagemath.org/ticket/8244" title="defect: Annoying warnings when building the HTML reference manual (closed: fixed)">#8244</a> + <a class="closed ticket" href="https://trac.sagemath.org/ticket/7448" title="defect: Sphinx nested class rendering. (closed: fixed)">#7448</a>.
</p>
TicketjhpalmieriWed, 24 Feb 2010 22:06:49 GMT
https://trac.sagemath.org/ticket/7549#comment:25
https://trac.sagemath.org/ticket/7549#comment:25
<p>
Replying to <a class="ticket" href="https://trac.sagemath.org/ticket/7549#comment:23" title="Comment 23">mpatel</a>:
</p>
<blockquote class="citation">
<p>
Replying to <a class="ticket" href="https://trac.sagemath.org/ticket/7549#comment:20" title="Comment 20">jhpalmieri</a>:
</p>
<blockquote class="citation">
<p>
I noticed that after I built with "-j -iu", edited a few files and ran "sage -b", then when I built the manual again with "-j -iu", in the "reading sources" portion of the build, it only processes the changed files, but in the "writing output" phase, it rewrites all of the files. This could be a little annoying; can it be avoided?
</p>
</blockquote>
<p>
I've also seen this behavior, but I've been unable reproduce it with certainty --- at least, with a version of <a class="closed ticket" href="https://trac.sagemath.org/ticket/6187" title="enhancement: [with patch, positive review] Fix post-cloning docbuild problems and ... (closed: fixed)">#6187</a>'s <a class="ext-link" href="http://trac.sagemath.org/sage_trac/attachment/ticket/6187/trac_6187_testreference.patch"><span class="icon"></span>"testreference" patch</a>. Are there particular types of changes that usually trigger the problem?
</p>
</blockquote>
<p>
I'm not sure, but I just saw this message at the beginning of a docbuild:
</p>
<pre class="wiki">WARNING: unsupported build info format in '/Applications/sage/devel/sage/doc/output/html/en/reference/.buildinfo', building all
</pre>
TicketmpatelThu, 25 Feb 2010 08:46:21 GMT
https://trac.sagemath.org/ticket/7549#comment:26
https://trac.sagemath.org/ticket/7549#comment:26
<p>
I've seen this message, too. It <em>might</em> be a Sphinx bug.
</p>
<p>
The HTML builder writes a hash of the <code>html_*</code> settings to <code>.buildinfo</code> in the output directory. It appears that <a class="ext-link" href="http://bitbucket.org/birkenfeld/sphinx/src/tip/sphinx/builders/html.py#cl-144"><span class="icon"></span>StandaloneHTMLBuilder.get_outdated_docs</a> contains nearly all of the relevant code.
</p>
<p>
If, for some reason, this <code>get_outdated_docs</code> doesn't get called, the builder writes empty strings for the hashes. For example, <code>sage -docbuild reference html -j -S -a</code> does this (<code>-a</code> tells Sphinx to write all files). The next build attempt triggers the warning.
</p>
<p>
But I don't know if this is responsible for what we see.
</p>
TicketmpatelThu, 11 Mar 2010 06:21:32 GMTattachment set
https://trac.sagemath.org/ticket/7549
https://trac.sagemath.org/ticket/7549
<ul>
<li><strong>attachment</strong>
set to <em>trac_7549-doc_inheritance_underscore_v5.patch</em>
</li>
</ul>
<p>
Rebase vs. 4.3.4.alpha1 + <a class="closed ticket" href="https://trac.sagemath.org/ticket/8457" title="defect: Yet more annoying warnings when building the reference manual (closed: fixed)">#8457</a>. Apply only this patch.
</p>
TicketmpatelThu, 11 Mar 2010 06:30:43 GMT
https://trac.sagemath.org/ticket/7549#comment:27
https://trac.sagemath.org/ticket/7549#comment:27
<p>
V5 is rebased for 4.3.4.alpha1 + <a class="closed ticket" href="https://trac.sagemath.org/ticket/8457" title="defect: Yet more annoying warnings when building the reference manual (closed: fixed)">#8457</a>. I'm not sure what we should do about the many <code>-iu</code> warnings. Should we handle them in <code>sage_getargspec</code> or in <code>conf</code>?
</p>
TicketjhpalmieriFri, 12 Mar 2010 23:04:01 GMTstatus changed
https://trac.sagemath.org/ticket/7549#comment:28
https://trac.sagemath.org/ticket/7549#comment:28
<ul>
<li><strong>status</strong>
changed from <em>needs_review</em> to <em>needs_work</em>
</li>
</ul>
<p>
If I run <code>sage -docbuild reference html -i</code>, I get
</p>
<pre class="wiki">reading sources... [ 8%] sage/algebras/iwahori_hecke_algebra_element
Exception occurred:
File "/Applications/sage/devel/sage/doc/common/conf.py", line 354, in skip_member
if 'SAGE_CHECK_NESTED' in os.environ:
RuntimeError: maximum recursion depth exceeded
The full traceback has been saved in ...
</pre><p>
I scanned the traceback but didn't see anything obviously helpful.
</p>
<p>
By the way, I think we can put back the doctest from interfaces/singular.py, by changing the triple quotes at the beginning of the docstring to <code>r"""</code>. The attached patch does this.
</p>
<p>
Also, I used all of the extra error messages to figure out where the warnings
</p>
<pre class="wiki"><autodoc>:0: (ERROR/3) Unexpected indentation.
</pre><p>
were coming from, and the attached patch fixes the problems. So now, combined with <a class="closed ticket" href="https://trac.sagemath.org/ticket/8457" title="defect: Yet more annoying warnings when building the reference manual (closed: fixed)">#8457</a>, I get no error messages when building the reference manual (without the -i or -u switches, of course).
</p>
<p>
For the new warnings when building with -i or -u or -iu, I say we deal with them on another ticket. It's a big job revising all of the docstrings for underscore functions so that they are in proper reST format. (Also, right now they're useful -- see the previous paragraph. :)
</p>
<p>
Finally, do we want some sort of warning for the -i switch, and possibly the -u switch? ("may be slow, may not be compatible with PDF output" as part of its help string, for example)?
</p>
TicketjhpalmieriFri, 12 Mar 2010 23:07:43 GMT
https://trac.sagemath.org/ticket/7549#comment:29
https://trac.sagemath.org/ticket/7549#comment:29
<p>
(You may need to apply <a class="closed ticket" href="https://trac.sagemath.org/ticket/8511" title="defect: docstring fix for "unexpected indentation" (closed: fixed)">#8511</a> to get rid of one of the "unexpected indentation" warnings.)
</p>
TicketjhpalmieriFri, 12 Mar 2010 23:28:58 GMT
https://trac.sagemath.org/ticket/7549#comment:30
https://trac.sagemath.org/ticket/7549#comment:30
<p>
On second thought, I moved the "unexpected indentation" fix to ticket <a class="closed ticket" href="https://trac.sagemath.org/ticket/8511" title="defect: docstring fix for "unexpected indentation" (closed: fixed)">#8511</a>, so the "small fixes" patch just reinstates the interfaces/singular.py doctest.
</p>
TicketjhpalmieriFri, 12 Mar 2010 23:29:33 GMTattachment set
https://trac.sagemath.org/ticket/7549
https://trac.sagemath.org/ticket/7549
<ul>
<li><strong>attachment</strong>
set to <em>trac_7549-small-fixes.patch</em>
</li>
</ul>
<p>
apply on top of other patch
</p>
TicketmpatelSat, 13 Mar 2010 08:27:04 GMTattachment set
https://trac.sagemath.org/ticket/7549
https://trac.sagemath.org/ticket/7549
<ul>
<li><strong>attachment</strong>
set to <em>trac_7549-doc_inheritance_underscore_v6.patch</em>
</li>
</ul>
<p>
Fix recursion problem. Apply only this combined patch.
</p>
TicketmpatelSat, 13 Mar 2010 08:36:09 GMTstatus, author changed
https://trac.sagemath.org/ticket/7549#comment:31
https://trac.sagemath.org/ticket/7549#comment:31
<ul>
<li><strong>status</strong>
changed from <em>needs_work</em> to <em>needs_review</em>
</li>
<li><strong>author</strong>
changed from <em>Mitesh Patel</em> to <em>Mitesh Patel, Florent Hivert</em>
</li>
</ul>
<p>
I broke the module check in <a class="closed ticket" href="https://trac.sagemath.org/ticket/7448" title="defect: Sphinx nested class rendering. (closed: fixed)">#7448</a>'s <a class="attachment" href="https://trac.sagemath.org/attachment/ticket/7448/trac_7448-nested_class_sphinx-fh.4.patch" title="Attachment 'trac_7448-nested_class_sphinx-fh.4.patch' in Ticket #7448">V4</a><a class="trac-rawlink" href="https://trac.sagemath.org/raw-attachment/ticket/7448/trac_7448-nested_class_sphinx-fh.4.patch" title="Download"></a> when I made <a class="closed ticket" href="https://trac.sagemath.org/ticket/7448" title="defect: Sphinx nested class rendering. (closed: fixed)">#7448</a>'s <a class="attachment" href="https://trac.sagemath.org/attachment/ticket/7448/trac_7448-nested_class_sphinx-fh.5.patch" title="Attachment 'trac_7448-nested_class_sphinx-fh.5.patch' in Ticket #7448">V5</a><a class="trac-rawlink" href="https://trac.sagemath.org/raw-attachment/ticket/7448/trac_7448-nested_class_sphinx-fh.5.patch" title="Download"></a>. I apologize for that. I've restored Florent's code and folded in the small fixes patch in this ticket's V6.
</p>
TicketmpatelSat, 13 Mar 2010 08:37:35 GMT
https://trac.sagemath.org/ticket/7549#comment:32
https://trac.sagemath.org/ticket/7549#comment:32
<p>
The only change is in <code>sage_autodoc.py</code>.
</p>
TicketmpatelSat, 13 Mar 2010 09:01:03 GMTattachment set
https://trac.sagemath.org/ticket/7549
https://trac.sagemath.org/ticket/7549
<ul>
<li><strong>attachment</strong>
set to <em>trac_7549-doc_inheritance_underscore_v7.patch</em>
</li>
</ul>
<p>
Help notes. Replaces V6.
</p>
TickethivertSat, 13 Mar 2010 09:53:46 GMTauthor changed
https://trac.sagemath.org/ticket/7549#comment:33
https://trac.sagemath.org/ticket/7549#comment:33
<ul>
<li><strong>author</strong>
changed from <em>Mitesh Patel, Florent Hivert</em> to <em>Mitesh Patel</em>
</li>
</ul>
<p>
Replying to <a class="ticket" href="https://trac.sagemath.org/ticket/7549#comment:31" title="Comment 31">mpatel</a>:
</p>
<blockquote class="citation">
<p>
I broke the module check in <a class="closed ticket" href="https://trac.sagemath.org/ticket/7448" title="defect: Sphinx nested class rendering. (closed: fixed)">#7448</a>'s <a class="attachment" href="https://trac.sagemath.org/attachment/ticket/7448/trac_7448-nested_class_sphinx-fh.4.patch" title="Attachment 'trac_7448-nested_class_sphinx-fh.4.patch' in Ticket #7448">V4</a><a class="trac-rawlink" href="https://trac.sagemath.org/raw-attachment/ticket/7448/trac_7448-nested_class_sphinx-fh.4.patch" title="Download"></a> when I made <a class="closed ticket" href="https://trac.sagemath.org/ticket/7448" title="defect: Sphinx nested class rendering. (closed: fixed)">#7448</a>'s <a class="attachment" href="https://trac.sagemath.org/attachment/ticket/7448/trac_7448-nested_class_sphinx-fh.5.patch" title="Attachment 'trac_7448-nested_class_sphinx-fh.5.patch' in Ticket #7448">V5</a><a class="trac-rawlink" href="https://trac.sagemath.org/raw-attachment/ticket/7448/trac_7448-nested_class_sphinx-fh.5.patch" title="Download"></a>. I apologize for that. I've restored Florent's code and folded in the small fixes patch in this ticket's V6.
</p>
</blockquote>
<p>
Hi Mitesh ! I don't see any code from me here except a few lines who where already in <a class="closed ticket" href="https://trac.sagemath.org/ticket/7448" title="defect: Sphinx nested class rendering. (closed: fixed)">#7448</a>, and which you decide to improve (thanks by the way). So I don't think I deserve to be in the author.
</p>
<p>
Also I'm Ok with reviewing this but they are three more tickets in combinatoric which I committed myself to review. So don't rely on me for reviewing this very soon... However, I'd like to see this merged soon, so if you imagine someone who is willing to review, please ask him. Anyway, thanks for this work. I really this sage's doc is going to greatly improve.
</p>
TicketjhpalmieriMon, 05 Apr 2010 18:46:51 GMTstatus changed; reviewer set
https://trac.sagemath.org/ticket/7549#comment:34
https://trac.sagemath.org/ticket/7549#comment:34
<ul>
<li><strong>status</strong>
changed from <em>needs_review</em> to <em>positive_review</em>
</li>
<li><strong>reviewer</strong>
set to <em>John Palmieri</em>
</li>
</ul>
<p>
Sorry for not getting to this sooner. Positive review.
</p>
TicketjhpalmieriMon, 05 Apr 2010 18:46:58 GMTmilestone set
https://trac.sagemath.org/ticket/7549#comment:35
https://trac.sagemath.org/ticket/7549#comment:35
<ul>
<li><strong>milestone</strong>
set to <em>sage-4.4</em>
</li>
</ul>
TicketjhpalmieriThu, 15 Apr 2010 05:59:07 GMTstatus changed; resolution, merged set
https://trac.sagemath.org/ticket/7549#comment:36
https://trac.sagemath.org/ticket/7549#comment:36
<ul>
<li><strong>status</strong>
changed from <em>positive_review</em> to <em>closed</em>
</li>
<li><strong>resolution</strong>
set to <em>fixed</em>
</li>
<li><strong>merged</strong>
set to <em>sage-4.4.alpha0</em>
</li>
</ul>
<p>
Merged in 4.4.alpha0:
</p>
<ul><li>trac_7549-doc_inheritance_underscore_v7.patch
</li></ul>
Ticket