Advertising...

[Florent Hivert]

Hi there,

Sage documentation still has a lot of dangling links. To check if there are
some please use the recently added option --warn-links as in:

sage --docbuild --warn-links reference html

Beware that it triggers a full recompilation of the doc the first time you add
the option. Please see the developper guide (version 5.0_beta8 at least is
better) for details on how to setup links. Note that Sage-5.0 will have
several niceties for links:

- :trac:`12423` to link to trac site
- :python:`library/stdtypes.html#truth-value-testing` links to
http://docs.python.org/release/2.7.2/library/stdtypes.html#truth-value-testing
- :wikipedia:`Sage_(mathematics_software)`

If no one object, I'll change the checklist so that people don't add new
dangling links.

And finally, please use, use again and abuse of the markup

.. SEEALSO:

Have a nice doc :-)

Cheers,

Florent

[David Loeffler]

On Thursday, 22 March 2012 21:37:19 UTC, fhivert wrote:

     Hi there,

Sage documentation still has a lot of dangling links. To check if there are
some please use the recently added option --warn-links as in:

    sage --docbuild --warn-links reference html

Beware that it triggers a full recompilation of the doc the first time you add
the option.

I tried to use this, but ran into the following stupid glitch. If you do, in a clean copy of Sage, the following commands:

sage -b main

sage --docbuild --warn-links reference html

sage -clone foo

sage --docbuild --warn-links reference html

then *every one* of the last three commands will trigger a full rebuild of the reference manual (taking several tens of minutes)! This makes it basically impossible to use this new command together with Mercurial branches, and in particular kills any possibility of getting it to work with the patchbot.

David

[Nicolas M. Thiery]

On Sat, Mar 24, 2012 at 04:35:42AM -0700, David Loeffler wrote:
> I tried to use this, but ran into the following stupid glitch. If you do,
> in a clean copy of Sage, the following commands:
>
> sage -b main
> sage --docbuild --warn-links reference html
> sage -clone foo
> sage --docbuild --warn-links reference html
>
> then *every one* of the last three commands will trigger a full rebuild of
> the reference manual (taking several tens of minutes)! This makes it
> basically impossible to use this new command together with Mercurial
> branches, and in particular kills any possibility of getting it to work
> with the patchbot.

Yeah, those recompilations are a pain. In such a situation, one would
want to hack sage-main to setup --warn-links as default compilation
option. Do you see a preferable way for this, that would survive
through -clone, and not interfere with mercurial branches?

Cheers,
Nicolas
--
Nicolas M. Thi�ry "Isil" <nth...@users.sf.net>
http://Nicolas.Thiery.name/

[David Loeffler]

On Saturday, 24 March 2012 13:33:59 UTC, Nicolas M. Thiéry wrote:

On Sat, Mar 24, 2012 at 04:35:42AM -0700, David Loeffler wrote:
>    I tried to use this, but ran into the following stupid glitch.  

Yeah, those recompilations are a pain. In such a situation, one would

want to hack sage-main to setup --warn-links as default compilation
option. Do you see a preferable way for this, that would survive
through -clone, and not interfere with mercurial branches?

The problem isn't with sage-main, but with the code for "sage -clone". This code already contains a (slightly hackish) routine to check whether or not "--jsmath" was set last time "sage -docbuild" was called, and call it again with the same options. The existing routine does this by checking a specific output file in the reference manual to see if it includes the jsmath code, and so is no help with --warn-links which makes no actual difference to the output. A better way would presumably be to examine the contents of the Sphinx environment pickle, which must be where the options last used are stored.

David

[Florent Hivert]

Hi David,

I think I found a way to hack into Sphinx configuration so that changing
warn-links do not trigger the full recompilation of the doc. You have to
trigger in by hand if you want. For example in:

sage --docbuild reference html

sage --docbuild --warn-links reference html

The second compilation does nothing. And in

sage --docbuild reference html
touch <some sage source files>

sage --docbuild --warn-links reference html

The second recompilation only warns for the touched files. Is this what we
want ? Or do we want an extra option doing whatever ?

See #12869

Cheers,

Florent