Move project-specific extensions into a dedicated directory / package

[Mischback]

Currently, Sphinx's configuration file conf.py acts like one of the project's extensions.

While this works reasonably well for small use-cases (see #5), it is not the desired result.

To Do:

Sphinx's most basic tutorial places the (custom) extension in a folder _ext in the source directory.

From my understanding, the _ext directory may be placed anywhere. It has to be added to Python's PATH. See the section on extending sys.path.

Namespacing might be an issue, so make sure that the project's dedicated extensions don't conflict with other existing extensions (or other packages).

Steps

• create [REPO_ROOT]/extensions/mischback
• add [REPO_ROOT]/extensions to Python path
  • in conf.py:

    import sys
    
    # add the project-specific extensions directory to Python's path
    sys.path.append(join(REPO_ROOT, "extensions"))

• create [REPO_ROOT]/extensions/mischback/sphinx_jinja2_debug.py:

  def activate_jinja2_debug_ext(app):
      """Activate Jinja2 debug extension.
  
      This function is intended to be connected to ``Sphinx``'s
      ``builder-inited`` event (see
      https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx-core-events)
      and will then navigate from the app to the ``jinja.Environment`` and call
      its ``add_extension()`` method.
      """
      if hasattr(app.builder, "templates"):
          app.builder.templates.environment.add_extension("jinja2.ext.debug")
  
  def setup(app):
      """Register the extension with Sphinx.
  
      This function is required by ``Sphinx``'s extension interface, see
      https://www.sphinx-doc.org/en/master/development/tutorials/helloworld.html#writing-the-extension
      for reference.
  
      It connects this plugins (only) function with the ``"builder-inited"`` event, see
      https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx-core-events
      for reference.
      """
      app.connect("builder-inited", activate_jinja2_debug_ext)

• use the new extension
  • in conf.py:

    extensions = [
        # ...
        "mischback.sphinx_jinja2_debug",
    ]

• make the extensions setup() function return the (desired) dictionary (see dry-coding here)