forked from ryan-roemer/sphinx-bootstrap-theme
-
Notifications
You must be signed in to change notification settings - Fork 0
Sphinx Bootstrap Theme
License
php-tool/sphinx-bootstrap-theme
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
<!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>Sphinx Bootstrap Theme — Demo 0.5.3 documentation</title> <link rel="stylesheet" href="_static/bootstrap-sphinx.css" type="text/css" /> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT: './', VERSION: '0.5.3', COLLAPSE_INDEX: false, FILE_SUFFIX: '.html', HAS_SOURCE: true, SOURCELINK_SUFFIX: '.txt' }; </script> <script type="text/javascript" src="_static/jquery.js"></script> <script type="text/javascript" src="_static/underscore.js"></script> <script type="text/javascript" src="_static/doctools.js"></script> <script type="text/javascript" src="_static/js/jquery-1.11.0.min.js"></script> <script type="text/javascript" src="_static/js/jquery-fix.js"></script> <script type="text/javascript" src="_static/bootstrap-3.3.6/js/bootstrap.min.js"></script> <script type="text/javascript" src="_static/bootstrap-sphinx.js"></script> <link rel="index" title="Index" href="genindex.html" /> <link rel="search" title="Search" href="search.html" /> <link rel="next" title="Examples" href="examples.html" /> <link rel="prev" title="Bootstrap Theme Demo" href="index.html" /> <meta charset='utf-8'> <meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'> <meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'> <meta name="apple-mobile-web-app-capable" content="yes"> </head> <body> <a href="https://github.com/ryan-roemer/sphinx-bootstrap-theme" class="visible-desktop hidden-xs"><img id="gh-banner" style="position: absolute; top: 50px; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_white_ffffff.png" alt="Fork me on GitHub"></a> <script> // Adjust banner height. $(function () { var navHeight = $(".navbar .container").css("height"); $("#gh-banner").css("top", navHeight); }); </script> <div id="navbar" class="navbar navbar-default navbar-fixed-top"> <div class="container"> <div class="navbar-header"> <!-- .btn-navbar is used as the toggle for collapsed navbar content --> <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse"> <span class="icon-bar"></span> <span class="icon-bar"></span> <span class="icon-bar"></span> </button> <a class="navbar-brand" href="index.html"> Demo</a> <span class="navbar-text navbar-version pull-left"><b>0.5.3</b></span> </div> <div class="collapse navbar-collapse nav-collapse"> <ul class="nav navbar-nav"> <li class="dropdown globaltoc-container"> <a role="button" id="dLabelGlobalToc" data-toggle="dropdown" data-target="#" href="index.html">Site <b class="caret"></b></a> <ul class="dropdown-menu globaltoc" role="menu" aria-labelledby="dLabelGlobalToc"><ul class="current"> <li class="toctree-l1 current"><a class="current reference internal" href="#">Sphinx Bootstrap Theme</a><ul> <li class="toctree-l2"><a class="reference internal" href="#introduction-and-demos">Introduction and Demos</a></li> <li class="toctree-l2"><a class="reference internal" href="#installation">Installation</a></li> <li class="toctree-l2"><a class="reference internal" href="#customization">Customization</a></li> <li class="toctree-l2"><a class="reference internal" href="#theme-notes">Theme Notes</a></li> <li class="toctree-l2"><a class="reference internal" href="#contributing">Contributing</a></li> <li class="toctree-l2"><a class="reference internal" href="#licenses">Licenses</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="examples.html">Examples</a><ul> <li class="toctree-l2"><a class="reference internal" href="examples.html#headings">Headings</a></li> <li class="toctree-l2"><a class="reference internal" href="examples.html#code">Code</a></li> <li class="toctree-l2"><a class="reference internal" href="examples.html#admonitions">Admonitions</a></li> <li class="toctree-l2"><a class="reference internal" href="examples.html#footnotes">Footnotes</a></li> <li class="toctree-l2"><a class="reference internal" href="examples.html#icons">Icons</a></li> <li class="toctree-l2"><a class="reference internal" href="examples.html#tables">Tables</a></li> <li class="toctree-l2"><a class="reference internal" href="examples.html#code-documentation">Code Documentation</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="sidebar.html">Sidebar Examples</a><ul> <li class="toctree-l2"><a class="reference internal" href="sidebar.html#headings">Headings</a></li> <li class="toctree-l2"><a class="reference internal" href="sidebar.html#let-s-rock-some-lorem">Let’s Rock Some Lorem!</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="subdir/index.html">Subdirectory Page</a><ul> <li class="toctree-l2"><a class="reference internal" href="subdir/index.html#headings">Headings</a></li> </ul> </li> </ul> <ul> <li class="toctree-l1"><a class="reference internal" href="HISTORY.html">History</a><ul> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-5-3">v0.5.3</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-5-2">v0.5.2</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-5-1">v0.5.1</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-5-0">v0.5.0</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-4-14">v0.4.14</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-4-13">v0.4.13</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-4-12">v0.4.12</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-4-11">v0.4.11</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-4-10">v0.4.10</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-4-9">v0.4.9</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-4-8">v0.4.8</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-4-7">v0.4.7</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-4-6">v0.4.6</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-4-5">v0.4.5</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-4-4">v0.4.4</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-4-3">v0.4.3</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-4-2">v0.4.2</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-4-1">v0.4.1</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-4-0">v0.4.0</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-3-9">v0.3.9</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-3-8">v0.3.8</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-3-7">v0.3.7</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-3-6">v0.3.6</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-3-5">v0.3.5</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-3-4">v0.3.4</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-3-3">v0.3.3</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-3-2">v0.3.2</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-3-1">v0.3.1</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-3-0">v0.3.0</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-2-9">v0.2.9</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-2-8">v0.2.8</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-2-7">v0.2.7</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-2-6">v0.2.6</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-2-5">v0.2.5</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-2-4">v0.2.4</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-2-3">v0.2.3</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-2-2">v0.2.2</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-2-1">v0.2.1</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-2-0">v0.2.0</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-1-8">v0.1.8</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-1-7">v0.1.7</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-1-4">v0.1.4</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-1-3">v0.1.3</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-1-2">v0.1.2</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-1-1">v0.1.1</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-1-0">v0.1.0</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-0-6">v0.0.6</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-0-4">v0.0.4</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-0-3">v0.0.3</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-0-2">v0.0.2</a></li> <li class="toctree-l2"><a class="reference internal" href="HISTORY.html#v0-0-1">v0.0.1</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="TODO.html">Future Work</a><ul> <li class="toctree-l2"><a class="reference internal" href="TODO.html#css-layout">CSS / Layout</a></li> <li class="toctree-l2"><a class="reference internal" href="TODO.html#infrastructure">Infrastructure</a></li> <li class="toctree-l2"><a class="reference internal" href="TODO.html#upgrade-notes">Upgrade Notes</a></li> </ul> </li> </ul> </ul> </li> <li class="dropdown"> <a role="button" id="dLabelLocalToc" data-toggle="dropdown" data-target="#" href="#">Page <b class="caret"></b></a> <ul class="dropdown-menu localtoc" role="menu" aria-labelledby="dLabelLocalToc"><ul> <li><a class="reference internal" href="#">Sphinx Bootstrap Theme</a><ul> <li><a class="reference internal" href="#introduction-and-demos">Introduction and Demos</a></li> <li><a class="reference internal" href="#installation">Installation</a></li> <li><a class="reference internal" href="#customization">Customization</a><ul> <li><a class="reference internal" href="#theme-options">Theme Options</a></li> <li><a class="reference internal" href="#bootstrap-versions">Bootstrap Versions</a></li> <li><a class="reference internal" href="#extending-layout-html">Extending “layout.html”</a></li> <li><a class="reference internal" href="#adding-custom-css">Adding Custom CSS</a></li> </ul> </li> <li><a class="reference internal" href="#theme-notes">Theme Notes</a><ul> <li><a class="reference internal" href="#id2">Sphinx</a></li> <li><a class="reference internal" href="#id3">Bootstrap</a></li> </ul> </li> <li><a class="reference internal" href="#contributing">Contributing</a></li> <li><a class="reference internal" href="#licenses">Licenses</a></li> </ul> </li> </ul> </ul> </li> <li> <a href="index.html" title="Previous Chapter: Bootstrap Theme Demo"><span class="glyphicon glyphicon-chevron-left visible-sm"></span><span class="hidden-sm hidden-tablet">« Bootstrap The...</span> </a> </li> <li> <a href="examples.html" title="Next Chapter: Examples"><span class="glyphicon glyphicon-chevron-right visible-sm"></span><span class="hidden-sm hidden-tablet">Examples »</span> </a> </li> <li class="hidden-sm"> <div id="sourcelink"> <a href="_sources/README.rst.txt" rel="nofollow">Source</a> </div></li> </ul> <form class="navbar-form navbar-right" action="search.html" method="get"> <div class="form-group"> <input type="text" name="q" class="form-control" placeholder="Search" /> </div> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> </div> </div> <div class="container"> <div class="row"> <div class="col-md-12 content"> <div class="section" id="sphinx-bootstrap-theme"> <h1>Sphinx Bootstrap Theme<a class="headerlink" href="#sphinx-bootstrap-theme" title="Permalink to this headline">¶</a></h1> <p>This <a class="reference external" href="http://sphinx-doc.org/">Sphinx</a> <a class="reference external" href="http://sphinx-doc.org/theming.html">theme</a> integrates the <a class="reference external" href="http://getbootstrap.com/">Bootstrap</a> CSS / JavaScript framework with various layout options, hierarchical menu navigation, and mobile-friendly responsive design. It is configurable, extensible, and can use any number of different <a class="reference external" href="http://bootswatch.com">Bootswatch</a> CSS themes.</p> <div class="section" id="introduction-and-demos"> <h2>Introduction and Demos<a class="headerlink" href="#introduction-and-demos" title="Permalink to this headline">¶</a></h2> <p>The theme is introduced and discussed in the following posts:</p> <ul class="simple"> <li>12/09/2011 - <a class="reference external" href="http://loose-bits.com/2011/12/09/sphinx-twitter-bootstrap-theme.html">Twitter Bootstrap Theme for Sphinx</a></li> <li>11/19/2012 - <a class="reference external" href="http://loose-bits.com/2012/11/19/sphinx-bootstrap-theme-updates.html">Sphinx Bootstrap Theme Updates - Mobile, Dropdowns, and More</a></li> <li>2/12/2013 - <a class="reference external" href="http://loose-bits.com/2013/02/12/sphinx-bootstrap-theme-updates.html">Sphinx Bootstrap Theme 0.1.6 - Bootstrap and Other Updates</a></li> <li>4/10/2013 - <a class="reference external" href="http://loose-bits.com/2013/04/10/sphinx-bootstrap-theme-bootswatch.html">Sphinx Bootstrap Theme 0.2.0 - Now with Bootswatch!</a></li> <li>9/8/2013 - <a class="reference external" href="http://loose-bits.com/2013/09/08/sphinx-bootstrap-theme-bootstrap-3.html">Sphinx Bootstrap Theme 0.3.0 - Bootstrap v3 and more!</a></li> </ul> <p>Examples of the theme in use for some public projects:</p> <ul class="simple"> <li><a class="reference external" href="http://ryan-roemer.github.com/sphinx-bootstrap-theme">Sphinx Bootstrap Theme</a>: This project, with the theme option <code class="docutils literal"><span class="pre">'bootswatch_theme':</span> <span class="pre">"sandstone"</span></code> to use the “<a class="reference external" href="http://bootswatch.com/sandstone">Sandstone</a>” <a class="reference external" href="http://bootswatch.com">Bootswatch</a> theme.</li> <li><a class="reference external" href="http://ryan-roemer.github.com/django-cloud-browser">Django Cloud Browser</a>: A Django reusable app for browsing cloud datastores (e.g., Amazon Web Services S3).</li> <li><a class="reference external" href="http://cppformat.readthedocs.org">C++ Format</a>: Small, safe and fast formatting library for C++.</li> </ul> <p>The theme demo website also includes an <a class="reference external" href="http://ryan-roemer.github.com/sphinx-bootstrap-theme/examples.html">examples page</a> for some useful illustrations of getting Sphinx to play nicely with Bootstrap (also take a look at the <a class="reference external" href="http://ryan-roemer.github.com/sphinx-bootstrap-theme/_sources/examples.txt">examples source</a> for the underlying reStructuredText).</p> </div> <div class="section" id="installation"> <h2>Installation<a class="headerlink" href="#installation" title="Permalink to this headline">¶</a></h2> <p>Installation from <a class="reference external" href="http://pypi.python.org/pypi/sphinx-bootstrap-theme/">PyPI</a> is fairly straightforward:</p> <ol class="arabic"> <li><p class="first">Install the package:</p> <div class="highlight-default"><div class="highlight"><pre><span></span>$ pip install sphinx_bootstrap_theme </pre></div> </div> </li> <li><p class="first">Edit the “conf.py” configuration file to point to the bootstrap theme:</p> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># At the top.</span> <span class="kn">import</span> <span class="nn">sphinx_bootstrap_theme</span> <span class="c1"># ...</span> <span class="c1"># Activate the theme.</span> <span class="n">html_theme</span> <span class="o">=</span> <span class="s1">'bootstrap'</span> <span class="n">html_theme_path</span> <span class="o">=</span> <span class="n">sphinx_bootstrap_theme</span><span class="o">.</span><span class="n">get_html_theme_path</span><span class="p">()</span> </pre></div> </div> </li> </ol> </div> <div class="section" id="customization"> <h2>Customization<a class="headerlink" href="#customization" title="Permalink to this headline">¶</a></h2> <p>The can be customized in varying ways (some a little more work than others).</p> <div class="section" id="theme-options"> <h3>Theme Options<a class="headerlink" href="#theme-options" title="Permalink to this headline">¶</a></h3> <p>The theme provides many built-in options that can be configured by editing your “conf.py” file:</p> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># (Optional) Logo. Should be small enough to fit the navbar (ideally 24x24).</span> <span class="c1"># Path should be relative to the ``_static`` files directory.</span> <span class="n">html_logo</span> <span class="o">=</span> <span class="s2">"my_logo.png"</span> <span class="c1"># Theme options are theme-specific and customize the look and feel of a</span> <span class="c1"># theme further.</span> <span class="n">html_theme_options</span> <span class="o">=</span> <span class="p">{</span> <span class="c1"># Navigation bar title. (Default: ``project`` value)</span> <span class="s1">'navbar_title'</span><span class="p">:</span> <span class="s2">"Demo"</span><span class="p">,</span> <span class="c1"># Tab name for entire site. (Default: "Site")</span> <span class="s1">'navbar_site_name'</span><span class="p">:</span> <span class="s2">"Site"</span><span class="p">,</span> <span class="c1"># A list of tuples containing pages or urls to link to.</span> <span class="c1"># Valid tuples should be in the following forms:</span> <span class="c1"># (name, page) # a link to a page</span> <span class="c1"># (name, "/aa/bb", 1) # a link to an arbitrary relative url</span> <span class="c1"># (name, "http://example.com", True) # arbitrary absolute url</span> <span class="c1"># Note the "1" or "True" value above as the third argument to indicate</span> <span class="c1"># an arbitrary url.</span> <span class="s1">'navbar_links'</span><span class="p">:</span> <span class="p">[</span> <span class="p">(</span><span class="s2">"Examples"</span><span class="p">,</span> <span class="s2">"examples"</span><span class="p">),</span> <span class="p">(</span><span class="s2">"Link"</span><span class="p">,</span> <span class="s2">"http://example.com"</span><span class="p">,</span> <span class="kc">True</span><span class="p">),</span> <span class="p">],</span> <span class="c1"># Render the next and previous page links in navbar. (Default: true)</span> <span class="s1">'navbar_sidebarrel'</span><span class="p">:</span> <span class="kc">True</span><span class="p">,</span> <span class="c1"># Render the current pages TOC in the navbar. (Default: true)</span> <span class="s1">'navbar_pagenav'</span><span class="p">:</span> <span class="kc">True</span><span class="p">,</span> <span class="c1"># Tab name for the current pages TOC. (Default: "Page")</span> <span class="s1">'navbar_pagenav_name'</span><span class="p">:</span> <span class="s2">"Page"</span><span class="p">,</span> <span class="c1"># Global TOC depth for "site" navbar tab. (Default: 1)</span> <span class="c1"># Switching to -1 shows all levels.</span> <span class="s1">'globaltoc_depth'</span><span class="p">:</span> <span class="mi">2</span><span class="p">,</span> <span class="c1"># Include hidden TOCs in Site navbar?</span> <span class="c1">#</span> <span class="c1"># Note: If this is "false", you cannot have mixed ``:hidden:`` and</span> <span class="c1"># non-hidden ``toctree`` directives in the same page, or else the build</span> <span class="c1"># will break.</span> <span class="c1">#</span> <span class="c1"># Values: "true" (default) or "false"</span> <span class="s1">'globaltoc_includehidden'</span><span class="p">:</span> <span class="s2">"true"</span><span class="p">,</span> <span class="c1"># HTML navbar class (Default: "navbar") to attach to <div> element.</span> <span class="c1"># For black navbar, do "navbar navbar-inverse"</span> <span class="s1">'navbar_class'</span><span class="p">:</span> <span class="s2">"navbar navbar-inverse"</span><span class="p">,</span> <span class="c1"># Fix navigation bar to top of page?</span> <span class="c1"># Values: "true" (default) or "false"</span> <span class="s1">'navbar_fixed_top'</span><span class="p">:</span> <span class="s2">"true"</span><span class="p">,</span> <span class="c1"># Location of link to source.</span> <span class="c1"># Options are "nav" (default), "footer" or anything else to exclude.</span> <span class="s1">'source_link_position'</span><span class="p">:</span> <span class="s2">"nav"</span><span class="p">,</span> <span class="c1"># Bootswatch (http://bootswatch.com/) theme.</span> <span class="c1">#</span> <span class="c1"># Options are nothing (default) or the name of a valid theme</span> <span class="c1"># such as "amelia" or "cosmo".</span> <span class="s1">'bootswatch_theme'</span><span class="p">:</span> <span class="s2">"united"</span><span class="p">,</span> <span class="c1"># Choose Bootstrap version.</span> <span class="c1"># Values: "3" (default) or "2" (in quotes)</span> <span class="s1">'bootstrap_version'</span><span class="p">:</span> <span class="s2">"3"</span><span class="p">,</span> <span class="p">}</span> </pre></div> </div> <p>Note for the navigation bar title that if you don’t specify a theme option of <code class="docutils literal"><span class="pre">navbar_title</span></code> that the “conf.py” <code class="docutils literal"><span class="pre">project</span></code> string will be used. We don’t use the <code class="docutils literal"><span class="pre">html_title</span></code> or <code class="docutils literal"><span class="pre">html_short_title</span></code> values because by default those both contain version strings, which the navigation bar treats differently.</p> </div> <div class="section" id="bootstrap-versions"> <h3>Bootstrap Versions<a class="headerlink" href="#bootstrap-versions" title="Permalink to this headline">¶</a></h3> <p>The theme supports Bootstrap <code class="docutils literal"><span class="pre">v2.3.2</span></code> and <code class="docutils literal"><span class="pre">v3.3.4</span></code> via the <code class="docutils literal"><span class="pre">bootstrap_version</span></code> theme option (of <code class="docutils literal"><span class="pre">"2"</span></code> or <code class="docutils literal"><span class="pre">"3"</span></code>). Some notes regarding version differences:</p> <ul class="simple"> <li>Bootstrap 3 has dropped support for <a class="reference external" href="http://stackoverflow.com/questions/18023493">sub-menus</a>, so while supported by this theme, they will not show up in site or page menus.</li> <li>Internally, “navbar.html” is the Sphinx template used for Bootstrap v3 and “navbar-2.html” is the template used for v2.</li> </ul> </div> <div class="section" id="extending-layout-html"> <h3>Extending “layout.html”<a class="headerlink" href="#extending-layout-html" title="Permalink to this headline">¶</a></h3> <p>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 <code class="docutils literal"><span class="pre">navbarextra</span></code> template block for additional content in the navbar.</p> <p>Then, create your own “_templates” directory and “layout.html” file (assuming you build from a “source” directory):</p> <div class="highlight-default"><div class="highlight"><pre><span></span>$ mkdir source/_templates $ touch source/_templates/layout.html </pre></div> </div> <p>Then, configure your “conf.py”:</p> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">templates_path</span> <span class="o">=</span> <span class="p">[</span><span class="s1">'_templates'</span><span class="p">]</span> </pre></div> </div> <p>Finally, edit your override file “source/_templates/layout.html”:</p> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">{</span><span class="c1"># Import the theme's layout. #}</span> <span class="p">{</span><span class="o">%</span> <span class="n">extends</span> <span class="s2">"!layout.html"</span> <span class="o">%</span><span class="p">}</span> <span class="p">{</span><span class="c1"># Add some extra stuff before and use existing with 'super()' call. #}</span> <span class="p">{</span><span class="o">%</span> <span class="n">block</span> <span class="n">footer</span> <span class="o">%</span><span class="p">}</span> <span class="o"><</span><span class="n">h2</span><span class="o">></span><span class="n">My</span> <span class="n">footer</span> <span class="n">of</span> <span class="n">awesomeness</span><span class="o">.</</span><span class="n">h2</span><span class="o">></span> <span class="p">{{</span> <span class="nb">super</span><span class="p">()</span> <span class="p">}}</span> <span class="p">{</span><span class="o">%</span> <span class="n">endblock</span> <span class="o">%</span><span class="p">}</span> </pre></div> </div> </div> <div class="section" id="adding-custom-css"> <h3>Adding Custom CSS<a class="headerlink" href="#adding-custom-css" title="Permalink to this headline">¶</a></h3> <p>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:</p> <div class="highlight-default"><div class="highlight"><pre><span></span>$ mkdir source/_static $ touch source/_static/my-styles.css </pre></div> </div> <p>In the new file “source/_static/my-styles.css”, add any appropriate styling, e.g. a bold background color:</p> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">footer</span> <span class="p">{</span> <span class="n">background</span><span class="o">-</span><span class="n">color</span><span class="p">:</span> <span class="n">red</span><span class="p">;</span> <span class="p">}</span> </pre></div> </div> <p>Then, in “conf.py”, edit this line:</p> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">html_static_path</span> <span class="o">=</span> <span class="p">[</span><span class="s2">"_static"</span><span class="p">]</span> </pre></div> </div> <p>From there it depends on which version of Sphinx you are using:</p> <p><strong>Sphinx <= 1.5</strong></p> <p>You will need the override template “source/_templates/layout.html” file configured as above, but with the following code:</p> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">{</span><span class="c1"># Import the theme's layout. #}</span> <span class="p">{</span><span class="o">%</span> <span class="n">extends</span> <span class="s2">"!layout.html"</span> <span class="o">%</span><span class="p">}</span> <span class="p">{</span><span class="c1"># Custom CSS overrides #}</span> <span class="p">{</span><span class="o">%</span> <span class="nb">set</span> <span class="n">css_files</span> <span class="o">=</span> <span class="n">css_files</span> <span class="o">+</span> <span class="p">[</span><span class="s1">'_static/my-styles.css'</span><span class="p">]</span> <span class="o">%</span><span class="p">}</span> </pre></div> </div> <p><strong>Sphinx >= 1.6</strong></p> <p>Add a <cite>setup</cite> function in “conf.py” with stylesheet paths added relative to the static path:</p> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">setup</span><span class="p">(</span><span class="n">app</span><span class="p">):</span> <span class="n">app</span><span class="o">.</span><span class="n">add_stylesheet</span><span class="p">(</span><span class="s2">"my-styles.css"</span><span class="p">)</span> <span class="c1"># also can be a full URL</span> <span class="c1"># app.add_stylesheet("ANOTHER.css")</span> <span class="c1"># app.add_stylesheet("AND_ANOTHER.css")</span> </pre></div> </div> </div> </div> <div class="section" id="theme-notes"> <h2>Theme Notes<a class="headerlink" href="#theme-notes" title="Permalink to this headline">¶</a></h2> <div class="section" id="id2"> <h3>Sphinx<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h3> <p>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.</p> <p>The global (site-wide) table of contents is the “Site” navigation dropdown, which is a configurable level rendering of the <code class="docutils literal"><span class="pre">toctree</span></code> 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 <code class="docutils literal"><span class="pre">toc</span></code>.</p> </div> <div class="section" id="id3"> <h3>Bootstrap<a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h3> <p>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 <code class="docutils literal"><span class="pre">noConflict()</span></code> as <code class="docutils literal"><span class="pre">$jqTheme</span></code>.</p> <p>You can override any static JS/CSS files by dropping different versions in your Sphinx “_static” directory.</p> </div> </div> <div class="section" id="contributing"> <h2>Contributing<a class="headerlink" href="#contributing" title="Permalink to this headline">¶</a></h2> <p>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:</p> <div class="highlight-default"><div class="highlight"><pre><span></span>$ fab clean && fab demo </pre></div> </div> <p>Then, view the site in the development server:</p> <div class="highlight-default"><div class="highlight"><pre><span></span>$ fab demo_server </pre></div> </div> <p>Also, if you are adding a new type of styling or Sphinx or Bootstrap construct, please add a usage example to the “Examples” page.</p> <p><strong>Note</strong>: If you are in Python 3, Fabric isn’t available, so we have a very rough Makefile in its place. Try:</p> <div class="highlight-default"><div class="highlight"><pre><span></span>$ make clean && make demo </pre></div> </div> <p>Then, view the site in the development server:</p> <div class="highlight-default"><div class="highlight"><pre><span></span>$ make demo_server </pre></div> </div> </div> <div class="section" id="licenses"> <h2>Licenses<a class="headerlink" href="#licenses" title="Permalink to this headline">¶</a></h2> <p>Sphinx Bootstrap Theme is licensed under the <a class="reference external" href="https://github.com/ryan-roemer/sphinx-bootstrap-theme/blob/master/LICENSE.txt">MIT</a> license.</p> <p><a class="reference external" href="https://github.com/twbs/bootstrap/blob/v2.3.2/LICENSE">Bootstrap v2</a> is licensed under the Apache license 2.0.</p> <p><a class="reference external" href="https://github.com/twbs/bootstrap/blob/master/LICENSE">Bootstrap v3.1.0+</a> is licensed under the MIT license.</p> </div> </div> </div> </div> </div> <footer class="footer"> <div class="container"> <p class="pull-right"> <a href="#">Back to top</a> </p> <p> © Copyright 2011-2016, Ryan Roemer.<br/> Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.6.1.<br/> </p> </div> </footer> </body> </html>
About
Sphinx Bootstrap Theme
Resources
License
Stars
Watchers
Forks
Packages 0
No packages published
Languages
- HTML 81.5%
- Python 14.0%
- JavaScript 2.8%
- Makefile 1.7%