Sphinx TODO extension

196 views
Skip to first unread message

Florent Hivert

unread,
Apr 25, 2011, 1:04:04 PM4/25/11
to Sage Devel
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

unread,
Apr 25, 2011, 3:22:01 PM4/25/11
to sage-...@googlegroups.com


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

unread,
Apr 25, 2011, 7:17:19 PM4/25/11
to sage-...@googlegroups.com
Hi John,

Good idea. Done.

Florent

Florent Hivert

unread,
Apr 25, 2011, 7:49:39 PM4/25/11
to sage-...@googlegroups.com
> > 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

unread,
Apr 25, 2011, 8:20:32 PM4/25/11
to sage-devel
> 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

unread,
Apr 25, 2011, 10:23:43 PM4/25/11
to sage-...@googlegroups.com
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

unread,
Apr 27, 2011, 8:47:51 AM4/27/11
to sage-...@googlegroups.com
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

unread,
Jul 3, 2011, 1:25:48 PM7/3/11
to sage-...@googlegroups.com

+1

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


-leif

 
Reply all
Reply to author
Forward
0 new messages