Sphinx TODO extension

[Florent Hivert]

Hi there,

I'm working on #9128 whose goal is to resolve dangling links by looking in
python docs and in sage.all. On the way, I noticed that there are lots of
todos in the doc but no systematic way to handle them in sage. Fortunately,
there is a nice sphinx extension to handle them and gather them in a nice todo
list. I just created #11251 "Add todo extension to Sphinx" which allows to
use it as e.g.:

.. todo:: Should be optimized using Cython

Is there any objection to use it ?

At this point, I changed one todo as an example but did not systematically
change all the todos to avoid conflicts: the parts of sage bearing most todos
are those most likely to be under heavy development. Besides I didn't have the
time to do it ;-). I think it will be easier to instead change those
progressively, after a test period.

Do you agree with this approach?

Cheers,

Florent

[John H Palmieri]

On Monday, April 25, 2011 10:04:04 AM UTC-7, fhivert wrote:

     Hi there,

I'm working on #9128 whose goal is to resolve dangling links by looking in
python docs and in sage.all. On the way, I noticed that there are lots of
todos in the doc but no systematic way to handle them in sage. Fortunately,
there is a nice sphinx extension to handle them and gather them in a nice todo
list.  I just created #11251 "Add todo extension to Sphinx" which allows to
use it as e.g.:

  .. todo:: Should be optimized using Cython

Is there any objection to use it ?

Not from me.  I like the idea of getting more consistency in the documentation by using more Sphinx mark-up and extensions.

At this point, I changed one todo as an example but did not systematically
change all the todos to avoid conflicts: the parts of sage bearing most todos
are those most likely to be under heavy development. Besides I didn't have the
time to do it ;-). I think it will be easier to instead change those
progressively, after a test period.

Do you agree with this approach?

It seems like a good idea to me.  Should we also add a comment to the developer's guide about this kind of mark-up for the documentation?

--
John

[Florent Hivert]

Hi John,

Good idea. Done.

Florent

[Florent Hivert]

> > It seems like a good idea to me. Should we also add a comment to the
> > developer's guide about this kind of mark-up for the documentation?
>
> Good idea. Done.

In the same veins, I think that links to trac ticket should be
hyperlinks. Sphinx extlinks extension make it very easy. The only question is
the syntax. I'm thinking about something like :ticket:`3412` or :trac:`2132`.
Any preferences or objections ?

Cheers,

Florent

[slabbe]

> I'm thinking about something like :ticket:`3412` or :trac:`2132`.
> Any preferences or objections ?

I prefer trac. I don't know why.

Sébastien

[Keshav Kini]

I also prefer trac, but I know why: it's shorter! Also it's more clearly related to trac.sagemath.org/sage_trac . Patch comments also say stuff like "trac #1234", not "ticket #1234".

And yeah, I'm with John - it's a waste to use sphinx and not take advantage of its capabilities. The same goes for all the tools we use, really, including trac itself (if you have any ideas about how to better utilize trac, you might want to contact Maarten in another thread floating around sage-devel recently...)

-Keshav

----
Join us in #sagemath on irc.freenode.net !

[Pablo De Napoli]

Please review ticket #10620 to upgrade sphynix

Pablo

> --
> To post to this group, send an email to sage-...@googlegroups.com
> To unsubscribe from this group, send an email to
> sage-devel+...@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/sage-devel
> URL: http://www.sagemath.org
>

[leif]

+1

Incidentally, I just started adding FIXMEs to the Sage Developer's Guide... :-)


-leif