Sphinx Custom Directives

[Vinicius Kwiecien Ruoso]

Hi all,

I'm using Sphinx to generate nice looking and informative
documentations. It is a great tool.

I'm having annoying problems when using my reST files created to work
with Sphinx with other tools that use docutils as a middleware. More
precisely, I'm using Robot Framework to read and execute my test
files. The idea is to have one file that Sphinx can use to generate
nice docs, and robot can use to execute the tests.

The problem is that Sphinx (and Sphinx plugins) define lots of
directives that will only work (or make sense) with Sphinx. This
causes docutils to generate lots of errors/warning about stuff that is
not defined by it [2].

The question is: there is some way to ignore errors/warnings of
directives that Sphinx define? The ideia is not to suppress all
errors/warnings docutils generates, but only those related to Sphinx
stuff.

Any hints would be appreciated. I'm also adding the link to the
discussion at robot list [1].

Greetings,
Vinicius

[1] https://groups.google.com/d/msg/robotframework-users/0V-q3xJgcZI/pp0Qs39NAwAJ
[2]
tests/resources/settings.rst:2: (ERROR/3) Unknown directive type "highlight".

.. highlight:: robotframework

mpls_tp/bfd_test.rst:15: (ERROR/3) Unknown interpreted text role "ref".
mpls_tp/bfd_test.rst:75: (ERROR/3) Unknown interpreted text role "term".
mpls_tp/bfd_test.rst:82: (ERROR/3) Unknown interpreted text role "term".
mpls_tp/bfd_test.rst:110: (ERROR/3) Unknown interpreted text role "term".
mpls_tp/bfd_test.rst:138: (ERROR/3) Unknown interpreted text role "term".
mpls_tp/bfd_test.rst:290: (ERROR/3) Unknown directive type "automodule".

.. automodule:: mpls_tp.bfd_test
:members:
:undoc-members:
:show-inheritance:

[Guenter Milde]

On 2015-08-05, Vinicius Kwiecien Ruoso wrote:

...

> I'm having annoying problems when using my reST files created to work

> with Sphinx with other tools that use Docutils as a middleware.
...

> The problem is that Sphinx (and Sphinx plugins) define lots of
> directives that will only work (or make sense) with Sphinx. This
> causes docutils to generate lots of errors/warning about stuff that is

> not defined by it.

> The question is: there is some way to ignore errors/warnings of

> directives that Sphinx define? The idea is not to suppress all

> errors/warnings docutils generates, but only those related to Sphinx
> stuff.

I don't know of a ready-made solution.

OTOH, there are two ideas:

* Docutils is extendable, so the calling application can define and
register "mock directives" or compatibility code.
http://docutils.sourceforge.net/docs/howto/rst-directives.html

Example:
rst2beamer does not define a new writer, but modifies and extends
standard Docutils in the front-end wrapper:
https://github.com/myint/rst2beamer

* Another idea is adding a "custom-directive" directive similar to
"custom-role" to rST in Docutils. Then, compatibility definitions
could be done by including an rST document.

Günter

[Vinicius Kwiecien Ruoso]

Hi!

Thanks for your answer.

The first ideia seems simple to implement and I have an idea on how to proceed.

Please, can you elaborate on the second idea? I'm newbie regarding docutils and don't really understand what you mean. I'm thinking about it in some way to "catch" all directives that are not defined, is that right?

Thanks,

Vinicius

[Guenter Milde]

On 2015-08-07, Vinicius Kwiecien Ruoso wrote:

> [-- Type: text/plain, Encoding: quoted-printable --]

> Hi!

> Thanks for your answer.

> The first ideia seems simple to implement and I have an idea on how to
> proceed.

> Please, can you elaborate on the second idea? I'm newbie regarding docutils
> and don't really understand what you mean. I'm thinking about it in some
> way to "catch" all directives that are not defined, is that right?

Not exactly.

>> * Another idea is adding a "custom-directive" directive similar to
>> "custom-role" to rST in Docutils. Then, compatibility definitions
>> could be done by including an rST document.

The "custom-role" directive allows to define new roles in an rst-document:
http://docutils.sourceforge.net/docs/ref/rst/directives.html#custom-interpreted-text-roles
The idea is creating a similar "custom-directive" directive.
(see also http://docutils.sourceforge.net/docs/dev/todo.html#directives)
This would allow to create "fallback directives" in the document or an
included rST file and the document could compile with standard Docutils.


Catching all directives that are not defined would require a different
approach. You would have to dig into the Docutils sources, grep for
"unknown Directive" (or what the exact error message is) and see whether the
error could be changed to a warning or similar in a custom parser.

Günter