1

Before I run off the in wrong direction, if adding a new output format to Sphinx, might one have to add special case code to all existing Sphinx extensions?

For example I see that the 'todo' extension seems to try and use admonitions but has to have special case latex code - might I have to do similar for every extension that someone might use unless I can do some similar jiggery-pokery to reuse existing formatting features?

deceze
  • 510,633
  • 85
  • 743
  • 889
Paul D Smith
  • 639
  • 5
  • 16
  • If you don't get an answer, suggest asking on one of their official support channels: [sphinx-users](https://groups.google.com/group/sphinx-users), #sphinx-doc channel on FreeNode, or opening an issue https://github.com/sphinx-doc/sphinx/issues Otherwise there is the docs for [Developing extensions for Sphinx](http://www.sphinx-doc.org/en/master/extdev/index.html). – Steve Piercy Apr 23 '18 at 20:08

1 Answers1

1

All extensions that make use of Sphinx's add_node() function need to be adjusted to cover the new output format. Otherwise, your new output format builder will not be able to process the custom nodes. You still should be able to build, though.

However, let me clarify the following:

  • Not all extensions make use of add_node().
  • In many cases, you should be able to register an already existing function for the new output format, just like in the example of the extension development tutorial in the Sphinx documentation.
  • You should be able to override the add_node() registrations of the extensions you use without modifying the source code of the extensions by re-registering the nodes at the end of your project's conf.py file.
Timotheus.Kampik
  • 2,425
  • 1
  • 22
  • 30
  • Are you saying this? Extensions can create new nodes, and might add support for these nodes for the standard Sphinx builders. New builders can implement their own version of the visit/depart_new_node() methods to improve their own output. So extensions might define new nodes that a builder doesn't support (Sphinx defaults to the 'text' output) and a builder might implement visit/depart methods for extensions that the user does not require. Extensions should only contain visit/depart for the standard Sphinx builders. – Paul D Smith Apr 25 '18 at 13:00