Discussion:
Implementation of a ToDo directive
(too old to reply)
d***@comnets.rwth-aachen.de
2008-11-06 09:13:57 UTC
Permalink
Dear all,

first of all I want to thank the Sphinx developers for this great
tool. I
ported the developers manual for our openWNS (open Wireless Network
Simulator)
to Sphinx. I am still surprised how easy and intuitively the work with
Sphinx is.
So, thanks for that!

During the work on the documentation I often wanted to place ToDos
within the text to keep track of
things that still need to be documented. I think it would be
benefitial to have
a special kind of admonition (.. todo::) to place inline in the text
for this task.
Furthermore, I want these admonitions to show only if a certain flag
is set in the
configuration, such that a released version of the documentation does
not show any
todo content. In addition to that I want a separate page that collects
all todo
admonitions and provides an overview of all pending todos within the
document.

I did not find any support for this within the current release of
Sphinx, so I started
developing a todo extension of my own. I implemented two directives:
todo & todolist
that should take care of the task. The basic functionality works now,
but I still face
some problems. You can take a look at what I have done so far here:

http://pastebin.com/f55ea9fe0

An example of how I use this example can be seen here:

http://pastebin.com/f7913c13a

The problems I have now are:

1. I only want to include the todolist page in the TOC if the
configuration flag is set.
The todolist page is now always included, although it is empty if
the configuration file
is not set. I want it to completely vanish.

2. With this implementation all todo admonitions show up in the final
document as
'''Note: The todo description''' I want them to show up as '''Todo:
The todo description'''

3. In the todolist I only copy the original todo. It would be nice to
include additional
information there, such as a link to the original todo location and
the original location within the
source (filename, linenumber, etc.)

I am a little bit stuck here and wonder if someone could help. I
already tried the sphinx.ext.ifconfig
to exclude the todolist from the TOC, but this does not work. I think
Sphinx does not expect
any directive within the TOC.

Any ideas?

Best Regards,
Daniel

--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To post to this group, send email to sphinx-***@googlegroups.com
To unsubscribe from this group, send email to sphinx-dev+***@googlegroups.com
For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en
-~----------~----~----~----~------~----~------~--~---
Georg Brandl
2008-11-06 10:11:59 UTC
Permalink
Post by d***@comnets.rwth-aachen.de
Dear all,
first of all I want to thank the Sphinx developers for this great
tool. I
ported the developers manual for our openWNS (open Wireless Network
Simulator)
to Sphinx. I am still surprised how easy and intuitively the work with
Sphinx is.
So, thanks for that!
During the work on the documentation I often wanted to place ToDos
within the text to keep track of
things that still need to be documented. I think it would be
benefitial to have
a special kind of admonition (.. todo::) to place inline in the text
for this task.
Furthermore, I want these admonitions to show only if a certain flag
is set in the
configuration, such that a released version of the documentation does
not show any
todo content. In addition to that I want a separate page that collects
all todo
admonitions and provides an overview of all pending todos within the
document.
That's a good idea! I'd like to include the extension when it's finished.
Post by d***@comnets.rwth-aachen.de
I did not find any support for this within the current release of
Sphinx, so I started
todo & todolist
that should take care of the task. The basic functionality works now,
but I still face
http://pastebin.com/f55ea9fe0
http://pastebin.com/f7913c13a
1. I only want to include the todolist page in the TOC if the
configuration flag is set.
The todolist page is now always included, although it is empty if
the configuration file
is not set. I want it to completely vanish.
Hmm... there's no API yet for excluding items from the TOC.

Of course, as a hack-around, you could generate the document heading only
if the "todo" option is set. Then, since there is no heading in the document,
none will show up in the TOC.
Post by d***@comnets.rwth-aachen.de
2. With this implementation all todo admonitions show up in the final
document as
The todo description'''
If you modify your make_admonition call a bit, that should be fine. Look
at the seealso directive:

seealsonode = make_admonition(
addnodes.seealso, name, [_('See also')], options, content,
lineno, content_offset, block_text, state, state_machine)

IOW, the "arguments" arg is replaced by your wanted title.
Post by d***@comnets.rwth-aachen.de
3. In the todolist I only copy the original todo. It would be nice to
include additional
information there, such as a link to the original todo location and
the original location within the
source (filename, linenumber, etc.)
For the link to the location, you can put a "target" node at the point
where the todo directive occurs. Look at the index directive for an example.

I see that you store all todo nodes as an attribute of the node class.
This will not work with partial builds, when only changed files are parsed.
The canonical way is to use an attribute of the environment object, which
is pickled and restored between calls.
Post by d***@comnets.rwth-aachen.de
I am a little bit stuck here and wonder if someone could help. I
already tried the sphinx.ext.ifconfig
to exclude the todolist from the TOC, but this does not work. I think
Sphinx does not expect any directive within the TOC.
That's true. It doesn't interpret the content in the "normal" way.

cheers,
Georg


--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To post to this group, send email to sphinx-***@googlegroups.com
To unsubscribe from this group, send email to sphinx-dev+***@googlegroups.com
For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en
-~----------~----~----~----~------~----~------~--~---
d***@comnets.rwth-aachen.de
2008-11-06 15:00:56 UTC
Permalink
Thanks for your quick help. I managed to make todos show up as 'Todo:
content of todo'. It
did not work by simply putting 'Todo' in the argument list. It showed
up then as 'Note: Todo:'.
I needed to create a new node type 'todoNode' and add appropriate
visitors. The Sphinx documentation
is not up to date I think, addNode does not take any visitor arguments
anymore, so I helped myself
by using setattr on the translator object. This did the job. Maybe
there is a better way?

I manged to include a target node for each todo item, but I did not
find how to actually insert a
reference to these labels in the todolist. How is this done? I cannot
find the code that actually
generates the index pages.

I also collect all todo nodes at the environment object now.

I have put the current version here:

http://pastebin.com/m2b02f72b

Regards,
Daniel
Post by Georg Brandl
Post by d***@comnets.rwth-aachen.de
Dear all,
first of all I want to thank the Sphinx developers for this great
tool. I
ported the developers manual for our openWNS (open Wireless Network
Simulator)
to Sphinx. I am still surprised how easy and intuitively the work with
Sphinx is.
So, thanks for that!
During the work on the documentation I often wanted to place ToDos
within the text to keep track of
things that still need to be documented. I think it would be
benefitial to have
a special kind of admonition (.. todo::) to place inline in the text
for this task.
Furthermore, I want these admonitions to show only if a certain flag
is set in the
configuration, such that a released version of the documentation does
not show any
todo content. In addition to that I want a separate page that collects
all todo
admonitions and provides an overview of all pending todos within the
document.
That's a good idea! I'd like to include the extension when it's finished.
Post by d***@comnets.rwth-aachen.de
I did not find any support for this within the current release of
Sphinx, so I started
todo & todolist
that should take care of the task. The basic functionality works now,
but I still face
http://pastebin.com/f55ea9fe0
http://pastebin.com/f7913c13a
1. I only want to include the todolist page in the TOC if the
configuration flag is set.
   The todolist page is now always included, although it is empty if
the configuration file
   is not set. I want it to completely vanish.
Hmm... there's no API yet for excluding items from the TOC.
Of course, as a hack-around, you could generate the document heading only
if the "todo" option is set. Then, since there is no heading in the document,
none will show up in the TOC.
Post by d***@comnets.rwth-aachen.de
2. With this implementation all todo admonitions show up in the final
document as
The todo description'''
If you modify your make_admonition call a bit, that should be fine. Look
    seealsonode = make_admonition(
        addnodes.seealso, name, [_('See also')], options, content,
        lineno, content_offset, block_text, state, state_machine)
IOW, the "arguments" arg is replaced by your wanted title.
Post by d***@comnets.rwth-aachen.de
3. In the todolist I only copy the original todo. It would be nice to
include additional
   information there, such as a link to the original todo location and
the original location within the
   source (filename, linenumber, etc.)
For the link to the location, you can put a "target" node at the point
where the todo directive occurs. Look at the index directive for an example.
I see that you store all todo nodes as an attribute of the node class.
This will not work with partial builds, when only changed files are parsed.
The canonical way is to use an attribute of the environment object, which
is pickled and restored between calls.
Post by d***@comnets.rwth-aachen.de
I am a little bit stuck here and wonder if someone could help. I
already tried the sphinx.ext.ifconfig
to exclude the todolist from the TOC, but this does not work. I think
Sphinx does not expect any directive within the TOC.
That's true. It doesn't interpret the content in the "normal" way.
cheers,
Georg
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To post to this group, send email to sphinx-***@googlegroups.com
To unsubscribe from this group, send email to sphinx-dev+***@googlegroups.com
For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en
-~----------~----~----~----~------~----~------~--~---
Yarko T
2008-11-08 00:06:16 UTC
Permalink
Hi Daniel,
Thanks for posting this. It caused me to read about extensions to
Sphinx...

I don't know if I"m missing something in config somewhere - I put in one
test ".. todo::"
and the node seems to be created, but docutils/nodes.py doesn't like that

node.replace_self([])

is being called on a node whose attribute is ['admonition-todo']


I've got a todolist.rst, and a single todo test entry in the sources. I'm
pretty sure I've configured conf.py right (after all, the extension is
correctly getting called - I've stepped through this to try to find what's
going on).

I've also put my new todolist in the toctree - basically just trying to
start w/ the example usage file you'd posted.

Can you help?

Thanks much,

Yarko
Post by d***@comnets.rwth-aachen.de
content of todo'. It
did not work by simply putting 'Todo' in the argument list. It showed
up then as 'Note: Todo:'.
I needed to create a new node type 'todoNode' and add appropriate
visitors. The Sphinx documentation
is not up to date I think, addNode does not take any visitor arguments
anymore, so I helped myself
by using setattr on the translator object. This did the job. Maybe
there is a better way?
I manged to include a target node for each todo item, but I did not
find how to actually insert a
reference to these labels in the todolist. How is this done? I cannot
find the code that actually
generates the index pages.
I also collect all todo nodes at the environment object now.
http://pastebin.com/m2b02f72b
Regards,
Daniel
Post by Georg Brandl
Post by d***@comnets.rwth-aachen.de
Dear all,
first of all I want to thank the Sphinx developers for this great
tool. I
ported the developers manual for our openWNS (open Wireless Network
Simulator)
to Sphinx. I am still surprised how easy and intuitively the work with
Sphinx is.
So, thanks for that!
During the work on the documentation I often wanted to place ToDos
within the text to keep track of
things that still need to be documented. I think it would be
benefitial to have
a special kind of admonition (.. todo::) to place inline in the text
for this task.
Furthermore, I want these admonitions to show only if a certain flag
is set in the
configuration, such that a released version of the documentation does
not show any
todo content. In addition to that I want a separate page that collects
all todo
admonitions and provides an overview of all pending todos within the
document.
That's a good idea! I'd like to include the extension when it's finished.
Post by d***@comnets.rwth-aachen.de
I did not find any support for this within the current release of
Sphinx, so I started
todo & todolist
that should take care of the task. The basic functionality works now,
but I still face
http://pastebin.com/f55ea9fe0
http://pastebin.com/f7913c13a
1. I only want to include the todolist page in the TOC if the
configuration flag is set.
The todolist page is now always included, although it is empty if
the configuration file
is not set. I want it to completely vanish.
Hmm... there's no API yet for excluding items from the TOC.
Of course, as a hack-around, you could generate the document heading only
if the "todo" option is set. Then, since there is no heading in the
document,
Post by Georg Brandl
none will show up in the TOC.
Post by d***@comnets.rwth-aachen.de
2. With this implementation all todo admonitions show up in the final
document as
The todo description'''
If you modify your make_admonition call a bit, that should be fine. Look
seealsonode = make_admonition(
addnodes.seealso, name, [_('See also')], options, content,
lineno, content_offset, block_text, state, state_machine)
IOW, the "arguments" arg is replaced by your wanted title.
Post by d***@comnets.rwth-aachen.de
3. In the todolist I only copy the original todo. It would be nice to
include additional
information there, such as a link to the original todo location and
the original location within the
source (filename, linenumber, etc.)
For the link to the location, you can put a "target" node at the point
where the todo directive occurs. Look at the index directive for an
example.
Post by Georg Brandl
I see that you store all todo nodes as an attribute of the node class.
This will not work with partial builds, when only changed files are
parsed.
Post by Georg Brandl
The canonical way is to use an attribute of the environment object, which
is pickled and restored between calls.
Post by d***@comnets.rwth-aachen.de
I am a little bit stuck here and wonder if someone could help. I
already tried the sphinx.ext.ifconfig
to exclude the todolist from the TOC, but this does not work. I think
Sphinx does not expect any directive within the TOC.
That's true. It doesn't interpret the content in the "normal" way.
cheers,
Georg
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To post to this group, send email to sphinx-***@googlegroups.com
To unsubscribe from this group, send email to sphinx-dev+***@googlegroups.com
For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en
-~----------~----~----~----~------~----~------~--~---
Yarko T
2008-11-08 09:15:58 UTC
Permalink
Ok - I've gotten a little further on this - if I put a try / except in
process_todo_nodes() in the node.replace_self() call and just pass on the
exception, things seem to be ok for todo output.
Now, in htmlwriter.py, I get an "unkown_visit()" call for 'todolist' -
still trying to figure this out...
Post by Yarko T
Hi Daniel,
Thanks for posting this. It caused me to read about extensions to
Sphinx...
I don't know if I"m missing something in config somewhere - I put in one
test ".. todo::"
and the node seems to be created, but docutils/nodes.py doesn't like that
node.replace_self([])
is being called on a node whose attribute is ['admonition-todo']
I've got a todolist.rst, and a single todo test entry in the sources. I'm
pretty sure I've configured conf.py right (after all, the extension is
correctly getting called - I've stepped through this to try to find what's
going on).
I've also put my new todolist in the toctree - basically just trying to
start w/ the example usage file you'd posted.
Can you help?
Thanks much,
Yarko
Post by d***@comnets.rwth-aachen.de
content of todo'. It
did not work by simply putting 'Todo' in the argument list. It showed
up then as 'Note: Todo:'.
I needed to create a new node type 'todoNode' and add appropriate
visitors. The Sphinx documentation
is not up to date I think, addNode does not take any visitor arguments
anymore, so I helped myself
by using setattr on the translator object. This did the job. Maybe
there is a better way?
I manged to include a target node for each todo item, but I did not
find how to actually insert a
reference to these labels in the todolist. How is this done? I cannot
find the code that actually
generates the index pages.
I also collect all todo nodes at the environment object now.
http://pastebin.com/m2b02f72b
Regards,
Daniel
Post by Georg Brandl
Post by d***@comnets.rwth-aachen.de
Dear all,
first of all I want to thank the Sphinx developers for this great
tool. I
ported the developers manual for our openWNS (open Wireless Network
Simulator)
to Sphinx. I am still surprised how easy and intuitively the work with
Sphinx is.
So, thanks for that!
During the work on the documentation I often wanted to place ToDos
within the text to keep track of
things that still need to be documented. I think it would be
benefitial to have
a special kind of admonition (.. todo::) to place inline in the text
for this task.
Furthermore, I want these admonitions to show only if a certain flag
is set in the
configuration, such that a released version of the documentation does
not show any
todo content. In addition to that I want a separate page that collects
all todo
admonitions and provides an overview of all pending todos within the
document.
That's a good idea! I'd like to include the extension when it's
finished.
Post by Georg Brandl
Post by d***@comnets.rwth-aachen.de
I did not find any support for this within the current release of
Sphinx, so I started
todo & todolist
that should take care of the task. The basic functionality works now,
but I still face
http://pastebin.com/f55ea9fe0
http://pastebin.com/f7913c13a
1. I only want to include the todolist page in the TOC if the
configuration flag is set.
The todolist page is now always included, although it is empty if
the configuration file
is not set. I want it to completely vanish.
Hmm... there's no API yet for excluding items from the TOC.
Of course, as a hack-around, you could generate the document heading
only
Post by Georg Brandl
if the "todo" option is set. Then, since there is no heading in the
document,
Post by Georg Brandl
none will show up in the TOC.
Post by d***@comnets.rwth-aachen.de
2. With this implementation all todo admonitions show up in the final
document as
The todo description'''
If you modify your make_admonition call a bit, that should be fine. Look
seealsonode = make_admonition(
addnodes.seealso, name, [_('See also')], options, content,
lineno, content_offset, block_text, state, state_machine)
IOW, the "arguments" arg is replaced by your wanted title.
Post by d***@comnets.rwth-aachen.de
3. In the todolist I only copy the original todo. It would be nice to
include additional
information there, such as a link to the original todo location and
the original location within the
source (filename, linenumber, etc.)
For the link to the location, you can put a "target" node at the point
where the todo directive occurs. Look at the index directive for an
example.
Post by Georg Brandl
I see that you store all todo nodes as an attribute of the node class.
This will not work with partial builds, when only changed files are
parsed.
Post by Georg Brandl
The canonical way is to use an attribute of the environment object,
which
Post by Georg Brandl
is pickled and restored between calls.
Post by d***@comnets.rwth-aachen.de
I am a little bit stuck here and wonder if someone could help. I
already tried the sphinx.ext.ifconfig
to exclude the todolist from the TOC, but this does not work. I think
Sphinx does not expect any directive within the TOC.
That's true. It doesn't interpret the content in the "normal" way.
cheers,
Georg
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To post to this group, send email to sphinx-***@googlegroups.com
To unsubscribe from this group, send email to sphinx-dev+***@googlegroups.com
For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en
-~----------~----~----~----~------~----~------~--~---
d***@comnets.rwth-aachen.de
2008-11-09 14:29:13 UTC
Permalink
It should work now. You can check out the new version here:

http://pastebin.com/f71ba7373

Let me know if you still face any problems.

Regards,
Daniel
Ok - I've gotten a little further on this -  if I put a try / except in
process_todo_nodes() in the node.replace_self() call and just pass on the
exception, things seem to be ok for todo output.
Now, in htmlwriter.py, I get an "unkown_visit()"  call  for 'todolist' -
still trying to figure this out...
Post by Yarko T
Hi Daniel,
Thanks for posting this.   It caused me to read about extensions to
Sphinx...
I don't know if I"m missing something in config somewhere -  I put in one
test ".. todo::"
and the node seems to be created, but docutils/nodes.py  doesn't like that
    node.replace_self([])
is being called on a node whose attribute is ['admonition-todo']
I've got a todolist.rst, and a single todo test entry in the sources.   I'm
pretty sure I've configured conf.py right (after all, the extension is
correctly getting called - I've stepped through this to try to find what's
going on).
I've also put my new todolist in the toctree - basically just trying to
start w/ the example usage file you'd posted.
Can you help?
Thanks much,
Yarko
Post by d***@comnets.rwth-aachen.de
content of todo'. It
did not work by simply putting 'Todo' in the argument list. It showed
up then as 'Note: Todo:'.
I needed to create a new node type 'todoNode' and add appropriate
visitors. The Sphinx documentation
is not up to date I think, addNode does not take any visitor arguments
anymore, so I helped myself
by using setattr on the translator object. This did the job. Maybe
there is a better way?
I manged to include a target node for each todo item, but I did not
find how to actually insert a
reference to these labels in the todolist. How is this done? I cannot
find the code that actually
generates the index pages.
I also collect all todo nodes at the environment object now.
http://pastebin.com/m2b02f72b
Regards,
 Daniel
Post by Georg Brandl
Post by d***@comnets.rwth-aachen.de
Dear all,
first of all I want to thank the Sphinx developers for this great
tool. I
ported the developers manual for our openWNS (open Wireless Network
Simulator)
to Sphinx. I am still surprised how easy and intuitively the work with
Sphinx is.
So, thanks for that!
During the work on the documentation I often wanted to place ToDos
within the text to keep track of
things that still need to be documented. I think it would be
benefitial to have
a special kind of admonition (.. todo::) to place inline in the text
for this task.
Furthermore, I want these admonitions to show only if a certain flag
is set in the
configuration, such that a released version of the documentation does
not show any
todo content. In addition to that I want a separate page that collects
all todo
admonitions and provides an overview of all pending todos within the
document.
That's a good idea! I'd like to include the extension when it's
finished.
Post by Georg Brandl
Post by d***@comnets.rwth-aachen.de
I did not find any support for this within the current release of
Sphinx, so I started
todo & todolist
that should take care of the task. The basic functionality works now,
but I still face
http://pastebin.com/f55ea9fe0
http://pastebin.com/f7913c13a
1. I only want to include the todolist page in the TOC if the
configuration flag is set.
   The todolist page is now always included, although it is empty if
the configuration file
   is not set. I want it to completely vanish.
Hmm... there's no API yet for excluding items from the TOC.
Of course, as a hack-around, you could generate the document heading
only
Post by Georg Brandl
if the "todo" option is set. Then, since there is no heading in the
document,
Post by Georg Brandl
none will show up in the TOC.
Post by d***@comnets.rwth-aachen.de
2. With this implementation all todo admonitions show up in the final
document as
The todo description'''
If you modify your make_admonition call a bit, that should be fine. Look
    seealsonode = make_admonition(
        addnodes.seealso, name, [_('See also')], options, content,
        lineno, content_offset, block_text, state, state_machine)
IOW, the "arguments" arg is replaced by your wanted title.
Post by d***@comnets.rwth-aachen.de
3. In the todolist I only copy the original todo. It would be nice to
include additional
   information there, such as a link to the original todo location and
the original location within the
   source (filename, linenumber, etc.)
For the link to the location, you can put a "target" node at the point
where the todo directive occurs. Look at the index directive for an
example.
Post by Georg Brandl
I see that you store all todo nodes as an attribute of the node class.
This will not work with partial builds, when only changed files are
parsed.
Post by Georg Brandl
The canonical way is to use an attribute of the environment object,
which
Post by Georg Brandl
is pickled and restored between calls.
Post by d***@comnets.rwth-aachen.de
I am a little bit stuck here and wonder if someone could help. I
already tried the sphinx.ext.ifconfig
to exclude the todolist from the TOC, but this does not work. I think
Sphinx does not expect any directive within the TOC.
That's true. It doesn't interpret the content in the "normal" way.
cheers,
Georg
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To post to this group, send email to sphinx-***@googlegroups.com
To unsubscribe from this group, send email to sphinx-dev+***@googlegroups.com
For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en
-~----------~----~----~----~------~----~------~--~---
Georg Brandl
2008-11-09 11:02:06 UTC
Permalink
Post by d***@comnets.rwth-aachen.de
content of todo'. It
did not work by simply putting 'Todo' in the argument list. It showed
up then as 'Note: Todo:'.
I needed to create a new node type 'todoNode' and add appropriate
visitors. The Sphinx documentation
is not up to date I think, addNode does not take any visitor arguments
anymore, so I helped myself
by using setattr on the translator object. This did the job. Maybe
there is a better way?
It is the other way around :) The visitor arguments are new in the tip,
which will be 0.5 shortly, while you are using 0.4.3.
Post by d***@comnets.rwth-aachen.de
I manged to include a target node for each todo item, but I did not
find how to actually insert a
reference to these labels in the todolist. How is this done? I cannot
find the code that actually
generates the index pages.
I also collect all todo nodes at the environment object now.
http://pastebin.com/m2b02f72b
If you want to include references to the target nodes, you have to
construct some reference nodes and let them point to the target nodes.
You'll have to include the docname of the todo node in the entry in
all_todos, and then best look into resolve_references() in environment.py
how to get reference nodes.

Some other minor comments:

* there is still allTodos in class todolist.
* the target node should come before the todo node in the return of
todo_directive().
* the global "app" isn't needed AFAICS.
* instead of setting tagname to the todo node, you can use
``doctree.traverse(todoNode)``.

cheers,
Georg

--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To post to this group, send email to sphinx-***@googlegroups.com
To unsubscribe from this group, send email to sphinx-dev+***@googlegroups.com
For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en
-~----------~----~----~----~------~----~------~--~---
d***@comnets.rwth-aachen.de
2008-11-09 12:18:20 UTC
Permalink
Thanks for the resolve_references() in environment.py hint. I followed
that
code and inserted my own references. Unfortunately the docutils/
writers/html4css1/__init__.py
chokes on that. The assertion below fails:

def visit_reference(self, node):
atts = {'class': 'reference'}
if node.has_key('refuri'):
atts['href'] = node['refuri']
if ( self.settings.cloak_email_addresses
and atts['href'].startswith('mailto:')):
atts['href'] = self.cloak_mailto(atts['href'])
self.in_mailto = 1
atts['class'] += ' external'
else:
assert node.has_key('refid'), \
'References must have "refuri" or "refid"
attribute.'
atts['href'] = '#' + node['refid']
atts['class'] += ' internal'
if not isinstance(node.parent, nodes.TextElement):
---> assert len(node) == 1 and isinstance(node[0],
nodes.image) <--- This one fails
atts['class'] += ' image-reference'
self.body.append(self.starttag(node, 'a', '', **atts))

I tried to set the parent node of the reference node manually, but
somehow it gets replaced.
If I use the debugger an print node at that position I get:

p node.parent
<section "todo list":
<title...><paragraph...><todoNode...><reference...><todo ...>

Here is how I construct the reference in the process_todolist
callback:

r = []
for (docname, todoNode, target) in env.all_todos:

newnode = nodes.reference('', '')
innernode = nodes.emphasis("Dummy", "Dummy")
newnode['refdocname'] = docname
newnode['refuri'] = "../not/yet/correct/TBD#soon"
newnode.append(innernode)
r += [newnode, todoNode.deepcopy()]
node.replace_self(r)

I basically copied that from environment.py . Did I miss something
there? Any ideas?

Cheers, Daniel
Post by Georg Brandl
Post by d***@comnets.rwth-aachen.de
content of todo'. It
did not work by simply putting 'Todo' in the argument list. It showed
up then as 'Note: Todo:'.
I needed to create a new node type 'todoNode' and add appropriate
visitors. The Sphinx documentation
is not up to date I think, addNode does not take any visitor arguments
anymore, so I helped myself
by using setattr on the translator object. This did the job. Maybe
there is a better way?
It is the other way around :) The visitor arguments are new in the tip,
which will be 0.5 shortly, while you are using 0.4.3.
Post by d***@comnets.rwth-aachen.de
I manged to include a target node for each todo item, but I did not
find how to actually insert a
reference to these labels in the todolist. How is this done? I cannot
find the code that actually
generates the index pages.
I also collect all todo nodes at the environment object now.
http://pastebin.com/m2b02f72b
If you want to include references to the target nodes, you have to
construct some reference nodes and let them point to the target nodes.
You'll have to include the docname of the todo node in the entry in
all_todos, and then best look into resolve_references() in environment.py
how to get reference nodes.
* there is still allTodos in class todolist.
* the target node should come before the todo node in the return of
  todo_directive().
* the global "app" isn't needed AFAICS.
* instead of setting tagname to the todo node, you can use
  ``doctree.traverse(todoNode)``.
cheers,
Georg
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To post to this group, send email to sphinx-***@googlegroups.com
To unsubscribe from this group, send email to sphinx-dev+***@googlegroups.com
For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en
-~----------~----~----~----~------~----~------~--~---
Georg Brandl
2008-11-09 12:48:05 UTC
Permalink
Post by d***@comnets.rwth-aachen.de
Thanks for the resolve_references() in environment.py hint. I followed
that
code and inserted my own references. Unfortunately the docutils/
writers/html4css1/__init__.py
atts = {'class': 'reference'}
atts['href'] = node['refuri']
if ( self.settings.cloak_email_addresses
atts['href'] = self.cloak_mailto(atts['href'])
self.in_mailto = 1
atts['class'] += ' external'
assert node.has_key('refid'), \
'References must have "refuri" or "refid"
attribute.'
atts['href'] = '#' + node['refid']
atts['class'] += ' internal'
---> assert len(node) == 1 and isinstance(node[0],
nodes.image) <--- This one fails
atts['class'] += ' image-reference'
self.body.append(self.starttag(node, 'a', '', **atts))
I tried to set the parent node of the reference node manually, but
somehow it gets replaced.
p node.parent
<title...><paragraph...><todoNode...><reference...><todo ...>
Here is how I construct the reference in the process_todolist
r = []
newnode = nodes.reference('', '')
innernode = nodes.emphasis("Dummy", "Dummy")
newnode['refdocname'] = docname
newnode['refuri'] = "../not/yet/correct/TBD#soon"
newnode.append(innernode)
r += [newnode, todoNode.deepcopy()]
node.replace_self(r)
I basically copied that from environment.py . Did I miss something
there? Any ideas?
I'm not sure right now, but I'd try putting the new reference into a
paragraph node of its own.

Georg

--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To post to this group, send email to sphinx-***@googlegroups.com
To unsubscribe from this group, send email to sphinx-dev+***@googlegroups.com
For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en
-~----------~----~----~----~------~----~------~--~---
d***@comnets.rwth-aachen.de
2008-11-09 14:24:44 UTC
Permalink
Yes. That did the trick. I have cleaned up the code and have put a new
version here:

http://pastebin.com/f71ba7373

It works quite well. And I think it is nearly finished. There are
still some open issues

1) Backlinks don't work in the PDF version.
2) The todolist page does not get rebuilt if somewhere in the
document new todos appear or a re removed.
3) The CSS needs to be adopted with a default layout of the todo
admonitions.

What do you think?

Regards,
Daniel
Post by Georg Brandl
Post by d***@comnets.rwth-aachen.de
Thanks for the resolve_references() in environment.py hint. I followed
that
code and inserted my own references. Unfortunately the docutils/
writers/html4css1/__init__.py
        atts = {'class': 'reference'}
            atts['href'] = node['refuri']
            if ( self.settings.cloak_email_addresses
                atts['href'] = self.cloak_mailto(atts['href'])
                self.in_mailto = 1
            atts['class'] += ' external'
            assert node.has_key('refid'), \
                   'References must have "refuri" or "refid"
attribute.'
            atts['href'] = '#' + node['refid']
            atts['class'] += ' internal'
--->            assert len(node) == 1 and isinstance(node[0],
nodes.image) <--- This one fails
            atts['class'] += ' image-reference'
        self.body.append(self.starttag(node, 'a', '', **atts))
I tried to set the parent node of the reference node manually, but
somehow it gets replaced.
p node.parent
<title...><paragraph...><todoNode...><reference...><todo ...>
Here is how I construct the reference in the process_todolist
r = []
    newnode = nodes.reference('', '')
    innernode = nodes.emphasis("Dummy", "Dummy")
    newnode['refdocname'] = docname
    newnode['refuri'] = "../not/yet/correct/TBD#soon"
    newnode.append(innernode)
    r += [newnode, todoNode.deepcopy()]
node.replace_self(r)
I basically copied that from environment.py . Did I miss something
there? Any ideas?
I'm not sure right now, but I'd try putting the new reference into a
paragraph node of its own.
Georg
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To post to this group, send email to sphinx-***@googlegroups.com
To unsubscribe from this group, send email to sphinx-dev+***@googlegroups.com
For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en
-~----------~----~----~----~------~----~------~--~---
Georg Brandl
2008-11-09 17:40:03 UTC
Permalink
Post by d***@comnets.rwth-aachen.de
Yes. That did the trick. I have cleaned up the code and have put a new
http://pastebin.com/f71ba7373
It works quite well. And I think it is nearly finished. There are
still some open issues
1) Backlinks don't work in the PDF version.
2) The todolist page does not get rebuilt if somewhere in the
document new todos appear or a re removed.
3) The CSS needs to be adopted with a default layout of the todo
admonitions.
What do you think?
Looks good! I'll take it from here and add it to the repo, if you're
fine with it.

cheers.
Georg

--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To post to this group, send email to sphinx-***@googlegroups.com
To unsubscribe from this group, send email to sphinx-dev+***@googlegroups.com
For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en
-~----------~----~----~----~------~----~------~--~---
d***@comnets.rwth-aachen.de
2008-11-09 17:55:04 UTC
Permalink
Great!

Thanks,
Daniel
Post by Georg Brandl
Post by d***@comnets.rwth-aachen.de
Yes. That did the trick. I have cleaned up the code and have put a new
http://pastebin.com/f71ba7373
It works quite well. And I think it is nearly finished. There are
still some open issues
   1) Backlinks don't work in the PDF version.
   2) The todolist page does not get rebuilt if somewhere in the
document new todos appear or a re removed.
   3) The CSS needs to be adopted with a default layout of the todo
admonitions.
What do you think?
Looks good! I'll take it from here and add it to the repo, if you're
fine with it.
cheers.
Georg
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To post to this group, send email to sphinx-***@googlegroups.com
To unsubscribe from this group, send email to sphinx-dev+***@googlegroups.com
For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en
-~----------~----~----~----~------~----~------~--~---
Georg Brandl
2008-11-09 18:47:55 UTC
Permalink
OK, update to tip -- rev 744:99e97f4646e1 has the new extension!

Let me know if it works for you,

Georg
Post by d***@comnets.rwth-aachen.de
Great!
Thanks,
Daniel
Post by Georg Brandl
Post by d***@comnets.rwth-aachen.de
Yes. That did the trick. I have cleaned up the code and have put a new
http://pastebin.com/f71ba7373
It works quite well. And I think it is nearly finished. There are
still some open issues
1) Backlinks don't work in the PDF version.
2) The todolist page does not get rebuilt if somewhere in the
document new todos appear or a re removed.
3) The CSS needs to be adopted with a default layout of the todo
admonitions.
What do you think?
Looks good! I'll take it from here and add it to the repo, if you're
fine with it.
cheers.
Georg
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To post to this group, send email to sphinx-***@googlegroups.com
To unsubscribe from this group, send email to sphinx-dev+***@googlegroups.com
For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en
-~----------~----~----~----~------~----~------~--~---
Yarko
2008-11-09 19:24:25 UTC
Permalink
Thanks for all your effort on this. I will put it to use immediately on our project.

Yarko

-----Original Message-----
From: ***@comnets.rwth-aachen.de
Sent: Sunday, November 09, 2008 8:24 AM
To: sphinx-dev <sphinx-***@googlegroups.com>
Subject: Re: Implementation of a ToDo directive


Yes. That did the trick. I have cleaned up the code and have put a new
version here:

http://pastebin.com/f71ba7373

It works quite well. And I think it is nearly finished. There are
still some open issues

1) Backlinks don't work in the PDF version.
2) The todolist page does not get rebuilt if somewhere in the
document new todos appear or a re removed.
3) The CSS needs to be adopted with a default layout of the todo
admonitions.

What do you think?

Regards,
Daniel
Post by d***@comnets.rwth-aachen.de
Thanks for the resolve_references() in environment.py hint. I followed
[The entire original message is not included]

--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To post to this group, send email to sphinx-***@googlegroups.com
To unsubscribe from this group, send email to sphinx-dev+***@googlegroups.com
For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en
-~----------~----~----~----~------~----~------~--~---
Georg Brandl
2008-11-09 19:25:23 UTC
Permalink
Post by Yarko
Thanks for all your effort on this. I will put it to use immediately on our project.
Sphinx itself uses it too; see e.g. <http://sphinx.pocoo.org/ext/coverage.html>.

Georg

--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To post to this group, send email to sphinx-***@googlegroups.com
To unsubscribe from this group, send email to sphinx-dev+***@googlegroups.com
For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en
-~----------~----~----~----~------~----~------~--~---

Continue reading on narkive:
Loading...