python / python-docs-theme

Sphinx theme for Python documentation
Other
74 stars 58 forks source link

Add `hosted_on` variable for a link in the footer #165

Closed hugovk closed 6 months ago

hugovk commented 6 months ago

Helps https://github.com/python/docs-community/issues/5.

If hosted_on is defined in your docs' conf.py:

html_theme_options = {
    'collapsiblesidebar': True,
    'hosted_on': '<a href="https://example.com">Example</a>',
    'issues_url': '/bugs.html',
    'license_url': '/license.html',
    'root_include_title': False   # We use the version switcher instead.
}

Adds a "Hosted by" line to the footer:

image

Conditional

For https://github.com/python/docs-community/issues/5, we can instead add this in conf.py:

if os.getenv("READTHEDOCS"):
    html_theme_options["hosted_on"] = '<a href="https://about.readthedocs.com/">Read the Docs</a>'

And we'll only get the "Hosted by" line for builds created on Read the Docs:

image

Here's a demo build:

If you build that locally or on another server which doesn't have the env var defined, we don't get the link:

image

hugovk commented 6 months ago

This has now been released, so here's the follow-up: https://github.com/python/cpython/pull/114697