Basic Extension Help needed

[Josh English]

I am trying to write a simple extension for Sphinx. What I want to do is build a standard tool for documenting the use of PubSub.

Ideally, my rst would include:

.. message:: documented-with-keyword

   :keyword: boring

   This describes the ``documented-with-keyword`` topic

This would likely be inside a function in the real documents.

I cannot find a tutorial on directives anywhere. Every tutorial I find talks about roles.

I tried a simple file (attached) and built a sample project using quickstart, and I get errors:

Error in "message" directive:

no content permitted

I get this error with or without any content.

Can someone point out what I'm doing wrong? A good site that explains this?

Thanks.

Josh

[Mark Elston]

Hi Josh,

Did you ever get a reply to this?  I am running up against something similar and could use some pointers as well.

Mark

[Takayuki Shimizukawa]

Hi,

I think the extension tutorial page is useful:

- http://sphinx-doc.org/ext/tutorial.html
- http://docutils.sourceforge.net/docs/howto/rst-directives.html

And, I think my small source code is close to your purpose:

- https://bitbucket.org/shimizukawa/sphinxjp.themes.s6/src/tip/src/sphinxjp/themes/s6/directives.py

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


2013/7/7 Mark Elston <melst...@gmail.com>:

> --
> You received this message because you are subscribed to the Google Groups
> "sphinx-users" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to sphinx-users...@googlegroups.com.
> To post to this group, send email to sphinx...@googlegroups.com.
> Visit this group at http://groups.google.com/group/sphinx-users.
>
> For more options, visit https://groups.google.com/groups/opt_out.
>
>

[Josh English]

No luck so far. I opted to use a table in the function documentation
listing the topic, the arguments, and a description of when it is
sent.

I think this works as far as function and method documentation goes.

I would like to be able to document the entire topic tree on a single
page, like a glossary. Now that I've played with TopicTreeTraversers
and Visitors in PyPubSub, I may be able to get a directive working
that would document the tree, but I haven't played with it yet. I need
to go relearn everything.


I'll also look over Takayuki Shimizukawa's code and see if it makes sense to me.

> You received this message because you are subscribed to a topic in the Google Groups "sphinx-users" group.
> To unsubscribe from this topic, visit https://groups.google.com/d/topic/sphinx-users/vFpUgwj7bG0/unsubscribe.
> To unsubscribe from this group and all its topics, send an email to sphinx-users...@googlegroups.com.

> To post to this group, send email to sphinx...@googlegroups.com.
> Visit this group at http://groups.google.com/group/sphinx-users.
> For more options, visit https://groups.google.com/groups/opt_out.
>
>

--
Josh English
Joshua.R...@gmail.com
http://www.joshuarenglish.com

[Mark Elston]

Shimizukawa-san,

Thanks a lot for the pointers.  Your example helped me get over the hump on adding a new directive which was one of two approaches I was trying to explore.  As my needs called for either a single argument or a single option it was pretty simple to get it going.  The only problem I had was that the contents of the block didn't get substitutions done on it.  Then I looked in the container directive and saw the call to

  self.state.nested_parse(...)

This solved my problem and I am now off and running.

Josh, if you are having problems with doing this yourself perhaps I can help out a little.

Thanks again.

Mark

[Josh English]

It's been a month. I stepped away for a month to avoid trichotillomania.

I'm actually working on a completely different project, not related to coding, but one where I feel Restructured Text and Sphinx could be useful.

If I can get these to work. I have a bunch of roles and directives I would like to use in my text, and create index pages with back references. It's a discussion and analysis of short stories, so I'd like to write one story per page, and use directives like

.. writer:: Josh English

.. magazine:: Aoife's Kiss

.. issue:: 24

.. pov:: Third person

.. tense:: past 

and so on. I would like to have a page where I can create a WriterList, and list all the writers in alphabetical order (with backlinks to the stories), and do the same with magazines (with back links), and so on.

I followed the tutorial at http://sphinx-doc.org/ext/tutorial.html. I ignored the configuration file options.

I get the error File "c:\Users\Josh\Desktop\storyaday\extensions\writernode.py", line 62, in process_writer_nodes

    for writer_info in env.writer_all_writers:

AttributeError: BuildEnvironment instance has no attribute 'writer_all_writers'

I've attached the extension, and the error log. 

I swear I have crossed checked every character from the tutorial, and the only changes are using "writer" instead of "todo" (minus the configuration variable).

Can someone please take a look at this and tell me what I'm doing wrong?

Josh

[Takayuki Shimizukawa]

Hi Josh,

I ran your extension, but another error was occurred.
I've checked your code and fixed 2 problems,
https://gist.github.com/shimizukawa/6255385/revisions
Now this works for me.

Debugging Tips in the Sphinx Developer's Guide document will help you.
https://bitbucket.org/birkenfeld/sphinx/src/ef3092d/doc/devguide.rst#rst-header-debugging-tips

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

2013/8/17 Josh English <joshua.r...@gmail.com>:

[Josh English]

Thanks. I didn't see those. Now I'm getting the same error: 

File "C:\Users\Josh\Desktop\storyaday\extensions\writernode.py", line 62, in process_writer_nodes

    for writer_info in env.writer_all_writers:

AttributeError: BuildEnvironment instance has no attribute 'writer_all_writers'

When you say it works, in what way? 

Josh

[Josh English]

Hold on. I found yet another typo.

It's working now. Thank you. The next trick is making it what I want.

Josh

> --
> You received this message because you are subscribed to a topic in the
> Google Groups "sphinx-users" group.
> To unsubscribe from this topic, visit
> https://groups.google.com/d/topic/sphinx-users/vFpUgwj7bG0/unsubscribe.
> To unsubscribe from this group and all its topics, send an email to

> sphinx-users...@googlegroups.com.
> To post to this group, send email to sphinx...@googlegroups.com.
> Visit this group at http://groups.google.com/group/sphinx-users.
> For more options, visit https://groups.google.com/groups/opt_out.

[Josh English]

With more tweaking, I managed to get what I want. Thank you for all your help. 

Josh