Sphinx extension to silently generate a sitemap for HTML builds
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
sphinx_sitemap
.gitignore
.travis.yml
CHANGELOG.md
CONTRIBUTING.md
LICENSE
README.rst
setup.cfg
setup.py
tox.ini

README.rst

Sphinx Sitemap Generator Extension

A Sphinx extension to silently generate a sitemaps.org compliant sitemap for the HTML version of your Sphinx Documentation.

Build Status PyPI version License: MIT

Installing

Directly install via pip by using:

pip install sphinx-sitemap

Add sphinx_sitemap to the extensions array in your Sphinx conf.py. For example:

extensions = ['sphinx_sitemap']

Set the value of html_baseurl in your Sphinx conf.py to the current base URL of your documentation. For example:

html_baseurl = 'https://my-site.com/docs/'

Note: html_baseurl was introduced in Sphinx 1.8.0. If you are using a version prior to that you must set your base URL to site_url instead.

Multilingual Configuration

For multilingual sitemaps, you have to generate a sitemap per language/locale and then manually add their locations to a sitemapindex file.

The extension will look at the language config value for the current language being built, and the locale_dirs value for the directory for alternate languages, so make sure those are set.

Note: The extension is currently opinionated, in that it will also use the version config value in the generated URL. Setting it to latest is appropriate for most use cases.

The end result is something like the following for each language/version build:

<?xml version="1.0" encoding="utf-8"?>
<urlset xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://my-site.com/docs/en/latest/index.html</loc>
    <xhtml:link href="https://my-site.com/docs/es/latest/index.html" hreflang="es" rel="alternate"/>
    <xhtml:link href="https://my-site.com/docs/fr/latest/index.html" hreflang="fr" rel="alternate"/>
    <xhtml:link href="https://my-site.com/docs/en/latest/index.html" hreflang="en" rel="alternate"/>
  </url>
  <url>
    <loc>https://my-site.com/docs/en/latest/about.html</loc>
    <xhtml:link href="https://my-site.com/docs/es/latest/about.html" hreflang="es" rel="alternate"/>
    <xhtml:link href="https://my-site.com/docs/fr/latest/about.html" hreflang="fr" rel="alternate"/>
    <xhtml:link href="https://my-site.com/docs/en/latest/index.html" hreflang="en" rel="alternate"/>
  </url>
</urlset>

See Who Is Using It

You can use GitHub search or libraries.io to see who is using sphinx-sitemap.

Contributing

Pull Requests welcome! See CONTRIBUTING for instructions on how best to contribute.

Maintaining PyPI Version

These are the steps, to be run by the maintainer, for making a new Python package release.

  1. Rev versions in sphinx_sitemap/version.py and setup.py.

  2. Update CHANGELOG.md

  3. Create a tag and push to GitHub:

    git tag -a vX.Y.Z -m "Release vX.Y.Z"
    git push --tags origin master
    
  4. Create latest distribution locally:

    python setup.py sdist
    
  5. Upload to the test pypi.org repository:

    twine upload --repository-url https://test.pypi.org/legacy/ dist/*
    
  6. Upload to the production pypi.org repository:

    twine upload dist/*
    

License

sphinx-sitemap is made available under a MIT license; see LICENSE for details.

Originally based on the sitemap generator in the guzzle_sphinx_theme project, also licensed under the MIT license.