Metadata-Version: 1.1
Name: kentigern
Version: 0.1.4
Summary: A Sphinx Bootstrap derived Theme.
Home-page: https://code.daniel-williams.co.uk/kentigern
Author: Daniel Williams
Author-email: mail@daniel-williams.co.uk
License: UNKNOWN
Description: =========
        Kentigern
        =========
        
        This Sphinx_ theme_ integrates the Bootstrap_ CSS / JavaScript
        framework with various layout options, hierarchical menu navigation,
        and mobile-friendly responsive design.
        
        .. _Bootstrap: http://getbootstrap.com/
        .. _Sphinx: http://sphinx-doc.org/
        .. _theme: http://sphinx-doc.org/theming.html
        .. _PyPI: http://pypi.python.org/pypi/sphinx-bootstrap-theme/
        .. _GitHub repository: https://github.com/ryan-roemer/sphinx-bootstrap-theme
        
        
        Installation
        ============
        Installation from PyPI_ is fairly straightforward:
        
        1. Install the package::
        
              $ pip install kentigern
        
        2. Edit the "conf.py" configuration file to point to the bootstrap theme::
        
              # At the top.
              import kentigern
        
              # ...
        
              # Activate the theme.
              html_theme = 'kentigern'
              html_theme_path = kentigern.get_html_theme_path()
        
        
        Customization
        =============
        The theme can be customized in varying ways (some a little more work than others).
        
        Theme Options
        -------------
        The theme provides many built-in options that can be configured by editing
        your "conf.py" file::
        
            # (Optional) Logo. Should be small enough to fit the navbar (ideally 24x24).
            # Path should be relative to the ``_static`` files directory.
            html_logo = "my_logo.png"
        
            # Theme options are theme-specific and customize the look and feel of a
            # theme further.
            html_theme_options = {
                # Navigation bar title. (Default: ``project`` value)
                'navbar_title': "Demo",
        
                # Tab name for entire site. (Default: "Site")
                'navbar_site_name': "Site",
        
                # A list of tuples containing pages or urls to link to.
                # Valid tuples should be in the following forms:
                #    (name, page)                 # a link to a page
                #    (name, "/aa/bb", 1)          # a link to an arbitrary relative url
                #    (name, "http://example.com", True) # arbitrary absolute url
                # Note the "1" or "True" value above as the third argument to indicate
                # an arbitrary url.
                'navbar_links': [
                    ("Examples", "examples"),
                    ("Link", "http://example.com", True),
                ],
        
                # Render the next and previous page links in navbar. (Default: true)
                'navbar_sidebarrel': True,
        
                # Render the current pages TOC in the navbar. (Default: true)
                'navbar_pagenav': True,
        
                # Tab name for the current pages TOC. (Default: "Page")
                'navbar_pagenav_name': "Page",
        
                # Global TOC depth for "site" navbar tab. (Default: 1)
                # Switching to -1 shows all levels.
                'globaltoc_depth': 2,
        
                # Include hidden TOCs in Site navbar?
                #
                # Note: If this is "false", you cannot have mixed ``:hidden:`` and
                # non-hidden ``toctree`` directives in the same page, or else the build
                # will break.
                #
                # Values: "true" (default) or "false"
                'globaltoc_includehidden': "true",
        
                # HTML navbar class (Default: "navbar") to attach to <div> element.
                # For black navbar, do "navbar navbar-inverse"
                'navbar_class': "navbar navbar-inverse",
        
                # Fix navigation bar to top of page?
                # Values: "true" (default) or "false"
                'navbar_fixed_top': "true",
        
                # Location of link to source.
                # Options are "nav" (default), "footer" or anything else to exclude.
                'source_link_position': "nav",
            }
        
        Note for the navigation bar title that if you don't specify a theme option of
        ``navbar_title`` that the "conf.py" ``project`` string will be used. We don't
        use the ``html_title`` or ``html_short_title`` values because by default those
        both contain version strings, which the navigation bar treats differently.
        
        
        Extending "layout.html"
        -----------------------
        As a more "hands on" approach to customization, you can override any template
        in this Sphinx theme or any others. A good candidate for changes is
        "layout.html", which provides most of the look and feel. First, take a look
        at the "layout.html" file that the theme provides, and figure out
        what you need to override. As a side note, we have some theme-specific
        enhancements, such as the ``navbarextra`` template block for additional
        content in the navbar.
        
        Then, create your own "_templates" directory and "layout.html" file (assuming
        you build from a "source" directory)::
        
            $ mkdir source/_templates
            $ touch source/_templates/layout.html
        
        Then, configure your "conf.py"::
        
            templates_path = ['_templates']
        
        Finally, edit your override file "source/_templates/layout.html"::
        
            {# Import the theme's layout. #}
            {% extends "!layout.html" %}
        
            {# Add some extra stuff before and use existing with 'super()' call. #}
            {% block footer %}
              <h2>My footer of awesomeness.</h2>
              {{ super() }}
            {% endblock %}
        
        
        Adding Custom CSS
        -----------------
        Alternately, you could add your own custom static media directory with a CSS
        file to override a style, which in the demo would be something like::
        
            $ mkdir source/_static
            $ touch source/_static/my-styles.css
        
        In the new file "source/_static/my-styles.css", add any appropriate styling,
        e.g. a bold background color::
        
            footer {
              background-color: red;
            }
        
        Then, in "conf.py", edit this line::
        
            html_static_path = ["_static"]
        
        From there it depends on which version of Sphinx you are using:
        
        **Sphinx <= 1.5**
        
        You will need the override template "source/_templates/layout.html" file
        configured as above, but with the following code::
        
            {# Import the theme's layout. #}
            {% extends "!layout.html" %}
        
            {# Custom CSS overrides #}
            {% set css_files = css_files + ['_static/my-styles.css'] %}
        
        .. note::
        
           See `Issue #159 <https://github.com/ryan-roemer/sphinx-bootstrap-theme/pull/159>`_
           for more information.
        
        **Sphinx >= 1.6.1**
        
        Add a ``setup`` function in "conf.py" with stylesheet paths added relative to the
        static path::
        
            def setup(app):
                app.add_stylesheet("my-styles.css") # also can be a full URL
                # app.add_stylesheet("ANOTHER.css")
                # app.add_stylesheet("AND_ANOTHER.css")
        
        .. tip::
        
           Sphinx automatically calls your ``setup`` function defined in "conf.py" during
           the build process for you.  There is no need to, nor should you, call this
           function directly in your code.
        
        Theme Notes
        ===========
        Sphinx
        ------
        The theme places the global TOC, local TOC, navigation (prev, next) and
        source links all in the top Bootstrap navigation bar, along with the Sphinx
        search bar on the left side.
        
        The global (site-wide) table of contents is the "Site" navigation dropdown,
        which is a configurable level rendering of the ``toctree`` for the entire site.
        The local (page-level) table of contents is the "Page" navigation dropdown,
        which is a multi-level rendering of the current page's ``toc``.
        
        
        Bootstrap
        ---------
        The theme offers Bootstrap v2.x and v3.x, both of which rely on
        jQuery v.1.9.x. As the jQuery that Bootstrap wants can radically depart from
        the jQuery Sphinx internal libraries use, the library from this theme is
        integrated via ``noConflict()`` as ``$jqTheme``.
        
        You can override any static JS/CSS files by dropping different versions in your
        Sphinx "_static" directory.
        
        
        Contributing
        ============
        Contributions to this project are most welcome. Please make sure that the demo
        site builds cleanly, and looks like what you want. First build the demo::
        
            $ fab clean && fab demo
        
        Then, view the site in the development server::
        
            $ fab demo_server
        
        Also, if you are adding a new type of styling or Sphinx or Bootstrap construct,
        please add a usage example to the "Examples" page.
        
        **Note**: If you are in Python 3, Fabric isn't available, so we have a very
        rough Makefile in its place. Try::
        
            $ make clean && make demo
        
        Then, view the site in the development server::
        
            $ make demo_server
        
        
        Licenses
        ========
        Sphinx Bootstrap Theme is licensed under the MIT_ license.
        
        `Bootstrap v2`_ is licensed under the Apache license 2.0.
        
        `Bootstrap v3.1.0+`_ is licensed under the MIT license.
        
        .. _`MIT`: https://github.com/ryan-roemer/sphinx-bootstrap-theme/blob/master/LICENSE.txt
        .. _`Bootstrap v2`: https://github.com/twbs/bootstrap/blob/v2.3.2/LICENSE
        .. _`Bootstrap v3.1.0+`: https://github.com/twbs/bootstrap/blob/master/LICENSE
        
        
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Documentation
