sphinx-social-cards Plugins

It is possible to make plugins for this sphinx_social_cards extension. Such plugins can

Creating a Plugin

A typical plugin involves a setup() function and another function that gets called when Sphinx has prepared the builder for use (the builder-inited event). For more details on writing a sphinx extension, see the Sphinx Hello World tutorial.

from sphinx.application import Sphinx

def on_builder_init(app: Sphinx):
    # add contexts, layouts, or images from here
    pass

def setup(app: Sphinx):
    # connect your on_builder_init() to the builder-inited event
    app.connect("builder-inited", on_builder_init)

Cookiecutter Available

This extension is hosted on github with a cookiecutter template that can be used to quickly make a plugin that is ready for deployment. Just clone the repository then run the cookiecutter module on the cloned repository’s “cookiecutter” directory.

git clone https://github.com/2bndy5/sphinx-social-cards
pip install cookiecutter
cookiecutter sphinx-social-cards/cookiecutter

Follow the prompts and it will generate a new python project in the working directory.

Adding Context

First, write a typical sphinx extension that hooks into the builder-inited event. See Creating a Plugin. Then, add a dict of context information to the build environment using add_jinja_context().

Warning

Please do not use hyphenated names in the dict‘s keys as it would cause a Jinja parsing error if not using the dict notation. It is recommended to use snake casing in the key names for user convenience.

{{ plugin['my-ctx'].example }}

{{ plugin.my_ctx.example }}

from sphinx.application import Sphinx
from sphinx_social_cards.plugins import add_jinja_context

def on_builder_init(app: Sphinx):
    my_ctx = {"example": "hello world"}
    add_jinja_context(app, {"my_ctx": my_ctx})

Done! Now the added context is available in the plugin context:

layers:
  - typography:
      content: '{{ plugin.my_ctx.example }}'

Adding Layouts

First, write a typical sphinx extension that hooks into the builder-inited event. See Creating a Plugin. Then, add the directory of layouts from the plugin to the cards_layout_dir list using add_layouts_dir(). The path added must be an absolute path.

Warning

Do not use the same names as the pre-designed layouts. If a default layout exists in the plugin’s layouts path, then it will override the original default layout.

Instead, you should namespace your plugin’s layouts with a subdirectory name. For example, a bitbucket plugin can have layouts in the plugin’s layouts/bitbucket directory. When the layouts are added, the layout bitbucket/default will not override the default layout.

from pathlib import Path
from sphinx.application import Sphinx
from sphinx_social_cards.plugins import add_layouts_dir

def on_builder_init(app: Sphinx):
    add_layouts_dir(app, Path(__file__).parent / "layouts")

Done! Now the search for a specified layout will include the plugin’s directory of layouts.

Adding Images

First, write a typical sphinx extension that hooks into the builder-inited event. See Creating a Plugin. Then, add the directory of images from the plugin to the image_paths list using add_images_dir(). The path added must be an absolute path.

Warning

Do take care of the image names as they can take precedence over another image using the same name from a different path.

Instead, you should namespace your plugin’s images with a subdirectory name. For example, a bootstrap plugin can have images in the plugin’s images/bootstrap folder. When the images are added, the image bootstrap/logo.png will not take precedence over another image named logo.png.

from pathlib import Path
from sphinx.application import Sphinx
from sphinx_social_cards.plugins import add_images_dir

def on_builder_init(app: Sphinx):
    add_images_dir(app, Path(__file__).parent / "images")

Done! Now the search for a specified image will include the plugin’s directory of images.

API Reference

sphinx_social_cards.plugins

This module holds the information that plugins need to interface with the sphinx_social_cards extension. Currently, this module holds the following:

SPHINX_SOCIAL_CARDS_PLUGINS_ENV_KEY = 'sphinx_social_cards_plugins'

The Sphinx builder environment key that points to the plugin jinja contexts.

SPHINX_SOCIAL_CARDS_CONFIG_KEY = 'sphinx_social_cards'

The Sphinx config validated object from conf.py. This key always points to a Social_Cards object.

add_jinja_context(app: Sphinx, jinja_ctx: dict[str, Any])

Adds a dict to the builder environment key for plugin jinja contexts.

add_layouts_dir(app: Sphinx, layouts_dir: str | Path)

Adds a str or Path of new layouts to the cards_layout_dir list.

add_images_dir(app: Sphinx, images_dir: str | Path)

Adds a str or Path of new images to the image_paths list.