Sphinx extension writing tutorial

[Matěj Týč]

Hello,
I would like to write an extension. (if that matters, I would like a directive for elaborate quotations so you can specify the book, page, chapter and the quotation and as a result, everything is formatted in a nice and easily customizable way.)
Anyway, I have found the extension tutorial:
http://sphinx-doc.org/extdev/tutorial.html
and although it has some nice points, it can be worked on:

1. In the directive class implementation (http://sphinx-doc.org/extdev/tutorial.html#the-directive-classes), there is the  make_admonition function used. Not only is this function absolutely undocumented, it is also the only function of this kind in its package, and there is not any description of what it does in the tutorial. Therefore, it is very difficult to learn anything from it. i.e. if I want something different than a todo-list, what should I do?

2. The visit_todo_node(self, node) looks like a function that is used later to monkey-patch a class. I would love to read more about its purpose, but it seems to me that the best option is to take a look at the source, which is a pity.

What confuses me most is that both the Directive class and visit_* and depart_* functions influence what happens to the document when a particular directive is encountered in the source. The run method of the class is able to do a lot of advanced stuff at the background at the high level, whereas the functions are more subtle and they work on lower level (they can be i.e. html- and tex- specific, if I am right).
But what is the big idea behind this?

Could you please provide me with some information? I believe that together, we can greatly expand and improve the tutorial.

[Bryan Van de ven]

FWIW I just recently create several extension directives, roles, and auto documenters for the Bokeh project:

http://bokeh.pydata.org/en/dev/docs/reference/sphinxext.html

Including ones to inline live Bokeh plots, to automatically document our special model classes that have metaclasses that confuse autodoc, to automatically refer to GH resources, and to add a code-block that can be in a collapsible accordion layout. 

I agree the lack of documentation (there's an irony here somewhere...) is a big problem. Especially for docutils. Although I now regard writing extensions as a somewhat straightforward task, I was only able to get to that point of understanding by trawling through the bowels of both the sphinx and docutils source code. I'd like to write a blog post about my experience but I am not sure when I will have the time. In case looking at some example source is helpful to you, here is the source for the extensions I created:

https://github.com/bokeh/bokeh/tree/master/bokeh/sphinxext

Also a few of the most egregious problems:

* The API pages linked in the tutorial are not complete!! I naively assumed a page called, e.g, "Builder API" would at least actually list all the method available. I was on the verge of giving up the project, lamenting that simple things I would need to do were just not possible, before I discovered there was quite a bit more (but only by looking at the actual source code)

* Parameters and attributes for docutils node and node creation helper functions are completely nonexistent AFAICT. Because of this, I have  on occasion had to resort to using visitors on custom nodes in the build phase, even though I am almost certain it could be done better with existing docutils node, if I could find any clue how to use them. 

* There is almost no docs at all for creating auto-documenters. Once you "grok" how things work, it's actually quite awesome and simple. I thought I was gong to have to write pages of code to create my own auto documenters. Then I realize (again only after carefully studying the autodoc source code) only a handful of lines were needed, you just have to realize what it takes to "plug in" your directives. I would say this mere information would have saved me half a day:

* create a custom directive to document whatever special thing you have

* "plug" this directive into autodoc but creating an autodoc subclass configured with:

  - this custom directive's name, and 

  - a higher priority than the default auto-documenter for this type

Voila, about 10 lines and autodoc will happily use your directive everywhere it should. 

Anyway, I hope this is helpful. Assuming I can get around to a blog post I will definitely share it here.