Programmatically adding reference targets from a plugin

81 views
Skip to first unread message

Rotem Yaari

unread,
Apr 7, 2013, 4:45:52 AM4/7/13
to sphin...@googlegroups.com
I've written a small plugin to automatically document a certain facility from code. What I couldn't figure out was how to add link targets to make :ref: work properly. Can anyone provide a pointer or a reference for doing this, for instance in this code (let's say, make :ref:`some_id` work as a link elsewhere):

class SampleDirective(Directive):
    has_content = False
    required_arguments = 0
    optional_arguments = 0
    def run(self):
        section = nodes.section(ids=["some_id"])
        section.append(nodes.title(text="Title Here")
        return [section]

Thanks in advance,

Rotem

Takayuki Shimizukawa

unread,
Apr 13, 2013, 1:06:35 PM4/13/13
to sphin...@googlegroups.com
Hi Rotem,

This code works as your expect.

def run(self):
section = nodes.section(names=['some_id'])
self.state.document.note_explicit_target(section)
section.append(nodes.title(text="Title Here"))
return [section]

I could not find reference, but below source code will help you.

* add_target(): setup names and explicit ids to document.nametypes and nameids:
http://repo.or.cz/w/docutils.git/blob/HEAD:/docutils/docutils/parsers/rst/states.py#l1932

* process_doc(): collect labels by using document.nametypes:
https://bitbucket.org/birkenfeld/sphinx/src/357b5d1/sphinx/domains/std.py#cl-481

* resolve_xref(): ref target resolver:
https://bitbucket.org/birkenfeld/sphinx/src/357b5d1/sphinx/domains/std.py#cl-520

Regards,
--
Takayuki SHIMIZUKAWA
http://about.me/shimizukawa


2013/4/7 Rotem Yaari <vma...@gmail.com>:
> --
> You received this message because you are subscribed to the Google Groups
> "sphinx-dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to sphinx-dev+...@googlegroups.com.
> For more options, visit https://groups.google.com/groups/opt_out.
>
>

Rotem Yaari

unread,
Apr 13, 2013, 2:20:24 PM4/13/13
to sphin...@googlegroups.com
This doesn't work for me. Sphinx complains that the :ref: target could not be found. I also tried to link from the same document and it doesn't appear to help.


You received this message because you are subscribed to a topic in the Google Groups "sphinx-dev" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/sphinx-dev/X47u3i18g-E/unsubscribe?hl=en-GB.
To unsubscribe from this group and all of its topics, send an email to sphinx-dev+...@googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.





--
Rotem

Takayuki Shimizukawa

unread,
Apr 14, 2013, 2:42:06 AM4/14/13
to sphin...@googlegroups.com
Hi Rotem,

2013/4/14 Rotem Yaari <vma...@gmail.com>:
> This doesn't work for me. Sphinx complains that the :ref: target could not
> be found. I also tried to link from the same document and it doesn't appear
> to help.

hum...
I checked with Sphinx-1.2b1+docutils-0.10 / Sphinx-1.1.3+docutils-0.7.

Here is all files I tried.
https://dl.dropboxusercontent.com/u/284189/sphinx-link-target-sample.zip

Rotem Yaari

unread,
Apr 14, 2013, 4:02:28 AM4/14/13
to sphin...@googlegroups.com
Whoops, my bad. Turns out I was using (ids=...) instead of (names=...).

Works great now. Thanks!


--
You received this message because you are subscribed to a topic in the Google Groups "sphinx-dev" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/sphinx-dev/X47u3i18g-E/unsubscribe?hl=en-GB.
To unsubscribe from this group and all of its topics, send an email to sphinx-dev+...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.





--
Rotem
Reply all
Reply to author
Forward
0 new messages