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

Create a SphinxExtension that help register Sphinx extension members via decorators

    XMLWordPrintable

    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

          Issue Links

            Activity

            Hide
            tjenness Tim Jenness added a comment -

            Is this ticket still relevant?

            Show
            tjenness Tim Jenness added a comment - Is this ticket still relevant?
            Hide
            jsick Jonathan Sick added a comment -

            I've decided this approach won't be beneficial, so we'll mark as invalid.

            Show
            jsick Jonathan Sick added a comment - I've decided this approach won't be beneficial, so we'll mark as invalid.

              People

              Assignee:
              jsick Jonathan Sick
              Reporter:
              jsick Jonathan Sick
              Watchers:
              Jonathan Sick, Tim Jenness
              Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved:

                  Jenkins

                  No builds found.