Add todo extension to Sphinx

[hivert]

Sphinx has a todo extension which allows to highlight and gather them
in a nice todo-list. I thinks it is worth adding it to sage doc.
See also
this thread on sage-devel.

CC: @nexttime @novoselt

Component: documentation

Keywords: todo sphinx days30

Author: Florent Hivert

Reviewer: John Palmieri

Merged: sage-4.7.2.alpha0

Issue created by migration from https://trac.sagemath.org/ticket/11251

[hivert]

comment:2

I currently nee to commute it with my patch for #9128...

[jhpalmieri]

comment:4

This looks pretty good to me. I would change "The To Do list of sage" -- at least capitalize Sage. Maybe there should also be a comment that the list is incomplete. (A "to do" item could be to add to the to do list :)

[hivert]

comment:5

Replying to @jhpalmieri:

This looks pretty good to me. I would change "The To Do list of sage" -- at least capitalize Sage. Maybe there should also be a comment that the list is incomplete. (A "to do" item could be to add to the to do list :)

Done. One less "to do" item :)

[hivert]

comment:6

I really don't understand the buildbot error. What the hell does it has to do with what I'm doing. Moreover I can't reproduce it on my laptop:

}}}popcorn-*stall/sage-4.6.2 $ sage -t  -force_lib devel/sagenb-main/sagenb/misc/misc.py
sage -t -force_lib "devel/sagenb-main/sagenb/misc/misc.py"  
         [2.5 s]
 
----------------------------------------------------------------------
All tests passed!
Total time for all tests: 2.6 seconds

[saliola]

comment:7

Hello. I noticed that the todo comments in the command-line documentation do not appear. Here is a short example you can do on the command line:

sage: def f(): 
....:     r"""
....:     Hello!
....:     """
....:     pass
....: 
sage: 
sage: f?
Type:           function
Base Class:     <type 'function'>
String Form:    <function f at 0x110441f50>
Namespace:      Interactive
File:           /Users/saliola/Applications/sage-4.7.rc1/devel/sage-trac/sage/combinat/posets/<ipython console>
Definition:     f()
Docstring:
       Hello!


sage: def g():
....:     r"""
....:     .. todo::
....:         Hello
....:     """ 
....:     pass
....: 
sage: g?
Type:           function
Base Class:     <type 'function'>
String Form:    <function g at 0x10ef6b050>
Namespace:      Interactive
File:           /Users/saliola/Applications/sage-4.7.rc1/devel/sage-trac/sage/combinat/posets/<ipython console>
Definition:     g()

sage: 

[hivert]

Changed keywords from todo sphinx to todo sphinx days30

[nthiery]

comment:9

Hi!

Any chance to have this finalized soon? Currently #11287 (runsnake) depends on it.

[hivert]

comment:10

Any chance to have this finalized soon? Currently #11287 (runsnake) depends on it.

I've identified the problem: the file sage-4.7/devel/sagenb/sagenb/misc/sphinxify.py contains a non updated copy of the configuration file
sage-4.7/devel/sage/doc/common/conf.py

So if I find out why we don't simply fetch the file, I might fix it very soon.

Florent

[hivert]

comment:11

Attachment: trac_11251-sphinx_todo_extension-fh.patch.gz

Hello. I noticed that the todo comments in the command-line documentation do not appear. Here is a short example you can do on the command line:

This should now be fixed. Back to needs review.

[jhpalmieri]

comment:12

This looks pretty good to me. I'm attaching a small referee patch. Should we also patch sphinxify in the sagenb repo?

[jhpalmieri]

Attachment: trac_11251-referee.patch.gz

apply on top of other patch

[nthiery]

comment:13

Positive review on the reviewer's patch. John: you may put a positive review if you feel like it now!

[jhpalmieri]

comment:14

Well, does sphinxify.py need to be patched?

[hivert]

comment:15

Replying to @jhpalmieri:

Well, does sphinxify.py need to be patched?

Sorry for the confusion. My analysis of the problem was wrong. There is a code duplication and the actual file I had to patch is

sage-4.7/devel/sage-combinat/doc/en/introspect/conf.py

You can double check that it works both under the command line and the notebook. I actually don't really know what this sphinxify.py is here.

Cheers,

Florent

[jhpalmieri]

Reviewer: John Palmieri

[jhpalmieri]

comment:16

Introspection works, but isn't perfect. I think it's good enough for now, but it might be nice to try to figure out what's wrong eventually. In particular: look at a docstring with a ".. todo" markup in these four ways:

• in the reference manual: it looks great. "TODO" is in bold, and the whole block has a different background color.
• in the notebook (by typing sage.combinat.combinat?, for example): it looks okay. "TODO" is not in bold, and the block has the same background color as the rest of the docstring.
• from the command line, using ...?: it looks as good as can be expected, since it's plain text.
• from the command line, using browse_sage_doc(sage.combinat.combinat): it looks pretty good, in between the reference manual and the notebook: "TODO" is in bold, but the background color is white.

I tried modifying sphinxify.py and it didn't seem to have any effect. If only there were some way to add something like this to a "to do list"...

[nexttime]

comment:19

Maybe I misunderstood the intent, but is there a way to omit the TODOs from "production" documentation?

(I thought they were only for "internal" use, i.e. invisible to an "ordinary" user, as opposed to a developer working on the documentation, similar to \note{} of LaTeX's "beamer" class.)

[hivert]

comment:20

Replying to @nexttime:

Maybe I misunderstood the intent, but is there a way to omit the TODOs from
"production" documentation?

(I thought they were only for "internal" use, i.e. invisible to an
"ordinary" user, as opposed to a developer working on the documentation,
similar to \note{} of LaTeX's "beamer" class.)

Actually, this wasn't my intend. As an open source project, I don't see the
point in hiding places where sage could be improved. On the contrary, marking
clearly in the documentation: "there is something we want to improve here"
seems to me to be a good practice. This was my main motivation for adding this
extension.

Otherwise said, in my mind those TODOs are more for long term improvement
where we don't know yet what to do and some feedback is needed or where we
don't have yet the manpower to do it, But my point of view is maybe not shared
by the majority of sage developers/users.

Now to answer the technical question, in doc/common/conf.py you have

# include the todos
todo_include_todos = True

Changing it to False by hand or depending on an environment variable
should do the job. Still, I'd rather having it to True by default.

Florent

[jhpalmieri]

comment:21

Replying to @nexttime:

Maybe I misunderstood the intent, but is there a way to omit the TODOs from "production" documentation?

(I thought they were only for "internal" use, i.e. invisible to an "ordinary" user, as opposed to a developer working on the documentation, similar to \note{} of LaTeX's "beamer" class.)

I understood this markup is used to mark places where the code needs improvement, not the documentation. Also, as you know, with Sage the distinction between users and developers is intentionally blurred.

[jhpalmieri]

comment:22

See #6495 for a followup, of sorts. That ticket breaks the reference manual into chunks and builds them in parallel, which can greatly speed things up, but I can't figure out a good way to collect all of the todo items into a single list. So right now, the patch makes each Sage module collect its own todo items. Please take a look and suggest improvements.

[jdemeyer]

Merged: sage-4.7.2.alpha0