Uploaded image for project: 'Data Management'
  1. Data Management
  2. DM-15900

Create a SphinxExtension that help register Sphinx extension members via decorators

    Details

      Description

      From experience creating Sphinx extensions (DM-15821), it's clear that extensions can have lots of members that need to be tracked by the setup function. I think this can be made easier by using decorators that register directives, roles, and so forth, and then using that centralized registry to auto-populate the setup function.

      It looks something like this:

             from docutils import nodes
             from docutils.parsers.rst import Directive
       
             from documenteer.sphinxext.utils import SphinxExtension
       
       
             # module-level instance. All members of the Sphinx extension refer to
             # this instance.
             extension = SphinxExtension()
       
             # Decorate a directive class to register it with the extension
             @extension.directive
             def MyDirective(Directive):
       
                 # By putting a ``name`` attribute in your directive, SphinxExtension
                 # will use that name for the directive name.
                 name = "my-directive"
       
                 def run(self):
                     return [nodes.paragraph(text='Hello world')
       
              # Now your setup function just calls the setup method on the
              # SphinxExtension instance
              def setup():
                  extension.setup()
      

        Attachments

          Container Issues

            Activity

              People

              • Assignee:
                jsick Jonathan Sick
                Reporter:
                jsick Jonathan Sick
                Watchers:
                Jonathan Sick
              • Votes:
                0 Vote for this issue
                Watchers:
                1 Start watching this issue

                Dates

                • Created:
                  Updated:

                  Summary Panel