Menu

#82 Add support for registering plugins, ideally through docutils

Default
open
nobody
None
5
2021-09-24
2021-09-23
No

There's a large community of plugins and documents built around Sphinx, but less so around plain Docutils. That's too bad, because Docutils is a really great piece of software, and the standard toolchain works wonderfully for single-page documents, including academic papers, slide decks, or websites.

As far as I can tell, one of the main missing features is a standardized extension mechanism. Customizable roles and directives are one of Docutils strengths, but if I write a package that defines directives I have a good way to plug it into Sphinx or Pelican, but no natural way to plug it into Docutils directly (one that would allow me to use rst2html5.py directly).

Instead, the most convenient way to do this is to write a custom python driver, as far as I can tell: you need first call register_directive, register_canonical_role, etc; and then you call publish_cmdline. That's a lot of work for end users, compared to Sphinx' list of plugins.

As a result of this, we have many directives and plugins that work with one Docutils frontend but not another. This came up in a recent discussion about bibliography support: there is an excellent extension called sphinxcontrib-bibtex, but it does not work with plain Docutils or with Pelican; only with Sphinx.

It would be great if there was a standard, documented way to extend Docutils. Maybe that could be a setuptools entry point, as is done with Pygments? Ideally one could register extra frontends, backends, directives, and roles that way, and users would just need to list in docutils.conf which plugins they intend to use. I expect many plugins would then be able to target "pure docutils", adding features specific to Sphinx only as a progressive enhancement.

(Oh, and we would likely need a single command line application, instead of one per frontend/backend pair, of course)

Please let me know your thoughts!

Discussion

  • Clément Pit-Claudel

    Sorry, SourceForge is a pain and I can't find how to edit my original issue, which got posted too soon. There are typos in this sentence:

    This cane up in a recent discussion about bibliography support: there is an excellent extension called sphinxcontrib-bibtex, but it does not work with plain Docutils or with Pelican; only with Docutils.

    It should be: This came up in a recent discussion about bibliography support: there is an excellent extension called sphinxcontrib-bibtex, but it does not work with plain Docutils or with Pelican; only with Sphinx. Here is a link: https://github.com/mcmtroffaes/pybtex-docutils/pull/16

     
  • Günter Milde

    Günter Milde - 2021-09-24

    Thank you for the suggestion. A plugin API is desirable, indeed. It will take a lot of discussion and planning, though, as once offered it is hard to change.

    There is a rudimentary plugin system present already: the reader, parser, and writer components are imported using helper functions that search also in the Python-Path (sys.path) for matching modules. This allows for 3rd party drop-in replacements. See the myst-docutils package for an example.

    In future, entry points could be used for plugins providing additional features or modified behaviour. (also cf. [patch:#186])

    we would likely need a single command line application, instead of one
    per frontend/backend pair, of course

    Docutils 0.17 comes with tools/docutils-cli.py, a generic command line front end that allows the free selection of reader, parser, and writer components.

    Since [r8915], docutils-cli.py allows 3rd-party drop-in components for reader, parser, and writer, too: just specify the "import name" of the containing Python module.

     

    Related

    Commit: [r8915]


    Last edit: Günter Milde 2022-01-03

Log in to post a comment.

Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.