Skip to main content

Tools for integrating affiliated Sphinx sites

Project description

sphinx-affiliates

CI status License: MIT

Allow search to include documents from more than one Sphinx documentation html site.

This is useful when you have a number of github repositories under one org, are using sphinx to build documentation for all of them, and github pages to serve the artifacts. When you configure a custom domain, say https://my.site.org, for one repo in the org, any other repo's github pages (say repo2) will be visible as https://my.site.org/repo2. But the search.html from the sites will not know about eachother: they will be completely independent. This extension will solve that by

  • changing the search engine to allow loading more than one index
  • changing the search index generation process to generate an additional index
  • add configuration options to add the additional indices, from affiliate sites, to the search.html page.

To use this, install it via pip and add something like this to your conf.py

extensions = [
    'sphinx_affiliates',   # Add the extension
]

# Where this site's build is hosted, this will be the URL for all the search
# results from this site.
affiliate_options = {
    'canonical_url': "https://affiliate_search.github.io",
}

# Other sites to add to the search of this site. HTTP urls may get blocked
# as cross-site scripting
sphinx_affiliates = [
    '../other_repo1/affiliate_searchindex.js',
    'https://affiliate_search.github.io/other_repo2/affiliate_searchindex.js',
]

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

sphinx_affiliates-0.2.1-py3-none-any.whl (10.1 kB view hashes)

Uploaded Python 3

sphinx_affiliates-0.2.1-py2-none-any.whl (10.1 kB view hashes)

Uploaded Python 2

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page