Metadata-Version: 1.1
Name: sphinx-sitemap
Version: 2.2.0
Summary: Sitemap generator for Sphinx
Home-page: https://github.com/jdillard/sphinx-sitemap
Author: Jared Dillard
Author-email: jared.dillard@gmail.com
License: MIT
Download-URL: https://github.com/jdillard/sphinx-sitemap/archive/v2.2.0.tar.gz
Description: Sphinx Sitemap Generator Extension
        ==================================
        
        A `Sphinx`_ extension to generate multiversion and multilanguage
        `sitemaps.org`_ compliant sitemaps for the HTML version of your Sphinx
        documentation.
        
        |Build Status| |PyPI version| |Downloads| |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']
        
        Base Configuration
        ^^^^^^^^^^^^^^^^^^
        
        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/'
        
        After the HTML build is done, **sphinx-sitemap** will output the location of the
        sitemap::
        
            sitemap.xml was generated for URL https://my-site.com/docs/ in /path/to/_build/sitemap.xml
        
        **Tip:** Make sure to confirm the accuracy of the sitemap after installs and
        upgrades.
        
        Changing the Filename
        ^^^^^^^^^^^^^^^^^^^^^
        
        Set `sitemap_filename` in **conf.py** to the desired filename, for example::
        
            sitemap_filename = "sitemap.xml"
        
        Versioning Configuration
        ^^^^^^^^^^^^^^^^^^^^^^^^
        
        For multiversion sitemaps, you have to generate a sitemap per version and then
        manually add their locations to a `sitemapindex`_ file.
        
        The extension will look at the `version`_ config value for the current version
        being built, so make sure that is set.
        
        **Note:** When using multiple versions, it is best practice to set the canonical
        URL in the theme layout of all versions to the latest version of that page::
        
            <link rel="canonical" href="https://my-site.com/docs/latest/index.html"/>
        
        Multilingual Configuration
        ^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        For multilingual sitemaps, you have to generate a sitemap per language/locale
        and then manually add their locations to a `sitemapindex`_ file.
        
        Primary language is `language`_ config value. Alternative languages are either
        manually set by ``sitemap_locales`` option or auto-detected by the extension from
        the `locale_dirs`_ config value, so make sure one of those is set.
        
        ``sitemap_locales`` configuration is handy you want to list in the sitemap only some
        locales. For instance, if a third-party extension adds locale_dirs to Sphinx for the
        languages which you don't support in your docs, or if you want to wait for locales
        to reach a certain translated percentage before making them public. For example, if
        primary language is `en`, and you have `es` and `fr` translations, the sitemap
        look like this::
        
            <?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/index.html</loc>
                  <xhtml:link href="https://my-site.com/docs/es/index.html" hreflang="es" rel="alternate"/>
                  <xhtml:link href="https://my-site.com/docs/fr/index.html" hreflang="fr" rel="alternate"/>
                  <xhtml:link href="https://my-site.com/docs/en/index.html" hreflang="en" rel="alternate"/>
                </url>
                <url>
                    <loc>https://my-site.com/docs/en/about.html</loc>
                    <xhtml:link href="https://my-site.com/docs/es/about.html" hreflang="es" rel="alternate"/>
                    <xhtml:link href="https://my-site.com/docs/fr/about.html" hreflang="fr" rel="alternate"/>
                    <xhtml:link href="https://my-site.com/docs/en/about.html" hreflang="en" rel="alternate"/>
                </url>
              </urlset>
        
        If you limit the sitemap locales::
        
            sitemap_locales = ['en', 'es']
        
        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/index.html</loc>
              <xhtml:link href="https://my-site.com/docs/es/index.html" hreflang="es" rel="alternate"/>
            </url>
            <url>
              <loc>https://my-site.com/docs/en/about.html</loc>
              <xhtml:link href="https://my-site.com/docs/es/about.html" hreflang="es" rel="alternate"/>
            </url>
          </urlset>
        
        If you set the special value of ``[None]``::
        
            sitemap_locales = [None]
        
        only primary language is generated::
        
          <?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/index.html</loc>
            </url>
            <url>
              <loc>https://my-site.com/docs/en/about.html</loc>
            </url>
          </urlset>
        
        Customizing the URL Scheme
        ^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        If you have both ``language`` and ``version`` set, the default URL format is
        ``{version}{lang}{link}``. To change the default behavior, set the value of
        ``sitemap_url_scheme`` in **conf.py** to the desired format. For example::
        
            sitemap_url_scheme = "{lang}{version}subdir/{link}"
        
        **Note:** The extension is currently opinionated, in that it automatically
        appends trailing slashes to both the ``language`` and ``version`` values. You
        can also omit values from the scheme for desired behavior.
        
        Getting the Most out of the Sitemap
        -----------------------------------
        
        #. Add a **robots.txt** file in the **source** directory which contains a link to
           the sitemap or sitemapindex. For example::
        
             User-agent: *
        
             Sitemap: https://my-site.com/docs/sitemap.xml
        
           Then, add **robots.txt** to the `html_extra_path`_ config value::
        
             html_extra_path = ['robots.txt']
        
        #. Submit the sitemap or sitemapindex to the appropriate search engine tools.
        
        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.
        
        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.
        
        .. _CONTRIBUTING: CONTRIBUTING.md
        .. _extensions: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-extensions
        .. _GitHub search: https://github.com/search?utf8=%E2%9C%93&q=sphinx-sitemap+extension%3Atxt&type=
        .. _guzzle_sphinx_theme: https://github.com/guzzle/guzzle_sphinx_theme
        .. _html_baseurl: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_baseurl
        .. _html_extra_path: http://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_extra_path
        .. _language: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language
        .. _libraries.io: https://libraries.io/pypi/sphinx-sitemap
        .. _LICENSE: LICENSE
        .. _locale_dirs: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-locale_dirs
        .. _sitemapindex: https://support.google.com/webmasters/answer/75712?hl=en
        .. _sitemaps.org: https://www.sitemaps.org/protocol.html
        .. _Sphinx: http://sphinx-doc.org/
        .. _version: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-version
        
        .. |Build Status| image:: https://travis-ci.org/jdillard/sphinx-sitemap.svg?branch=master
           :target: https://travis-ci.org/jdillard/sphinx-sitemap
        .. |PyPI version| image:: https://img.shields.io/pypi/v/sphinx-sitemap.svg
           :target: https://pypi.python.org/pypi/sphinx-sitemap
        .. |Downloads| image:: https://pepy.tech/badge/sphinx-sitemap/week
            :target: https://pepy.tech/project/sphinx-sitemap
        .. |License: MIT| image:: https://img.shields.io/badge/License-MIT-blue.svg
           :target: https://github.com/jdillard/sphinx-sitemap/blob/master/LICENSE
        
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Documentation
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
