sphinx_social_cards.plugins.github¶

This plugin demonstrates how to add custom context and layouts. The purpose here is to get information from GitHub (eg stars, forks, etc) and use it in a new pre-designed layout.

Enabling¶

To enable this plugin, add it to your list of sphinx extensions in conf.py:

extensions = [
    "sphinx_social_cards",
    "sphinx_social_cards.plugins.github",
]

Configuration¶

This extension uses html_theme_options[repo_url] from sphinx-immaterial configuration value or its own repo_url configuration value to set the repository URL.

repo_url : str = ''¶

conf.py¶

repo_url = "https://github.com/2bndy5/sphinx-social-cards"

The repository’s required identifying information (owner and repo) can also be parsed from the site_url if it uses a standard GitHub Pages address (https://<owner>.github.io/<repo>).

Dependencies¶

To cache the owner/repository information, the appdirs dependency is needed. This can either be install directly:

pip install appdirs

or using the sphinx-social-cards package’s optional dependency:

sphinx-social-cards[github]

def get_cache_dir() -> str:
    time_fmt = "%B %#d %Y" if platform.system().lower() == "windows" else "%B %-d %Y"
    today = time.strftime(time_fmt, time.localtime())
    cache_dir = Path(
        user_cache_dir(
            "sphinx_social_cards.plugins.github",
            "2bndy5",
            version=today,  # (1)!
        )
    )
    if cache_dir.parent.exists() and not cache_dir.exists():
        shutil.rmtree(cache_dir.parent)  # purge the old cache
    return str(cache_dir)

Added Layouts¶

These are examples of the layouts added:

github/default github/default-dark

Added Context¶

This plugin adds the following members to the plugin.* jinja context:

class Github¶

A dict that can be accessed via plugin.vcs.github jinja context

owner : Owner¶

The github account owner information.

repo : Repo¶

The github account repo information.

repo Sub-Context¶

class Repo¶

A dict that can be accessed via plugin.vcs.github.repo jinja context

stars : int | str¶

The number of repository stars.

watchers : int | str¶

The number of repository watchers.

forks : int | str¶

The number of repository forks.

license : str¶

The name of the license(s).

open_issues : int | str¶

The number of open repository issues.

topics : List[str]¶

The list of search topics designated for the repository.

name : str | None¶

The name of the repository.

description : str | None¶

The repository description.

language : str | None¶

The primarily used program language in the repository.

languages : Dict[str, float]¶

A dict of the used program languages in the repository. Each key is a language’s name (eg. “Python”), and each value is the corresponding language’s percent used (eg “97.8”).

homepage : str | None¶

The repository’s designated outreach website (with protocols like https:// stripped).

html_url : str | None¶

The repository GitHub.com URI (with protocols like https:// stripped).

tags : List[str]¶

A list of the repository’s tags (str). These values seem to be ordered in recent descending to oldest tagged commits.

contributors : List[Contributor]¶

A list of the repository’s contributors.

owner Sub-Context¶

class Owner¶

A dict that can be accessed via plugin.vcs.github.owner jinja context

login : str¶

The account’s name.

avatar : str¶

The account’s avatar image’s URL.

type : str¶

The account’s type (eg “User” or “Organization”).

name : str | None¶

The account user’s human name.

followers : int | str¶

The number of users that the account is following.

following : int | str¶

The number of users that are following the account.

bio : str | None¶

The account profile’s brief description.

blog : str | None¶

A link to a blog site.

hirable : bool | None¶

A flag indicating the user is available for employment.

email : str | None¶

The publicly available email (if any).

location : str | None¶

The account profile’s location.

public_repos : int | str¶

The number of public repositories for the account.

public_gists : int | str¶

The number of public gists for the account.

twitter_username : str | None¶

The account user’s twitter username.

html_url : str | None¶

The URI to the GitHub.com site (with protocols like https:// stripped).

organizations : List[Organization]¶

A list of the Organizations to which the account belongs.

User List Sub-Contexts¶

class Contributor¶

A dict that can be accessed via each item listed in the plugin.vcs.github.repo.contributors jinja context

contributions : int | str¶

The account’s contributions count.

login : str¶

The account’s name.

avatar : str¶

The account’s avatar image’s URL.

class Organization¶

A dict that can be accessed via each item listed in the plugin.vcs.github.owner.organizations jinja context

description : str¶

The organization’s profile description

login : str¶

The account’s name.

avatar : str¶

The account’s avatar image’s URL.