{"author":"Ryan Roemer","author_email":"ryan@loose-bits.com","bugtrack_url":null,"classifiers":["Development Status :: 5 - Production/Stable","Environment :: Web Environment","Intended Audience :: Developers","Intended Audience :: System Administrators","License :: OSI Approved :: MIT License","Operating System :: OS Independent","Programming Language :: Python","Programming Language :: Python :: 2","Programming Language :: Python :: 3","Topic :: Internet","Topic :: Software Development :: Documentation"],"description":"========================\n Sphinx Bootstrap Theme\n========================\n\nThis Sphinx_ theme_ integrates the Bootstrap_ CSS / JavaScript\nframework with various layout options, hierarchical menu navigation,\nand mobile-friendly responsive design. It is configurable, extensible,\nand can use any number of different Bootswatch_ CSS themes.\n\n.. _Bootstrap: http://getbootstrap.com/\n.. _Sphinx: http://sphinx-doc.org/\n.. _theme: http://sphinx-doc.org/theming.html\n.. _PyPI: http://pypi.python.org/pypi/sphinx-bootstrap-theme/\n.. _GitHub repository: https://github.com/ryan-roemer/sphinx-bootstrap-theme\n\n\nIntroduction and Demos\n======================\nThe theme is introduced and discussed in the following posts:\n\n* 12/09/2011 - `Twitter Bootstrap Theme for Sphinx `_\n* 11/19/2012 - `Sphinx Bootstrap Theme Updates - Mobile, Dropdowns, and More `_\n* 2/12/2013 - `Sphinx Bootstrap Theme 0.1.6 - Bootstrap and Other Updates `_\n* 4/10/2013 - `Sphinx Bootstrap Theme 0.2.0 - Now with Bootswatch! `_\n* 9/8/2013 - `Sphinx Bootstrap Theme 0.3.0 - Bootstrap v3 and more! `_\n\nExamples of the theme in use for some public projects:\n\n* `Sphinx Bootstrap Theme`_: This project, with the theme option\n ``'bootswatch_theme': \"sandstone\"`` to use the \"Sandstone_\" Bootswatch_ theme.\n* `Django Cloud Browser`_: A Django reusable app for browsing cloud\n datastores (e.g., Amazon Web Services S3).\n* `seaborn`_: A statistical data visualization library.\n\nThe theme demo website also includes an `examples page`_ for some useful\nillustrations of getting Sphinx to play nicely with Bootstrap (also take a\nlook at the `examples source`_ for the underlying reStructuredText).\n\n.. _Bootswatch: http://bootswatch.com\n.. _United: http://bootswatch.com/united\n.. _Flatly: http://bootswatch.com/flatly\n.. _Sandstone: http://bootswatch.com/sandstone\n.. _Sphinx Bootstrap Theme: https://ryan-roemer.github.io/sphinx-bootstrap-theme\n.. _examples page: https://ryan-roemer.github.io/sphinx-bootstrap-theme/examples.html\n.. _examples source: https://ryan-roemer.github.io/sphinx-bootstrap-theme/_sources/examples.rst.txt\n.. _Django Cloud Browser: https://ryan-roemer.github.io/django-cloud-browser\n.. _seaborn: http://seaborn.pydata.org\n\n\nInstallation\n============\nInstallation from PyPI_ is fairly straightforward:\n\n1. Install the package::\n\n $ pip install sphinx_bootstrap_theme\n\n2. Edit the \"conf.py\" configuration file to point to the bootstrap theme::\n\n # At the top.\n import sphinx_bootstrap_theme\n\n # ...\n\n # Activate the theme.\n html_theme = 'bootstrap'\n html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()\n\n\nCustomization\n=============\nThe theme can be customized in varying ways (some a little more work than others).\n\nTheme Options\n-------------\nThe theme provides many built-in options that can be configured by editing\nyour \"conf.py\" file::\n\n # (Optional) Logo. Should be small enough to fit the navbar (ideally 24x24).\n # Path should be relative to the ``_static`` files directory.\n html_logo = \"my_logo.png\"\n\n # Theme options are theme-specific and customize the look and feel of a\n # theme further.\n html_theme_options = {\n # Navigation bar title. (Default: ``project`` value)\n 'navbar_title': \"Demo\",\n\n # Tab name for entire site. (Default: \"Site\")\n 'navbar_site_name': \"Site\",\n\n # A list of tuples containing pages or urls to link to.\n # Valid tuples should be in the following forms:\n # (name, page) # a link to a page\n # (name, \"/aa/bb\", 1) # a link to an arbitrary relative url\n # (name, \"http://example.com\", True) # arbitrary absolute url\n # Note the \"1\" or \"True\" value above as the third argument to indicate\n # an arbitrary url.\n 'navbar_links': [\n (\"Examples\", \"examples\"),\n (\"Link\", \"http://example.com\", True),\n ],\n\n # Render the next and previous page links in navbar. (Default: true)\n 'navbar_sidebarrel': True,\n\n # Render the current pages TOC in the navbar. (Default: true)\n 'navbar_pagenav': True,\n\n # Tab name for the current pages TOC. (Default: \"Page\")\n 'navbar_pagenav_name': \"Page\",\n\n # Global TOC depth for \"site\" navbar tab. (Default: 1)\n # Switching to -1 shows all levels.\n 'globaltoc_depth': 2,\n\n # Include hidden TOCs in Site navbar?\n #\n # Note: If this is \"false\", you cannot have mixed ``:hidden:`` and\n # non-hidden ``toctree`` directives in the same page, or else the build\n # will break.\n #\n # Values: \"true\" (default) or \"false\"\n 'globaltoc_includehidden': \"true\",\n\n # HTML navbar class (Default: \"navbar\") to attach to

element.\n # For black navbar, do \"navbar navbar-inverse\"\n 'navbar_class': \"navbar navbar-inverse\",\n\n # Fix navigation bar to top of page?\n # Values: \"true\" (default) or \"false\"\n 'navbar_fixed_top': \"true\",\n\n # Location of link to source.\n # Options are \"nav\" (default), \"footer\" or anything else to exclude.\n 'source_link_position': \"nav\",\n\n # Bootswatch (http://bootswatch.com/) theme.\n #\n # Options are nothing (default) or the name of a valid theme\n # such as \"cosmo\" or \"sandstone\".\n #\n # The set of valid themes depend on the version of Bootstrap\n # that's used (the next config option).\n #\n # Currently, the supported themes are:\n # - Bootstrap 2: https://bootswatch.com/2\n # - Bootstrap 3: https://bootswatch.com/3\n 'bootswatch_theme': \"united\",\n\n # Choose Bootstrap version.\n # Values: \"3\" (default) or \"2\" (in quotes)\n 'bootstrap_version': \"3\",\n }\n\nNote for the navigation bar title that if you don't specify a theme option of\n``navbar_title`` that the \"conf.py\" ``project`` string will be used. We don't\nuse the ``html_title`` or ``html_short_title`` values because by default those\nboth contain version strings, which the navigation bar treats differently.\n\nBootstrap Versions\n------------------\nThe theme supports Bootstrap ``v2.3.2`` and ``v3.3.7`` via the\n``bootstrap_version`` theme option (of ``\"2\"`` or ``\"3\"``). Some notes\nregarding version differences:\n\n* Bootstrap 3 has dropped support for `sub-menus`_, so while supported by this\n theme, they will not show up in site or page menus.\n* Internally, \"navbar.html\" is the Sphinx template used for Bootstrap v3 and\n \"navbar-2.html\" is the template used for v2.\n* If you are unsure what to choose, choose Bootstrap **3**. If you experience some\n form of compatibility issues, then try and use Bootstrap 2.\n\n.. _`sub-menus`: http://stackoverflow.com/questions/18023493\n\nExtending \"layout.html\"\n-----------------------\nAs a more \"hands on\" approach to customization, you can override any template\nin this Sphinx theme or any others. A good candidate for changes is\n\"layout.html\", which provides most of the look and feel. First, take a look\nat the \"layout.html\" file that the theme provides, and figure out\nwhat you need to override. As a side note, we have some theme-specific\nenhancements, such as the ``navbarextra`` template block for additional\ncontent in the navbar.\n\nThen, create your own \"_templates\" directory and \"layout.html\" file (assuming\nyou build from a \"source\" directory)::\n\n $ mkdir source/_templates\n $ touch source/_templates/layout.html\n\nThen, configure your \"conf.py\"::\n\n templates_path = ['_templates']\n\nFinally, edit your override file \"source/_templates/layout.html\"::\n\n {# Import the theme's layout. #}\n {% extends \"!layout.html\" %}\n\n {# Add some extra stuff before and use existing with 'super()' call. #}\n {% block footer %}\n

My footer of awesomeness.

\n {{ super() }}\n {% endblock %}\n\n\nAdding Custom CSS\n-----------------\nAlternately, you could add your own custom static media directory with a CSS\nfile to override a style, which in the demo would be something like::\n\n $ mkdir source/_static\n $ touch source/_static/my-styles.css\n\nIn the new file \"source/_static/my-styles.css\", add any appropriate styling,\ne.g. a bold background color::\n\n footer {\n background-color: red;\n }\n\nThen, in \"conf.py\", edit this line::\n\n html_static_path = [\"_static\"]\n\nFrom there it depends on which version of Sphinx you are using:\n\n**Sphinx <= 1.5**\n\nYou will need the override template \"source/_templates/layout.html\" file\nconfigured as above, but with the following code::\n\n {# Import the theme's layout. #}\n {% extends \"!layout.html\" %}\n\n {# Custom CSS overrides #}\n {% set css_files = css_files + ['_static/my-styles.css'] %}\n\n.. note::\n\n See `Issue #159 `_\n for more information.\n\n**Sphinx >= 1.6.1**\n\nAdd a ``setup`` function in \"conf.py\" with stylesheet paths added relative to the\nstatic path::\n\n def setup(app):\n app.add_stylesheet(\"my-styles.css\") # also can be a full URL\n # app.add_stylesheet(\"ANOTHER.css\")\n # app.add_stylesheet(\"AND_ANOTHER.css\")\n\n.. tip::\n\n Sphinx automatically calls your ``setup`` function defined in \"conf.py\" during\n the build process for you. There is no need to, nor should you, call this\n function directly in your code.\n\nTheme Notes\n===========\nSphinx\n------\nThe theme places the global TOC, local TOC, navigation (prev, next) and\nsource links all in the top Bootstrap navigation bar, along with the Sphinx\nsearch bar on the left side.\n\nThe global (site-wide) table of contents is the \"Site\" navigation dropdown,\nwhich is a configurable level rendering of the ``toctree`` for the entire site.\nThe local (page-level) table of contents is the \"Page\" navigation dropdown,\nwhich is a multi-level rendering of the current page's ``toc``.\n\n\nBootstrap\n---------\nThe theme offers Bootstrap v2.x and v3.x, both of which rely on\njQuery v.1.9.x. As the jQuery that Bootstrap wants can radically depart from\nthe jQuery Sphinx internal libraries use, the library from this theme is\nintegrated via ``noConflict()`` as ``$jqTheme``.\n\nYou can override any static JS/CSS files by dropping different versions in your\nSphinx \"_static\" directory.\n\n\nContributing\n============\nContributions to this project are most welcome. Please make sure that the demo\nsite builds cleanly, and looks like what you want. This project uses `tox\n`_ for development, once you have ``tox``\ninstalled (e.g., ``pip install tox``), change directories to the\n``sphinx-bootstrap-theme`` top-level directory.\n\n- Building documentation: ``tox -e docs``\n- Validate html links in documentation: ``tox -e linkcheck``\n- Validate the code style: ``tox -e lint``\n\nThe encouraged way to develop with this package is to use a development server.\nChanges made to files local in the repository will require rebuilding the\ndemo website, and using the development server will automate this process.\n\n1. In your terminal, execute ``tox -e server`` from the top level directory.\n By default, this runs on port ``8000``. If this port is in use, a\n pass-through argument to the underlying `sphinx-autobuild\n `_ tool is required\n such as ``tox -e server -- -p 8080``. The ``--`` between ``server`` and\n ``-p`` are required, that signals the end of the arguments to ``tox`` and\n everything after gets fed to ``sphinx-autobuild``.\n\n2. Open your browser of choice and visit `http://127.0.0.1:8000/\n `_ to see the server.\n\n3. Make any intended edits to the files in this repository. After the server\n finishes rebuilding you can refresh your browser to see the updates.\n\n4. When finished, make sure to end the server from your terminal you ran\n ``tox -e server`` with by issuing ``ctrl+c``.\n\nPackaging\n=========\n\nWhen a tag is pushed of the form ``vX.Y.Z`` (with the starting ``v``), it will\nbuild the distribution using ``tox -e dist`` and upload to PyPI automatically.\nBefore pushing a tag, using Test PyPI should be done. In addition to ``tox``,\ninstall `twine `_\n(``pip install twine``).\n\n.. code-block:: console\n\n # Build the distribution locally.\n $ tox -e dist\n\n # Attempt uploading to Test PyPI\n $ twine upload -r testpypi dist/*\n\n.. note::\n\n The file ``sphinx_bootstrap_theme/__init__.py`` has the version number that\n will be created. **Make sure it matches the tag you are creating**, once\n an upload goes up it cannot be overwritten. If in preparing a release you\n find an error and need to rebuild, simply increase the ``dev`` version\n in ``__init__.py`` and then rebuild and reupload. For example:\n\n .. code-block:: diff\n\n --- a/sphinx_bootstrap_theme/__init__.py\n +++ b/sphinx_bootstrap_theme/__init__.py\n @@ -1,7 +1,7 @@\n \"\"\"Sphinx bootstrap theme.\"\"\"\n import os\n\n -__version__ = \"0.8.0.dev0\"\n +__version__ = \"0.8.0.dev1\"\n\nAfter verifying that `everything appears as desired on Test PyPI\n`_ at the project\nURL, one can also test the installation if desired: ``pip install\n--index-url https://test.pypi.org/simple/ sphinx-bootstrap-theme``\n\nNow that everything is validated, we are ready for release.\n\n1. Set the version number in ``sphinx_bootstrap_theme/__init__.py`` correctly.\n E.g., for release ``0.8.0``, set ``__version__ = \"0.8.0\"`` without the\n trailing ``dev`` qualifier.\n\n2. If desired, rebuild and upload to Test PyPI. Commit and push the changed\n version number. Tag this commit ``git tag v0.8.0`` (note the leading ``v``\n is required for the CI/CD), and ``git push --tags``. This should initiate\n the official release and upload it to PyPI (see the files\n ``.github/workflows/{package,github_pages}.yaml`` for more).\n\n3. Now that the release is out, update the version number so that any users\n installing from source do not believe they have an official release. E.g.,\n set ``__version__ = \"0.8.1.dev0\"``, commit and push this \"dev version bump\"\n online.\n\n\nLicenses\n========\nSphinx Bootstrap Theme is licensed under the MIT_ license.\n\n`Bootstrap v2`_ is licensed under the Apache license 2.0.\n\n`Bootstrap v3.1.0+`_ is licensed under the MIT license.\n\n.. _`MIT`: https://github.com/ryan-roemer/sphinx-bootstrap-theme/blob/master/LICENSE.txt\n.. _`Bootstrap v2`: https://github.com/twbs/bootstrap/blob/v2.3.2/LICENSE\n.. _`Bootstrap v3.1.0+`: https://github.com/twbs/bootstrap/blob/master/LICENSE\n\n\n\n","description_content_type":"text/x-rst","docs_url":null,"download_url":"","downloads":{"last_day":-1,"last_month":-1,"last_week":-1},"dynamic":null,"home_page":"https://ryan-roemer.github.io/sphinx-bootstrap-theme/README.html","keywords":"sphinx,bootstrap,html,theme","license":"","license_expression":null,"license_files":null,"maintainer":"","maintainer_email":"","name":"sphinx-bootstrap-theme","package_url":"https://pypi.org/project/sphinx-bootstrap-theme/","platform":"","project_url":"https://pypi.org/project/sphinx-bootstrap-theme/","project_urls":{"Homepage":"https://ryan-roemer.github.io/sphinx-bootstrap-theme/README.html"},"provides_extra":null,"release_url":"https://pypi.org/project/sphinx-bootstrap-theme/0.8.1/","requires_dist":null,"requires_python":"","summary":"Sphinx Bootstrap Theme.","version":"0.8.1","yanked":false,"yanked_reason":null}

Package search

sphinx-bootstrap-theme

project_urls

Dependencies

All package metadata

Releases