| 1 |
Metadata-Version: 1.1 |
| 2 |
Name: guzzle_sphinx_theme |
| 3 |
Version: 0.7.11 |
| 4 |
Summary: Sphinx theme used by Guzzle. |
| 5 |
Home-page: https://github.com/guzzle/guzzle_sphinx_theme |
| 6 |
Author: Michael Dowling |
| 7 |
Author-email: [email protected] |
| 8 |
License: UNKNOWN |
| 9 |
Description: =================== |
| 10 |
Guzzle Sphinx Theme |
| 11 |
=================== |
| 12 |
|
| 13 |
Sphinx theme used by Guzzle: http://guzzlephp.org |
| 14 |
|
| 15 |
Installation |
| 16 |
============ |
| 17 |
|
| 18 |
Install via pip:: |
| 19 |
|
| 20 |
$ pip install guzzle_sphinx_theme |
| 21 |
|
| 22 |
or if you have the code checked out locally:: |
| 23 |
|
| 24 |
$ python setup.py install |
| 25 |
|
| 26 |
Configuration |
| 27 |
============= |
| 28 |
|
| 29 |
Add the following to your conf.py: |
| 30 |
|
| 31 |
.. code-block:: python |
| 32 |
|
| 33 |
import guzzle_sphinx_theme |
| 34 |
|
| 35 |
# Adds an HTML table visitor to apply Bootstrap table classes |
| 36 |
html_translator_class = 'guzzle_sphinx_theme.HTMLTranslator' |
| 37 |
html_theme_path = guzzle_sphinx_theme.html_theme_path() |
| 38 |
html_theme = 'guzzle_sphinx_theme' |
| 39 |
|
| 40 |
# Register the theme as an extension to generate a sitemap.xml |
| 41 |
extensions.append("guzzle_sphinx_theme") |
| 42 |
|
| 43 |
# Guzzle theme options (see theme.conf for more information) |
| 44 |
html_theme_options = { |
| 45 |
# Set the name of the project to appear in the sidebar |
| 46 |
"project_nav_name": "Project Name", |
| 47 |
} |
| 48 |
|
| 49 |
There are a lot more ways to customize this theme, as this more comprehensive |
| 50 |
example shows: |
| 51 |
|
| 52 |
.. code-block:: python |
| 53 |
|
| 54 |
import guzzle_sphinx_theme |
| 55 |
|
| 56 |
# Adds an HTML table visitor to apply Bootstrap table classes |
| 57 |
html_translator_class = 'guzzle_sphinx_theme.HTMLTranslator' |
| 58 |
html_theme_path = guzzle_sphinx_theme.html_theme_path() |
| 59 |
html_theme = 'guzzle_sphinx_theme' |
| 60 |
|
| 61 |
# Register the theme as an extension to generate a sitemap.xml |
| 62 |
extensions.append("guzzle_sphinx_theme") |
| 63 |
|
| 64 |
# Guzzle theme options (see theme.conf for more information) |
| 65 |
html_theme_options = { |
| 66 |
|
| 67 |
# Set the path to a special layout to include for the homepage |
| 68 |
"index_template": "special_index.html", |
| 69 |
|
| 70 |
# Set the name of the project to appear in the left sidebar. |
| 71 |
"project_nav_name": "Project Name", |
| 72 |
|
| 73 |
# Set your Disqus short name to enable comments |
| 74 |
"disqus_comments_shortname": "my_disqus_comments_short_name", |
| 75 |
|
| 76 |
# Set you GA account ID to enable tracking |
| 77 |
"google_analytics_account": "my_ga_account", |
| 78 |
|
| 79 |
# Path to a touch icon |
| 80 |
"touch_icon": "", |
| 81 |
|
| 82 |
# Specify a base_url used to generate sitemap.xml links. If not |
| 83 |
# specified, then no sitemap will be built. |
| 84 |
"base_url": "" |
| 85 |
|
| 86 |
# Allow a separate homepage from the master_doc |
| 87 |
"homepage": "index", |
| 88 |
|
| 89 |
# Allow the project link to be overriden to a custom URL. |
| 90 |
"projectlink": "http://myproject.url", |
| 91 |
} |
| 92 |
|
| 93 |
Customizing the layout |
| 94 |
====================== |
| 95 |
|
| 96 |
You can customize the theme by overriding Jinja template blocks. For example, |
| 97 |
"layout.html" contains several blocks that can be overridden or extended. |
| 98 |
|
| 99 |
Place a "layout.html" file in your project's "/_templates" directory. |
| 100 |
|
| 101 |
.. code-block:: bash |
| 102 |
|
| 103 |
mkdir source/_templates |
| 104 |
touch source/_templates/layout.html |
| 105 |
|
| 106 |
Then, configure your "conf.py": |
| 107 |
|
| 108 |
.. code-block:: python |
| 109 |
|
| 110 |
templates_path = ['_templates'] |
| 111 |
|
| 112 |
Finally, edit your override file "source/_templates/layout.html": |
| 113 |
|
| 114 |
:: |
| 115 |
|
| 116 |
{# Import the theme's layout. #} |
| 117 |
{% extends "!layout.html" %} |
| 118 |
|
| 119 |
{%- block extra_head %} |
| 120 |
{# Add custom things to the head HTML tag #} |
| 121 |
{# Call the parent block #} |
| 122 |
{{ super() }} |
| 123 |
{%- endblock %} |
| 124 |
|
| 125 |
.. note:: |
| 126 |
|
| 127 |
If you are using Readthedocs, then you might run into an issue where they |
| 128 |
don't currently allow you to extend layout.html. |
| 129 |
|
| 130 |
Platform: UNKNOWN |
| 131 |
Classifier: Development Status :: 3 - Alpha |
| 132 |
Classifier: Intended Audience :: Developers |
| 133 |
Classifier: Natural Language :: English |
| 134 |
Classifier: License :: OSI Approved :: MIT License |
| 135 |
Classifier: Programming Language :: Python |