diff options
| -rw-r--r-- | LICENSE.rst | 34 | ||||
| -rw-r--r-- | PKG-INFO | 67 | ||||
| -rw-r--r-- | README.rst | 33 | ||||
| -rw-r--r-- | alabaster/__init__.py | 35 | ||||
| -rw-r--r-- | alabaster/about.html | 59 | ||||
| -rw-r--r-- | alabaster/donate.html | 28 | ||||
| -rw-r--r-- | alabaster/layout.html | 126 | ||||
| -rw-r--r-- | alabaster/navigation.html | 10 | ||||
| -rw-r--r-- | alabaster/relations.html | 21 | ||||
| -rw-r--r-- | alabaster/static/alabaster.css_t | 776 | ||||
| -rw-r--r-- | alabaster/static/custom.css | 1 | ||||
| -rw-r--r-- | alabaster/support.py | 89 | ||||
| -rw-r--r-- | alabaster/theme.conf | 132 | ||||
| -rw-r--r-- | docs/changelog.rst | 361 | ||||
| -rw-r--r-- | docs/conf.py | 38 | ||||
| -rw-r--r-- | docs/customization.rst | 272 | ||||
| -rw-r--r-- | docs/index.rst | 49 | ||||
| -rw-r--r-- | docs/installation.rst | 67 | ||||
| -rw-r--r-- | docs/requirements.txt | 1 | ||||
| -rw-r--r-- | pyproject.toml | 58 |
20 files changed, 2257 insertions, 0 deletions
diff --git a/LICENSE.rst b/LICENSE.rst new file mode 100644 index 0000000..19361a7 --- /dev/null +++ b/LICENSE.rst @@ -0,0 +1,34 @@ +Copyright (c) 2020 Jeff Forcier. + +Based on original work copyright (c) 2011 Kenneth Reitz and copyright (c) 2010 +Armin Ronacher. + +Some rights reserved. + +Redistribution and use in source and binary forms of the theme, with or +without modification, are permitted provided that the following conditions +are met: + +* Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + +* Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials provided + with the distribution. + +* The names of the contributors may not be used to endorse or + promote products derived from this software without specific + prior written permission. + +THIS THEME IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +ARISING IN ANY WAY OUT OF THE USE OF THIS THEME, EVEN IF ADVISED OF THE +POSSIBILITY OF SUCH DAMAGE. diff --git a/PKG-INFO b/PKG-INFO new file mode 100644 index 0000000..38bf33f --- /dev/null +++ b/PKG-INFO @@ -0,0 +1,67 @@ +Metadata-Version: 2.1 +Name: alabaster +Version: 0.7.16 +Summary: A light, configurable Sphinx theme +Author-email: Jeff Forcier <jeff@bitprophet.org> +Maintainer: The Sphinx Developers +Requires-Python: >=3.9 +Description-Content-Type: text/x-rst +Classifier: Development Status :: 5 - Production/Stable +Classifier: Framework :: Sphinx +Classifier: Framework :: Sphinx :: Theme +Classifier: Intended Audience :: Developers +Classifier: License :: OSI Approved :: BSD License +Classifier: Operating System :: OS Independent +Classifier: Programming Language :: Python :: 3 +Classifier: Programming Language :: Python :: 3 :: Only +Classifier: Programming Language :: Python :: 3.9 +Classifier: Programming Language :: Python :: 3.10 +Classifier: Programming Language :: Python :: 3.11 +Classifier: Programming Language :: Python :: 3.12 +Classifier: Programming Language :: Python :: 3.13 +Classifier: Programming Language :: Python :: Implementation :: CPython +Classifier: Programming Language :: Python :: Implementation :: PyPy +Classifier: Topic :: Documentation +Classifier: Topic :: Documentation :: Sphinx +Classifier: Topic :: Software Development :: Documentation +Project-URL: Changelog, https://alabaster.readthedocs.io/en/latest/changelog.html +Project-URL: Documentation, https://alabaster.readthedocs.io/ +Project-URL: Download, https://pypi.org/project/alabaster/ +Project-URL: Homepage, https://alabaster.readthedocs.io/ +Project-URL: Issue tracker, https://github.com/bitprophet/alabaster/issues +Project-URL: Source, https://github.com/sphinx-doc/alabaster + +.. image:: https://img.shields.io/pypi/v/alabaster.svg + :target: https://pypi.org/project/alabaster/ + :alt: Package on PyPI + +.. image:: https://github.com/sphinx-doc/alabaster/actions/workflows/test.yml/badge.svg + :target: https://github.com/sphinx-doc/alabaster/actions/workflows/test.yml + :alt: CI Status + +.. image:: https://readthedocs.org/projects/alabaster/badge/ + :target: https://alabaster.readthedocs.io/ + :alt: Documentation Status + +.. image:: https://img.shields.io/badge/License-BSD%203--Clause-blue.svg + :target: https://opensource.org/license/BSD-3-Clause + :alt: BSD 3 Clause + + +What is Alabaster? +================== + +Alabaster is a visually (c)lean, responsive, configurable theme for the `Sphinx +<https://www.sphinx-doc.org>`_ documentation system. +It requires Python 3.9 or newer and Sphinx 3.4 or newer. + +It began as a third-party theme, and is still maintained separately, but as of +Sphinx 1.3, Alabaster is an install-time dependency of Sphinx and is selected +as the default theme. + +Live examples of this theme can be seen on `this project's own website +<https://alabaster.readthedocs.io/>`_, `paramiko.org <https://www.paramiko.org>`_, +`fabfile.org <https://www.fabfile.org>`_ and `pyinvoke.org <https://www.pyinvoke.org>`_. + +For more documentation, please see https://alabaster.readthedocs.io/. + diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..380897e --- /dev/null +++ b/README.rst @@ -0,0 +1,33 @@ +.. image:: https://img.shields.io/pypi/v/alabaster.svg + :target: https://pypi.org/project/alabaster/ + :alt: Package on PyPI + +.. image:: https://github.com/sphinx-doc/alabaster/actions/workflows/test.yml/badge.svg + :target: https://github.com/sphinx-doc/alabaster/actions/workflows/test.yml + :alt: CI Status + +.. image:: https://readthedocs.org/projects/alabaster/badge/ + :target: https://alabaster.readthedocs.io/ + :alt: Documentation Status + +.. image:: https://img.shields.io/badge/License-BSD%203--Clause-blue.svg + :target: https://opensource.org/license/BSD-3-Clause + :alt: BSD 3 Clause + + +What is Alabaster? +================== + +Alabaster is a visually (c)lean, responsive, configurable theme for the `Sphinx +<https://www.sphinx-doc.org>`_ documentation system. +It requires Python 3.9 or newer and Sphinx 3.4 or newer. + +It began as a third-party theme, and is still maintained separately, but as of +Sphinx 1.3, Alabaster is an install-time dependency of Sphinx and is selected +as the default theme. + +Live examples of this theme can be seen on `this project's own website +<https://alabaster.readthedocs.io/>`_, `paramiko.org <https://www.paramiko.org>`_, +`fabfile.org <https://www.fabfile.org>`_ and `pyinvoke.org <https://www.pyinvoke.org>`_. + +For more documentation, please see https://alabaster.readthedocs.io/. diff --git a/alabaster/__init__.py b/alabaster/__init__.py new file mode 100644 index 0000000..8da4cac --- /dev/null +++ b/alabaster/__init__.py @@ -0,0 +1,35 @@ +import os + +__version_info__ = (0, 7, 16) +__version__ = "0.7.16" + + +def get_path(): + """ + Shortcut for users whose theme is next to their conf.py. + """ + # Theme directory is defined as our parent directory + return os.path.abspath(os.path.dirname(os.path.dirname(__file__))) + + +def update_context(app, pagename, templatename, context, doctree): + context["alabaster_version"] = __version__ + context["alabaster_version_info"] = __version_info__ + + # Convert 'show_powered_by' in the theme options to + # the preferred option, html_show_sphinx. + html_theme_options = app.config.html_theme_options + if "show_powered_by" in html_theme_options: + show_powered_by = html_theme_options["show_powered_by"] + if isinstance(show_powered_by, str): + context["show_sphinx"] = show_powered_by.lower() == "true" + else: + context["show_sphinx"] = bool(show_powered_by) # to allow int values + + +def setup(app): + app.require_sphinx("3.4") + theme_path = os.path.abspath(os.path.dirname(__file__)) + app.add_html_theme("alabaster", theme_path) + app.connect("html-page-context", update_context) + return {"version": __version__, "parallel_read_safe": True} diff --git a/alabaster/about.html b/alabaster/about.html new file mode 100644 index 0000000..2bf686f --- /dev/null +++ b/alabaster/about.html @@ -0,0 +1,59 @@ +{% if theme_logo %} +<p class="logo"> + <a href="{{ pathto(master_doc) }}"> + <img class="logo" src="{{ pathto('_static/' ~ theme_logo, 1) }}" alt="Logo" /> + {% if theme_logo_name|lower == 'true' %} + <h1 class="logo logo-name">{{ project }}</h1> + {% elif theme_logo_name|lower != 'false' %} + <h1 class="logo logo-name">{{ theme_logo_name }}</h1> + {% endif %} + </a> +</p> +{% else %} +<h1 class="logo"><a href="{{ pathto(master_doc) }}">{{ project }}</a></h1> +{% endif %} + +{% if theme_description %} +<p class="blurb">{{ theme_description }}</p> +{% endif %} + +{% if theme_github_user and theme_github_repo %} +{% if theme_github_button|lower == 'true' %} +<p> +<iframe src="https://ghbtns.com/github-btn.html?user={{ theme_github_user }}&repo={{ theme_github_repo }}&type={{ theme_github_type }}&count={{ theme_github_count }}&size=large&v=2" + allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe> +</p> +{% endif %} +{% endif %} + +{% if theme_travis_button|lower != 'false' %} +{% if theme_travis_button|lower == 'true' %} + {% set path = theme_github_user + '/' + theme_github_repo %} +{% else %} + {% set path = theme_travis_button %} +{% endif %} +<p> +<a class="badge" href="https://travis-ci.org/{{ path }}"> + <img + alt="https://secure.travis-ci.org/{{ path }}.svg?branch={{ theme_badge_branch }}" + src="https://secure.travis-ci.org/{{ path }}.svg?branch={{ theme_badge_branch }}" + /> +</a> +</p> +{% endif %} + +{% if theme_codecov_button|lower != 'false' %} +{% if theme_codecov_button|lower == 'true' %} + {% set path = theme_github_user + '/' + theme_github_repo %} +{% else %} + {% set path = theme_codecov_button %} +{% endif %} +<p> +<a class="badge" href="https://codecov.io/github/{{ path }}"> + <img + alt="https://codecov.io/github/{{ path }}/coverage.svg?branch={{ theme_badge_branch }}" + src="https://codecov.io/github/{{ path }}/coverage.svg?branch={{ theme_badge_branch }}" + /> +</a> +</p> +{% endif %} diff --git a/alabaster/donate.html b/alabaster/donate.html new file mode 100644 index 0000000..f150c78 --- /dev/null +++ b/alabaster/donate.html @@ -0,0 +1,28 @@ +{# TODO: wrap all these in their own divs for easier styling #} + +{% if theme_donate_url or theme_opencollective or theme_tidelift_url %} +<h3 class="donation">Donate/support</h3> +{% endif %} + +{% if theme_donate_url %} +<p> +<a class="badge" href="{{ theme_donate_url }}"> +<img src="https://img.shields.io/badge/donate-%E2%9D%A4%C2%A0-ff69b4.svg?style=flat" alt="Donate"> +</a> +</p> +{% endif %} + +{% if theme_opencollective %} +<p> +<a class="badge" href="https://opencollective.com/{{ theme_opencollective }}/donate" target="_blank"> + <img src="https://opencollective.com/{{ theme_opencollective }}/donate/button.png?color={{ theme_opencollective_button_color }}" width=300 /> +</a> +</p> +{% endif %} + +{% if theme_tidelift_url %} +<p> +Professionally-supported {{ project }} is available with the +<a href="{{ theme_tidelift_url }}">Tidelift Subscription</a>. +</p> +{% endif %} diff --git a/alabaster/layout.html b/alabaster/layout.html new file mode 100644 index 0000000..a7ca710 --- /dev/null +++ b/alabaster/layout.html @@ -0,0 +1,126 @@ +{%- extends "basic/layout.html" %} + +{%- block extrahead %} + {{ super() }} + <link rel="stylesheet" href="{{ pathto('_static/custom.css', 1) }}" type="text/css" /> + {% if theme_touch_icon %} + <link rel="apple-touch-icon" href="{{ pathto('_static/' ~ theme_touch_icon, 1) }}" /> + {% endif %} + + {# Deprecated in favor of html_baseurl (pageurl). This is already set in the basic theme #} + {% if theme_canonical_url and not pageurl %} + <link rel="canonical" href="{{ theme_canonical_url }}{{ pagename }}.html" /> + {% endif %} +{% endblock %} + +{# top+bottom related navs; we also have our own in sidebar #} +{%- macro rellink_markup() %} + <nav id="rellinks"> + <ul> + {%- if prev %} + <li> + ← + <a href="{{ prev.link|e }}" title="Previous document">{{ prev.title }}</a> + </li> + {%- endif %} + {%- if next %} + <li> + <a href="{{ next.link|e }}" title="Next document">{{ next.title }}</a> + → + </li> + {%- endif %} + </ul> + </nav> +{%- endmacro %} + +{%- set theme_show_relbar_top = theme_show_relbar_top or theme_show_relbars %} +{%- set theme_show_relbar_bottom = theme_show_relbar_bottom or theme_show_relbars %} + +{# removed existing top+bottom related nav, and embed in main content #} +{%- block relbar1 %}{% endblock %} +{%- block relbar2 %}{% endblock %} + +{# Nav should appear before content, not after #} +{%- block content %} +{%- if theme_fixed_sidebar|lower == 'true' %} + <div class="document"> + {{ sidebar() }} + {%- block document %} + <div class="documentwrapper"> + {%- if render_sidebar %} + <div class="bodywrapper"> + {%- endif %} + + {%- block relbar_top %} + {%- if theme_show_relbar_top|tobool %} + <div class="related top"> + + {{- rellink_markup () }} + </div> + {%- endif %} + {% endblock %} + + <div class="body" role="main"> + {% block body %} {% endblock %} + </div> + + {%- block relbar_bottom %} + {%- if theme_show_relbar_bottom|tobool %} + <div class="related bottom"> + + {{- rellink_markup () }} + </div> + {%- endif %} + {% endblock %} + + {%- if render_sidebar %} + </div> + {%- endif %} + </div> + {%- endblock %} + <div class="clearer"></div> + </div> +{%- else %} +{{ super() }} +{%- endif %} +{%- endblock %} + +{%- block footer %} + <div class="footer"> + {% if show_copyright %}©{{ copyright }}.{% endif %} + {% if show_sphinx %} + {% if show_copyright %}|{% endif %} + Powered by <a href="https://www.sphinx-doc.org/">Sphinx {{ sphinx_version }}</a> + & <a href="https://alabaster.readthedocs.io">Alabaster {{ alabaster_version }}</a> + {% endif %} + {%- if show_source and has_source and sourcename %} + {% if show_copyright or show_sphinx %}|{% endif %} + <a href="{{ pathto('_sources/' + sourcename, true)|e }}" + rel="nofollow">{{ _('Page source') }}</a> + {%- endif %} + </div> + + {% if theme_github_banner|lower != 'false' %} + <a href="https://github.com/{{ theme_github_user }}/{{ theme_github_repo }}" class="github"> + <img style="position: absolute; top: 0; right: 0; border: 0;" src="{{ pathto('_static/' ~ theme_github_banner, 1) if theme_github_banner|lower != 'true' else 'https://github.blog/wp-content/uploads/2008/12/forkme_right_darkblue_121621.png' }}" alt="Fork me on GitHub" class="github"/> + </a> + {% endif %} + + {% if theme_analytics_id %} + <script> + + var _gaq = _gaq || []; + _gaq.push(['_setAccount', '{{ theme_analytics_id }}']); + _gaq.push(['_setDomainName', 'none']); + _gaq.push(['_setAllowLinker', true]); + _gaq.push(['_trackPageview']); + + (function() { + var ga = document.createElement('script'); ga.async = true; + ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'https://www') + '.google-analytics.com/ga.js'; + var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); + })(); + + </script> + {% endif %} +{%- endblock %} diff --git a/alabaster/navigation.html b/alabaster/navigation.html new file mode 100644 index 0000000..760dcc9 --- /dev/null +++ b/alabaster/navigation.html @@ -0,0 +1,10 @@ +<h3>{{ _('Navigation') }}</h3> +{{ toctree(includehidden=theme_sidebar_includehidden, collapse=theme_sidebar_collapse) }} +{% if theme_extra_nav_links %} +<hr /> +<ul> + {% for text, uri in theme_extra_nav_links.items() %} + <li class="toctree-l1"><a href="{{ uri }}">{{ text }}</a></li> + {% endfor %} +</ul> +{% endif %} diff --git a/alabaster/relations.html b/alabaster/relations.html new file mode 100644 index 0000000..770446c --- /dev/null +++ b/alabaster/relations.html @@ -0,0 +1,21 @@ +<div class="relations"> +<h3>Related Topics</h3> +<ul> + <li><a href="{{ pathto(master_doc) }}">Documentation overview</a><ul> + {%- for parent in parents %} + <li><a href="{{ parent.link|e }}">{{ parent.title }}</a><ul> + {%- endfor %} + {%- if prev %} + <li>Previous: <a href="{{ prev.link|e }}" title="{{ _('previous chapter') + }}">{{ prev.title }}</a></li> + {%- endif %} + {%- if next %} + <li>Next: <a href="{{ next.link|e }}" title="{{ _('next chapter') + }}">{{ next.title }}</a></li> + {%- endif %} + {%- for parent in parents %} + </ul></li> + {%- endfor %} + </ul></li> +</ul> +</div> diff --git a/alabaster/static/alabaster.css_t b/alabaster/static/alabaster.css_t new file mode 100644 index 0000000..720b7af --- /dev/null +++ b/alabaster/static/alabaster.css_t @@ -0,0 +1,776 @@ +{%- set theme_body_bg = theme_body_bg or theme_base_bg %} +{%- set theme_code_highlight_bg = theme_code_highlight_bg or theme_body_bg %} +{%- set theme_sidebar_header = theme_sidebar_header or theme_gray_1 %} +{%- set theme_sidebar_link = theme_sidebar_link or theme_gray_1 %} +{%- set theme_anchor_hover_fg = theme_anchor_hover_fg or theme_gray_1 %} + +{%- set theme_footnote_border = theme_footnote_border or theme_gray_2 %} +{%- set theme_pre_bg = theme_pre_bg or theme_gray_2 %} + +{%- set theme_head_font_family = theme_head_font_family or theme_font_family %} + +{#- set up admonition styling #} +{#- - basic level #} +{%- set theme_admonition_xref_bg = theme_admonition_xref_bg or theme_xref_bg %} +{%- set theme_admonition_bg = theme_admonition_bg or theme_gray_2 %} +{%- set theme_note_bg = theme_note_bg or theme_gray_2 %} +{%- set theme_seealso_bg = theme_seealso_bg or theme_gray_2 %} + +{#- - critical level #} +{%- set theme_danger_bg = theme_danger_bg or theme_pink_1 %} +{%- set theme_danger_border = theme_danger_border or theme_pink_2 %} +{%- set theme_danger_shadow = theme_danger_shadow or theme_pink_3 %} + +{%- set theme_error_bg = theme_error_bg or theme_pink_1 %} +{%- set theme_error_border = theme_error_border or theme_pink_2 %} +{%- set theme_error_shadow = theme_error_shadow or theme_pink_3 %} + +{#- - warning level #} +{%- set theme_caution_bg = theme_caution_bg or theme_pink_1 %} +{%- set theme_caution_border = theme_caution_border or theme_pink_2 %} + +{%- set theme_attention_bg = theme_attention_bg or theme_pink_1 %} +{%- set theme_attention_border = theme_attention_border or theme_pink_2 %} + +{%- set theme_warn_bg = theme_warn_bg or theme_pink_1 %} +{%- set theme_warn_border = theme_warn_border or theme_pink_2 %} + +{#- - normal level #} +{%- set theme_important_bg = theme_important_bg or theme_gray_2 %} +{%- set theme_tip_bg = theme_tip_bg or theme_gray_2 %} +{%- set theme_hint_bg = theme_hint_bg or theme_gray_2 %} + +{#- /set up admonition styling #} + +{%- set theme_shadow = theme_shadow or theme_gray_2 %} + + +{%- set theme_topic_bg = theme_topic_bg or theme_gray_2 %} + +{%- set theme_narrow_sidebar_link = theme_narrow_sidebar_link or theme_gray_3 %} +{%- set theme_sidebar_hr = theme_sidebar_hr or theme_gray_3 %} + +{%- set theme_relbar_border = theme_relbar_border or theme_gray_2 -%} + + +@import url("basic.css"); + +/* -- page layout ----------------------------------------------------------- */ + +body { + font-family: {{ theme_font_family }}; + font-size: {{ theme_font_size }}; + background-color: {{ theme_base_bg }}; + color: {{ theme_base_text }}; + margin: 0; + padding: 0; +} + + +div.document { + width: {{ theme_page_width }}; + margin: 30px auto 0 auto; +} + +div.documentwrapper { + float: left; + width: 100%; +} + +div.bodywrapper { + margin: 0 0 0 {{ theme_sidebar_width }}; +} + +div.sphinxsidebar { + width: {{ theme_sidebar_width }}; + font-size: 14px; + line-height: 1.5; +} + +hr { + border: 1px solid {{ theme_hr_border }}; +} + +div.body { + background-color: {{ theme_body_bg }}; + color: {{ theme_body_text }}; + padding: 0 30px 0 30px; +} + +div.body > .section { + text-align: {{ theme_body_text_align }}; +} + +div.footer { + width: {{ theme_page_width }}; + margin: 20px auto 30px auto; + font-size: 14px; + color: {{ theme_footer_text }}; + text-align: right; +} + +div.footer a { + color: {{ theme_footer_text }}; +} + +p.caption { + font-family: {{ theme_caption_font_family }}; + font-size: {{ theme_caption_font_size }}; +} + +{% if theme_show_related|lower == 'false' %} +div.relations { + display: none; +} +{% endif %} + +div.sphinxsidebar { + max-height: 100%; + overflow-y: auto; +} + +div.sphinxsidebar a { + color: {{ theme_sidebar_link }}; + text-decoration: none; + border-bottom: 1px dotted {{ theme_sidebar_link_underscore }}; +} + +div.sphinxsidebar a:hover { + border-bottom: 1px solid {{ theme_sidebar_link_underscore }}; +} + +div.sphinxsidebarwrapper { + padding: 18px 10px; +} + +div.sphinxsidebarwrapper p.logo { + padding: 0; + margin: -10px 0 0 0px; + text-align: center; +} + +div.sphinxsidebarwrapper h1.logo { + margin-top: -10px; + text-align: center; + margin-bottom: 5px; + text-align: {{ theme_logo_text_align }}; +} + +div.sphinxsidebarwrapper h1.logo-name { + margin-top: 0px; +} + +div.sphinxsidebarwrapper p.blurb { + margin-top: 0; + font-style: {{ theme_description_font_style }}; +} + +div.sphinxsidebar h3, +div.sphinxsidebar h4 { + font-family: {{ theme_head_font_family }}; + color: {{ theme_sidebar_header }}; + font-size: 24px; + font-weight: normal; + margin: 0 0 5px 0; + padding: 0; +} + +div.sphinxsidebar h4 { + font-size: 20px; +} + +div.sphinxsidebar h3 a { + color: {{ theme_sidebar_link }}; +} + +div.sphinxsidebar p.logo a, +div.sphinxsidebar h3 a, +div.sphinxsidebar p.logo a:hover, +div.sphinxsidebar h3 a:hover { + border: none; +} + +div.sphinxsidebar p { + color: {{ theme_sidebar_text }}; + margin: 10px 0; +} + +div.sphinxsidebar ul { + margin: 10px 0; + padding: 0; + color: {{ theme_sidebar_list }}; +} + +div.sphinxsidebar ul li.toctree-l1 > a { + font-size: 120%; +} + +div.sphinxsidebar ul li.toctree-l2 > a { + font-size: 110%; +} + +div.sphinxsidebar input { + border: 1px solid {{ theme_sidebar_search_button }}; + font-family: {{ theme_font_family }}; + font-size: 1em; +} + +div.sphinxsidebar #searchbox input[type="text"] { + width: 160px; +} + +div.sphinxsidebar .search > div { + display: table-cell; +} + +div.sphinxsidebar hr { + border: none; + height: 1px; + color: {{ theme_sidebar_hr }}; + background: {{ theme_sidebar_hr }}; + + text-align: left; + margin-left: 0; + width: 50%; +} + +div.sphinxsidebar .badge { + border-bottom: none; +} + +div.sphinxsidebar .badge:hover { + border-bottom: none; +} + +/* To address an issue with donation coming after search */ +div.sphinxsidebar h3.donation { + margin-top: 10px; +} + +/* -- body styles ----------------------------------------------------------- */ + +a { + color: {{ theme_link }}; + text-decoration: underline; +} + +a:hover { + color: {{ theme_link_hover }}; + text-decoration: underline; +} + +div.body h1, +div.body h2, +div.body h3, +div.body h4, +div.body h5, +div.body h6 { + font-family: {{ theme_head_font_family }}; + font-weight: normal; + margin: 30px 0px 10px 0px; + padding: 0; +} + +div.body h1 { margin-top: 0; padding-top: 0; font-size: 240%; } +div.body h2 { font-size: 180%; } +div.body h3 { font-size: 150%; } +div.body h4 { font-size: 130%; } +div.body h5 { font-size: 100%; } +div.body h6 { font-size: 100%; } + +a.headerlink { + color: {{ theme_anchor }}; + padding: 0 4px; + text-decoration: none; +} + +a.headerlink:hover { + color: {{ theme_anchor_hover_fg }}; + background: {{ theme_anchor_hover_bg }}; +} + +div.body p, div.body dd, div.body li { + line-height: 1.4em; +} + +div.admonition { + margin: 20px 0px; + padding: 10px 30px; + background-color: {{ theme_admonition_bg }}; + border: 1px solid {{ theme_admonition_border }}; +} + +div.admonition tt.xref, div.admonition code.xref, div.admonition a tt { + background-color: {{ theme_admonition_xref_bg }}; + border-bottom: 1px solid {{ theme_admonition_xref_border }}; +} + +div.admonition p.admonition-title { + font-family: {{ theme_head_font_family }}; + font-weight: normal; + font-size: 24px; + margin: 0 0 10px 0; + padding: 0; + line-height: 1; +} + +div.admonition p.last { + margin-bottom: 0; +} + +div.highlight { + background-color: {{ theme_code_highlight_bg }}; +} + +dt:target, .highlight { + background: {{ theme_highlight_bg }}; +} + +div.warning { + background-color: {{ theme_warn_bg }}; + border: 1px solid {{ theme_warn_border }}; +} + +div.danger { + background-color: {{ theme_danger_bg }}; + border: 1px solid {{ theme_danger_border }}; + -moz-box-shadow: 2px 2px 4px {{ theme_danger_shadow }}; + -webkit-box-shadow: 2px 2px 4px {{ theme_danger_shadow }}; + box-shadow: 2px 2px 4px {{ theme_danger_shadow }}; +} + +div.error { + background-color: {{ theme_error_bg }}; + border: 1px solid {{ theme_error_border }}; + -moz-box-shadow: 2px 2px 4px {{ theme_error_shadow }}; + -webkit-box-shadow: 2px 2px 4px {{ theme_error_shadow }}; + box-shadow: 2px 2px 4px {{ theme_error_shadow }}; +} + +div.caution { + background-color: {{ theme_caution_bg }}; + border: 1px solid {{ theme_caution_border }}; +} + +div.attention { + background-color: {{ theme_attention_bg }}; + border: 1px solid {{ theme_attention_border }}; +} + +div.important { + background-color: {{ theme_important_bg }}; + border: 1px solid {{ theme_important_border }}; +} + +div.note { + background-color: {{ theme_note_bg }}; + border: 1px solid {{ theme_note_border }}; +} + +div.tip { + background-color: {{ theme_tip_bg }}; + border: 1px solid {{ theme_tip_border }}; +} + +div.hint { + background-color: {{ theme_hint_bg }}; + border: 1px solid {{ theme_hint_border }}; +} + +div.seealso { + background-color: {{ theme_seealso_bg }}; + border: 1px solid {{ theme_seealso_border }}; +} + +div.topic { + background-color: {{ theme_topic_bg }}; +} + +p.admonition-title { + display: inline; +} + +p.admonition-title:after { + content: ":"; +} + +pre, tt, code { + font-family: {{theme_code_font_family}}; + font-size: {{ theme_code_font_size }}; +} + +.hll { + background-color: {{theme_code_highlight}}; + margin: 0 -12px; + padding: 0 12px; + display: block; +} + +img.screenshot { +} + +tt.descname, tt.descclassname, code.descname, code.descclassname { + font-size: 0.95em; +} + +tt.descname, code.descname { + padding-right: 0.08em; +} + +img.screenshot { + -moz-box-shadow: 2px 2px 4px {{ theme_shadow }}; + -webkit-box-shadow: 2px 2px 4px {{ theme_shadow }}; + box-shadow: 2px 2px 4px {{ theme_shadow }}; +} + +table.docutils { + border: 1px solid {{ theme_table_border }}; + -moz-box-shadow: 2px 2px 4px {{ theme_shadow }}; + -webkit-box-shadow: 2px 2px 4px {{ theme_shadow }}; + box-shadow: 2px 2px 4px {{ theme_shadow }}; +} + +table.docutils td, table.docutils th { + border: 1px solid {{ theme_table_border }}; + padding: 0.25em 0.7em; +} + +table.field-list, table.footnote { + border: none; + -moz-box-shadow: none; + -webkit-box-shadow: none; + box-shadow: none; +} + +table.footnote { + margin: 15px 0; + width: 100%; + border: 1px solid {{ theme_footnote_border }}; + background: {{ theme_footnote_bg }}; + font-size: 0.9em; +} + +table.footnote + table.footnote { + margin-top: -15px; + border-top: none; +} + +table.field-list th { + padding: 0 0.8em 0 0; +} + +table.field-list td { + padding: 0; +} + +table.field-list p { + margin-bottom: 0.8em; +} + +/* Cloned from + * https://github.com/sphinx-doc/sphinx/commit/ef60dbfce09286b20b7385333d63a60321784e68 + */ +.field-name { + -moz-hyphens: manual; + -ms-hyphens: manual; + -webkit-hyphens: manual; + hyphens: manual; +} + +table.footnote td.label { + width: .1px; + padding: 0.3em 0 0.3em 0.5em; +} + +table.footnote td { + padding: 0.3em 0.5em; +} + +dl { + margin-left: 0; + margin-right: 0; + margin-top: 0; + padding: 0; +} + +dl dd { + margin-left: 30px; +} + +blockquote { + margin: 0 0 0 30px; + padding: 0; +} + +ul, ol { + /* Matches the 30px from the narrow-screen "li > ul" selector below */ + margin: 10px 0 10px 30px; + padding: 0; +} + +pre { + background: {{ theme_pre_bg }}; + padding: 7px 30px; + margin: 15px 0px; + line-height: 1.3em; +} + +div.viewcode-block:target { + background: {{ theme_viewcode_target_bg }}; +} + +dl pre, blockquote pre, li pre { + margin-left: 0; + padding-left: 30px; +} + +tt, code { + background-color: {{ theme_code_bg }}; + color: {{ theme_code_text }}; + /* padding: 1px 2px; */ +} + +tt.xref, code.xref, a tt { + background-color: {{ theme_xref_bg }}; + border-bottom: 1px solid {{ theme_xref_border }}; +} + +a.reference { + text-decoration: none; + border-bottom: 1px dotted {{ theme_link }}; +} + +/* Don't put an underline on images */ +a.image-reference, a.image-reference:hover { + border-bottom: none; +} + +a.reference:hover { + border-bottom: 1px solid {{ theme_link_hover }}; +} + +a.footnote-reference { + text-decoration: none; + font-size: 0.7em; + vertical-align: top; + border-bottom: 1px dotted {{ theme_link }}; +} + +a.footnote-reference:hover { + border-bottom: 1px solid {{ theme_link_hover }}; +} + +a:hover tt, a:hover code { + background: {{ theme_code_hover }}; +} + + +@media screen and (max-width: 870px) { + + div.sphinxsidebar { + display: none; + } + + div.document { + width: 100%; + + } + + div.documentwrapper { + margin-left: 0; + margin-top: 0; + margin-right: 0; + margin-bottom: 0; + } + + div.bodywrapper { + margin-top: 0; + margin-right: 0; + margin-bottom: 0; + margin-left: 0; + } + + ul { + margin-left: 0; + } + + li > ul { + /* Matches the 30px from the "ul, ol" selector above */ + margin-left: 30px; + } + + .document { + width: auto; + } + + .footer { + width: auto; + } + + .bodywrapper { + margin: 0; + } + + .footer { + width: auto; + } + + .github { + display: none; + } + + + +} + + + +@media screen and (max-width: 875px) { + + body { + margin: 0; + padding: 20px 30px; + } + + div.documentwrapper { + float: none; + background: {{ theme_base_bg }}; + } + + div.sphinxsidebar { + display: block; + float: none; + width: 102.5%; + {%- if theme_fixed_sidebar|lower == 'true' %} + margin: -20px -30px 20px -30px; + {%- else %} + margin: 50px -30px -20px -30px; + {%- endif %} + padding: 10px 20px; + background: {{ theme_narrow_sidebar_bg }}; + color: {{ theme_narrow_sidebar_fg }}; + } + + div.sphinxsidebar h3, div.sphinxsidebar h4, div.sphinxsidebar p, + div.sphinxsidebar h3 a { + color: {{ theme_base_bg }}; + } + + div.sphinxsidebar a { + color: {{ theme_narrow_sidebar_link }}; + } + + div.sphinxsidebar p.logo { + display: none; + } + + div.document { + width: 100%; + margin: 0; + } + + div.footer { + display: none; + } + + div.bodywrapper { + margin: 0; + } + + div.body { + min-height: 0; + padding: 0; + } + + .rtd_doc_footer { + display: none; + } + + .document { + width: auto; + } + + .footer { + width: auto; + } + + .footer { + width: auto; + } + + .github { + display: none; + } +} + +{%- if theme_fixed_sidebar|lower == 'true' %} +@media screen and (min-width: 876px) { + div.sphinxsidebar { + position: fixed; + margin-left: 0; + } +} +{%- endif %} + + +/* misc. */ + +.revsys-inline { + display: none!important; +} + +/* Hide ugly table cell borders in ..bibliography:: directive output */ +table.docutils.citation, table.docutils.citation td, table.docutils.citation th { + border: none; + /* Below needed in some edge cases; if not applied, bottom shadows appear */ + -moz-box-shadow: none; + -webkit-box-shadow: none; + box-shadow: none; +} + + +/* relbar */ + +.related { + line-height: 30px; + width: 100%; + font-size: 0.9rem; +} + +.related.top { + border-bottom: 1px solid {{ theme_relbar_border }}; + margin-bottom: 20px; +} + +.related.bottom { + border-top: 1px solid {{ theme_relbar_border }}; +} + +.related ul { + padding: 0; + margin: 0; + list-style: none; +} + +.related li { + display: inline; +} + +nav#rellinks { + float: right; +} + +nav#rellinks li+li:before { + content: "|"; +} + +nav#breadcrumbs li+li:before { + content: "\00BB"; +} + +/* Hide certain items when printing */ +@media print { + div.related { + display: none; + } +} diff --git a/alabaster/static/custom.css b/alabaster/static/custom.css new file mode 100644 index 0000000..2a924f1 --- /dev/null +++ b/alabaster/static/custom.css @@ -0,0 +1 @@ +/* This file intentionally left blank. */ diff --git a/alabaster/support.py b/alabaster/support.py new file mode 100644 index 0000000..3b2ce04 --- /dev/null +++ b/alabaster/support.py @@ -0,0 +1,89 @@ +from pygments.style import Style +from pygments.token import ( + Comment, + Error, + Generic, + Keyword, + Literal, + Name, + Number, + Operator, + Other, + Punctuation, + String, + Whitespace, +) + + +# Originally based on FlaskyStyle which was based on 'tango'. +class Alabaster(Style): + background_color = "#f8f8f8" # doesn't seem to override CSS 'pre' styling? + default_style = "" + + styles = { + # No corresponding class for the following: + # Text: "", # class: '' + Whitespace: "#f8f8f8", # class: 'w' + Error: "#a40000 border:#ef2929", # class: 'err' + Other: "#000000", # class 'x' + Comment: "italic #8f5902", # class: 'c' + Comment.Preproc: "noitalic", # class: 'cp' + Keyword: "bold #004461", # class: 'k' + Keyword.Constant: "bold #004461", # class: 'kc' + Keyword.Declaration: "bold #004461", # class: 'kd' + Keyword.Namespace: "bold #004461", # class: 'kn' + Keyword.Pseudo: "bold #004461", # class: 'kp' + Keyword.Reserved: "bold #004461", # class: 'kr' + Keyword.Type: "bold #004461", # class: 'kt' + Operator: "#582800", # class: 'o' + Operator.Word: "bold #004461", # class: 'ow' - like keywords + Punctuation: "bold #000000", # class: 'p' + # because special names such as Name.Class, Name.Function, etc. + # are not recognized as such later in the parsing, we choose them + # to look the same as ordinary variables. + Name: "#000000", # class: 'n' + Name.Attribute: "#c4a000", # class: 'na' - to be revised + Name.Builtin: "#004461", # class: 'nb' + Name.Builtin.Pseudo: "#3465a4", # class: 'bp' + Name.Class: "#000000", # class: 'nc' - to be revised + Name.Constant: "#000000", # class: 'no' - to be revised + Name.Decorator: "#888", # class: 'nd' - to be revised + Name.Entity: "#ce5c00", # class: 'ni' + Name.Exception: "bold #cc0000", # class: 'ne' + Name.Function: "#000000", # class: 'nf' + Name.Property: "#000000", # class: 'py' + Name.Label: "#f57900", # class: 'nl' + Name.Namespace: "#000000", # class: 'nn' - to be revised + Name.Other: "#000000", # class: 'nx' + Name.Tag: "bold #004461", # class: 'nt' - like a keyword + Name.Variable: "#000000", # class: 'nv' - to be revised + Name.Variable.Class: "#000000", # class: 'vc' - to be revised + Name.Variable.Global: "#000000", # class: 'vg' - to be revised + Name.Variable.Instance: "#000000", # class: 'vi' - to be revised + Number: "#990000", # class: 'm' + Literal: "#000000", # class: 'l' + Literal.Date: "#000000", # class: 'ld' + String: "#4e9a06", # class: 's' + String.Backtick: "#4e9a06", # class: 'sb' + String.Char: "#4e9a06", # class: 'sc' + String.Doc: "italic #8f5902", # class: 'sd' - like a comment + String.Double: "#4e9a06", # class: 's2' + String.Escape: "#4e9a06", # class: 'se' + String.Heredoc: "#4e9a06", # class: 'sh' + String.Interpol: "#4e9a06", # class: 'si' + String.Other: "#4e9a06", # class: 'sx' + String.Regex: "#4e9a06", # class: 'sr' + String.Single: "#4e9a06", # class: 's1' + String.Symbol: "#4e9a06", # class: 'ss' + Generic: "#000000", # class: 'g' + Generic.Deleted: "#a40000", # class: 'gd' + Generic.Emph: "italic #000000", # class: 'ge' + Generic.Error: "#ef2929", # class: 'gr' + Generic.Heading: "bold #000080", # class: 'gh' + Generic.Inserted: "#00A000", # class: 'gi' + Generic.Output: "#888", # class: 'go' + Generic.Prompt: "#745334", # class: 'gp' + Generic.Strong: "bold #000000", # class: 'gs' + Generic.Subheading: "bold #800080", # class: 'gu' + Generic.Traceback: "bold #a40000", # class: 'gt' + } diff --git a/alabaster/theme.conf b/alabaster/theme.conf new file mode 100644 index 0000000..e85049e --- /dev/null +++ b/alabaster/theme.conf @@ -0,0 +1,132 @@ +[theme] +inherit = basic +stylesheet = alabaster.css +sidebars = about.html, navigation.html, relations.html, searchbox.html, donate.html +pygments_style = alabaster.support.Alabaster + +[options] +body_min_width = inherit +analytics_id = +badge_branch = master +canonical_url = +codecov_button = false +description = +description_font_style = normal +donate_url = +extra_nav_links = +fixed_sidebar = false +github_banner = false +github_button = true +github_count = true +github_repo = +github_type = watch +github_user = +gittip_user = +gratipay_user = +logo = +logo_name = false +logo_text_align = left +opencollective = +opencollective_button_color = white +page_width = 940px +relbar_border = +show_powered_by = true +show_related = false +show_relbar_bottom = +show_relbar_top = +show_relbars = false +sidebar_collapse = true +sidebar_includehidden = true +sidebar_width = 220px +tidelift_url = +touch_icon = +travis_button = false + +gray_1 = #444 +gray_2 = #EEE +gray_3 = #AAA + +pink_1 = #FCC +pink_2 = #FAA +pink_3 = #D52C2C + +base_bg = #fff +base_text = #000 +hr_border = #B1B4B6 +body_bg = +body_text = #3E4349 +body_text_align = left +footer_text = #888 +link = #004B6B +link_hover = #6D4100 +sidebar_header = +sidebar_text = #555 +sidebar_link = +sidebar_link_underscore = #999 +sidebar_search_button = #CCC +sidebar_list = #000 +sidebar_hr = +anchor = #DDD +anchor_hover_fg = +anchor_hover_bg = #EAEAEA +table_border = #888 +shadow = + +# Admonition options +## basic level +admonition_bg = +admonition_border = #CCC +note_bg = +note_border = #CCC +seealso_bg = +seealso_border = #CCC + +## critical level +danger_bg = +danger_border = +danger_shadow = +error_bg = +error_border = +error_shadow = + +## normal level +tip_bg = +tip_border = #CCC +hint_bg = +hint_border = #CCC +important_bg = +important_border = #CCC + +## warning level +caution_bg = +caution_border = +attention_bg = +attention_border = +warn_bg = +warn_border = + +topic_bg = +code_highlight_bg = +highlight_bg = #FAF3E8 +xref_border = #fff +xref_bg = #FBFBFB +admonition_xref_border = #fafafa +admonition_xref_bg = +footnote_bg = #FDFDFD +footnote_border = +pre_bg = +narrow_sidebar_bg = #333 +narrow_sidebar_fg = #FFF +narrow_sidebar_link = +font_size = 17px +caption_font_size = inherit +viewcode_target_bg = #ffd +code_bg = #ecf0f3 +code_text = #222 +code_hover = #EEE +code_font_size = 0.9em +code_font_family = 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace +font_family = Georgia, serif +head_font_family = +caption_font_family = inherit +code_highlight = #FFC diff --git a/docs/changelog.rst b/docs/changelog.rst new file mode 100644 index 0000000..2cadad2 --- /dev/null +++ b/docs/changelog.rst @@ -0,0 +1,361 @@ +========= +Changelog +========= + +Next release (in development) +----------------------------- + +:git_tag:`0.7.16` -- 2024-01-10 +------------------------------- + +- :bug:`215` Do not display ``logo_name`` if it is set to ``False``. + +:git_tag:`0.7.15` -- 2024-01-08 +------------------------------- + +- :feature:`213` Allow an arbitrary string in the ``logo_name`` option. +- :feature:`114` Improved sidebar CSS styles. +- :issue:`178` Deprecated ``canonical_url`` in favor of ``html_baseurl``. +- :bug:`200` Removed duplicate ``<meta name="viewport" ... />`` tag. +- :bug:`188` Removed underline from whitespace. +- :bug:`164` Removed ``type="text/javascript"`` from <script> elements. +- :bug:`161` Replaced ``©`` with unicode decimal code entity ``#169;``. + +:git_tag:`0.7.14` -- 2024-01-08 +------------------------------- + +- Dropped support for Python 3.8 and earlier. +- Dropped support for Sphinx 3.3 and earlier. +- :issue:`198` Fix horizontal scrolling on mobile. +- :issue:`206` Properly support the ``html_support_sphinx`` config value. +- :issue:`211` Fix the GitHub 'forkme' banner. +- Added ``alabaster_version_info`` to the HTML template context. +- Declare support for Python 3.13. +- Adopt the Ruff linter and formatter. +- Migrate from CircleCI to GitHub Actions. + +:git_tag:`0.7.13` -- 2023-01-13 +------------------------------- + +- Modernized the project: s/Travis/Circle/ for CI, + README badges, ``setup.cfg`` removal, metadata refresh, etc. +- Dropped support for Python 2 and Python <3.6. This + includes various minor updates to work correctly with modern versions of + Sphinx (1.6 at the very least). Thanks to Adam Turner for a pile of patches + here. + + .. warning:: + This change is backwards incompatible if you're on an old Python version. + +- Tweak CSS somewhat for compatibility with modern + Sphinx versions' base stylesheet. + +:git_tag:`0.7.12` -- 2018-10-02 +------------------------------- + +- On some browsers/platforms, 'badge'-style sidebar elements were + displaying dotted underlines. This was unintentional and explicit styling has + been added to remove them. Credit to Steven Loria. +- Reorganize the :doc:`customization page + </customization>` to break up the now rather long list of "variables and + feature toggles" into additional sections; includes alphabetizing those + lists, to make it a bit easier to find docs for a specific setting. +- :feature:`132` (partially via :issue:`143`) Add a generic donation + badge/url option (visually powered by https://shields.io/) as well as a + service-specific donation option for `OpenCollective + <https://opencollective.com>`_. + + We expect this to be followed-up on later with more service-specific options + for services like Patreon. Thanks to Melanie Crutchfield for the report and + Steven Loria for the initial patch. +- :bug:`128` Remove Gittip/Gratipay output from the ``donate.html`` sidebar + component, since the actual service has been insolvent since 2017. The + configuration options remain in place for the time being (to avoid breaking + backwards compatibility) but no longer do anything. Thanks to Joe Alcorn for + the report / original patchset. + + .. note:: + See the changelog entry for ``#132``, which re-introduces a more generic + donation sidebar framework. + +- :feature:`142` Add a ``tidelift_url`` option, which when set + (default is ``None``/unset) adds a small text snippet to the + ``donate.html`` sidebar component, linking to the given URL string. Thanks + to Steven Loria for the patch. +- :bug:`141` Fix a typo in the code-block font family, which incorrectly + specified ``Deja Vu Sans Mono`` instead of ``DejaVu Sans Mono``. This would + primarily impact systems lacking the first two fonts (``Consolas`` and + ``Menlo``) such as Linux desktops. Thanks to Ilya Trukhanov for catch & + patch. + +:git_tag:`0.7.11` -- 2018-06-18 +------------------------------- + +- :bug:`73` Clean up some problematic font issues: + + - Remove the outright broken Goudy Old Style, plus other mostly Adobe-only + fonts, from the ``font_family`` config setting; it is now simply ``Georgia, + serif`` which is what the majority of users were rendering anyways. + - Clear out the default value of ``head_font_family`` (which contained + ``Garamond``, a nice but also Adobe only font) + - Set ``head_font_family`` so it falls back to the value of ``font_family`` + unless a user has explicitly set it themselves. + + .. note:: + You can always go back to the old values by :ref:`explicitly setting + <theme-options>` ``font_family`` and/or ``head_font_family`` in your + ``conf.py``'s ``html_theme_options``, e.g.: + + .. code-block:: python + + html_theme_options = { + 'description': 'My awesome project', + 'font_family': "goudy old style, minion pro, bell mt, Georgia, Hiragino Mincho Pro, serif", + } + + .. warning:: + Depending on individual viewers' systems, this change *may* be **visually** + backwards incompatible if you were not already overriding the font + settings and those users had the fonts in question (which are not default + on most systems). + + As seen in the note above, you can **always** override the new defaults to + go back to the old behavior, using your config file. + +- :feature:`18` (via :issue:`101`) Add optional *next* and + *previous* links at the top and bottom of page content. Use theme option + ``show_relbars`` to enable these. Credit: William Minchin. +- Miscellaneous project maintenance updates such as + adding to Travis CI and enforcing the use of ``flake8``. +- :feature:`110` Add ``badge_branch`` option allowing + configurability of which specific Git branch the Travis, Codecov, etc buttons + default to. Credit: ``@TitanSnow``. +- :feature:`111` Add setuptools-level entrypoint for improved theme + distribution compatibility. Thanks to Aaron Carlisle for the patch. + +:git_tag:`0.7.10` -- 2017-02-28 +------------------------------- + +- :bug:`32` Update styling of various block-level elements such as admonitions + (``.. note::``, ``.. warning::``, etc) and code blocks (``.. code::``) so + they are no longer 'dedented' outside the main column of text they're + embedded in. This is both a stylistic change and a bugfix, since e.g. nesting + code blocks *within* note blocks looks actively broken. Thanks to Takayuki + Shimizukawa for the report. +- :bug:`96` ``admonition_xref`` had a template typo preventing it from + receiving styling; this has been fixed. Credit: Kenzie Togami. +- :bug:`95` Independently ran across + `sphinx-doc/sphinx#3276 <https://github.com/sphinx-doc/sphinx/issues/3276>`_, + namely that parameter lists become squashed together if one is running on + Sphinx 1.4.x. While that fix was merged in Sphinx itself, we felt it prudent + to include it in our own stylesheet as well, for immediate relief. + +:git_tag:`0.7.9` -- 2016-07-25 +------------------------------ + +- :feature:`6` (and :issue:`70`, both via :issue:`84`) Make all remaining + hardcoded style colors configurable, plus related cleanup (such as improving + differentiation of some admonition blocks such as ``warn`` and ``note``, + ensuring generic admonitions are left untouched, etc). Credit: + ``@ShadowKyogre``. +- :feature:`83` Expose Sphinx's toctree ``collapse`` option as the new + ``sidebar_collapse`` config option. Credit: Eric Holscher. +- :feature:`80` Add support for ``<link rel="canonical">`` (i.e. canonical + URLs). Thanks to Ben Gamari for the patch. +- :feature:`7` Generate real documentation site, both because the README is + just too big now, and so we can `eat our own dog food + <https://en.wikipedia.org/wiki/Eating_your_own_dog_food>`_. + +:git_tag:`0.7.8` -- 2016-05-05 +------------------------------ + +- #51 (via #67): Hide Github button if ``github_user`` and ``github_repo`` + aren't set. This is necessary since ``github_button`` defaults to True. + Thanks to Sam Whited for the report & Dmitry Shachnev for the patch. +- #75: Use SVG version of the Travis-CI button. Thanks to Sebastian Wiesner for + the patch. +- #41: Update the Github buttons to use a newer linked image & change the link + to their docs. Thanks to Tomi Hukkalainen. +- #45 (via #46) Tweak styling of nested bullet lists to prevent an issue where + they all collapse to the same indent level when viewed on smaller display + sizes. Thanks to Bram Geron for catch & patch, and to Jochen Kupperschmidt + for review/discussion. +- #44 (partial; via #57) Add an opt-in fixed sidebar behavior for users who + prefer a sidebar that never scrolls out of view. Credit: Joe Cross. +- #61: Set a small-but-nonzero footnote width to work around a common browser + display bug. Thanks to Konstantin Molchanov for catch & patch. +- #64: Add config options for font size and caption font size/family. Credit: + Marçal Solà. +- #78: Add custom stylesheet support. (This release will thus be the last to + merge simplistic style tweaks as feature toggles - only thorny CSS issues or + actual template-related changes will be merged afterwards.) +- #65: Wrap the sidebar's "Navigation" header in Sphinx's translation helper so + it gets translated if possible. Thanks to ``@uralbash``. +- #77: Fix image link styling to remove a bottom border which appears in some + situations. Thanks to Eric Holscher for the patch & ``@barbara-sfx`` for the + report. + +:git_tag:`0.7.7` -- 2015-12-21 +------------------------------ + +- Add some ``margin-bottom`` to ``table.field-list p`` so field lists (e.g. + Python function parameter lists in docstrings) written as multiple + paragraphs, look like actual paragraphs instead of all globbing together. +- Fix incorrect notes in README re: renamed ``github_button_*`` options - the + ``button_`` was dropped but docs did not reflect this. Thanks to Nik Nyby. +- Fix ``sidebar_hr`` setting - stylesheet wasn't correctly referencing the + right variable name. Thanks to Jannis Leidel. +- Allow configuring body text-align via ``body_text_align``. Credit to Marçal + Solà. +- Fix a handful of mismatched/unclosed HTML tags in the templates. Thanks to + Marvin Pinto for catch & patch. +- Add `Codecov <https://about.codecov.io>`_ badge support to sidebar. + +:git_tag:`0.7.6` -- 2015-06-22 +------------------------------ + +- Update how ``setup.py`` handles the ``README.rst`` file - load it explicitly + as UTF-8 so the changelog containing non-ASCII characters doesn't generate + ``UnicodeDecodeError`` in terminal environments whose default encoding is not + UTF-8 or other Unicode-compatible encodings. Thanks to Arun Persaud for the + report and Max Tepkeev for the suggested fix. +- Fix left-margin & padding styling for code blocks within list-item elements, + making them consistent with earlier changes applied to top-level code blocks. +- Expose page & sidebar widths as theme options ``page_width`` and + ``sidebar_width``. Their defaults are the same as the previously static + values. + +:git_tag:`0.7.5` -- 2015-06-15 +------------------------------ + +- Honor Sphinx's core ``html_show_copyright`` option when rendering page + footer. Thanks to Marcin Wojdyr for the report. +- Pre-history versions of Alabaster attempted to remove the "related" + sub-navigation (typically found as next/previous links in other themes) but + this didn't work right for mobile-oriented styling. + + This has been fixed by (re-)adding an improved sidebar nav element for these + links and making its display controllable via the new ``show_related`` theme + option (which defaults to ``false`` for backwards compatibility). + + .. note:: + To enable the related-links nav, you'll need to set ``show_related`` to + ``true`` **and** add ``relations.html`` to your ``html_sidebars`` (we've + updated the example config in this README to indicate this for new + installs). + + Thanks to Tomi Pieviläinen for the bug report. +- Update the "Fork me on Github" banner image to use an ``https://`` URI so + sites hosted over HTTPS don't encounter mixed-content errors. Thanks to + ``@nikolas`` for the patch. +- Remove an orphaned ``</li>`` from the footer 'show source' section. Credit to + Marcin Wojdyr. + +:git_tag:`0.7.4` -- 2015-05-03 +------------------------------ + +- Add ``code_highlight`` option (which includes general fixes to styling of + code blocks containing highlighted lines). Thanks to Steven Loria. + +:git_tag:`0.7.3` -- 2015-03-20 +------------------------------ + +- Hide ``shadow`` related styles on bibliography elements, in addition to the + earlier change re: ``border``. Thanks again to Philippe Dessus. + +:git_tag:`0.7.2` -- 2015-03-10 +------------------------------ + +- Updated CSS stylesheets to apply monospace styling to both ``tt`` and + ``code`` elements, instead of just to ``tt``. This addresses a change in HTML + generation in Sphinx 1.3 while retaining support for Sphinx 1.2. Thanks to + Eric Holscher for the heads up. + +:git_tag:`0.7.1` -- 2015-02-27 +------------------------------ + +- Finally add a changelog. To the README, for now, because a full doc site + isn't worthwhile just yet. +- Allow configuring a custom Github banner image (instead of simply toggling a + default on or off). Thanks to Nicola Iarocci for the original patch. +- Explicitly note Python version support in the README and ``setup.py``. +- Update Github button image link to use the newly-available HTTPS version of + the URL; this helps prevent errors on doc pages served via HTTPS. Thanks to + Gustavo Narea for the report. +- Add control over the font size & family of code blocks. Credit to Steven + Loria. +- Allow control over font family of body text and headings. Thanks to Georg + Brandl. +- Stylize ``.. seealso::`` blocks same as ``.. note::`` blocks for + consistency's sake (previously, ``.. seealso::`` used the Sphinx default + styling, which clashed). We may update these again later but for now, this is + an improvement! Thanks again to Steven Loria. +- Allow control over CSS ``font-style`` for the site description/tagline + element. Credit: Steven Loria. +- Add styling to disable default cell borders on ``.. bibliography::`` + directives' output. Thanks to Philippe Dessus for the report. + +:git_tag:`0.6.2` -- 2014-11-25 +------------------------------ + +- Make ``.. warn::`` blocks have a pink background (instead of having no + background, which was apparently an oversight of the themes Alabaster is + based on) and also make that color configurable. + +:git_tag:`0.6.1` -- 2014-09-04 +------------------------------ + +- Update Gittip support to acknowledge the service's rename to Gratipay. + +:git_tag:`0.6.0` -- 2014-04-17 +------------------------------ + +- Allow hiding the 'powered by' section of the footer. +- Fix outdated name in ``setup.py`` URL field. + +:git_tag:`0.5.1` -- 2014-04-15 +------------------------------ + +- Fix a bug in the new Travis support, re: its default value. + +:git_tag:`0.5.0` -- 2014-04-09 +------------------------------ + +- Add support for sidebar Travis status buttons. + +:git_tag:`0.4.1` -- 2014-04-06 +------------------------------ + +- Fix an inaccuracy in the description of ``logo_text_align``. +- Update logo & text styling to be more sensible. + +:git_tag:`0.4.0` -- 2014-04-06 +------------------------------ + +- Add an option to allow un-hiding one's toctree. + +:git_tag:`0.3.1` -- 2014-03-13 +------------------------------ + +- Improved Python 3 compatibility. +- Update styling of changelog pages generated by `bitprophet/releases + <https://github.com/bitprophet/releases>`_. + +:git_tag:`0.3.0` -- 2014-02-03 +------------------------------ + +- Display Alabaster version in footers alongside Sphinx version (necessitating + use of a mini Sphinx extension) plus other footer tweaks. + +:git_tag:`0.2.0` -- 2014-01-28 +------------------------------ + +- Allow control of logo replacement text's alignment. +- Add customized navigation sidebar element. +- Tweak page margins a bit. +- Add a 3rd level of medium-gray to the stylesheet & apply in a few places. + +:git_tag:`0.1.0` -- 2013-12-31 +------------------------------ + +- First tagged/PyPI'd version. diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..21bbb5f --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,38 @@ +from datetime import datetime + +extensions = [ + "sphinx.ext.extlinks", +] +templates_path = ["_templates"] +source_suffix = ".rst" +master_doc = "index" + +project = "Alabaster" +copyright = f"{datetime.now().year} Jeff Forcier" + +exclude_patterns = ["_build"] + +extlinks = { + "git_tag": ("https://github.com/sphinx-doc/alabaster/tree/%s", "%s"), + "bug": ("https://github.com/sphinx-doc/alabaster/issues/%s", "#%s"), + "feature": ("https://github.com/sphinx-doc/alabaster/issues/%s", "#%s"), + "issue": ("https://github.com/sphinx-doc/alabaster/issues/%s", "#%s"), +} + +html_theme = "alabaster" +html_sidebars = { + "**": [ + "about.html", + "navigation.html", + "relations.html", + "searchbox.html", + "donate.html", + ] +} +html_theme_options = { + "description": "A light, configurable Sphinx theme", + "github_user": "sphinx-doc", + "github_repo": "alabaster", + "fixed_sidebar": True, + "tidelift_url": "https://tidelift.com/subscription/pkg/pypi-alabaster?utm_source=pypi-alabaster&utm_medium=referral&utm_campaign=docs", # noqa +} diff --git a/docs/customization.rst b/docs/customization.rst new file mode 100644 index 0000000..fa2a844 --- /dev/null +++ b/docs/customization.rst @@ -0,0 +1,272 @@ +============= +Customization +============= + +Alabaster's behavior & style can be customized in multiple ways: + +* Various template-level or nontrivial-style settings can be configured via + your ``conf.py`` in ``html_theme_options``; see :ref:`theme-options`. +* As of Alabaster 0.7.8, you can provide your own CSS stylesheet overrides via + a :ref:`custom stylesheet <custom-stylesheet>`. This is suitable for changes + that only need minor CSS modifications. + + .. note:: + Some theme options implemented prior to 0.7.8 would have been more suitable + as local custom stylesheet overrides. Therefore: + + * We no longer accept feature requests which are more appropriately solved + by using this functionality instead. + * In future backwards-incompatible versions we may deprecate some of those + options; as such we highly recommend leveraging the custom stylesheet + whenever possible, even if an option is present below. + + * When in doubt, simply check `the built-in stylesheet's template + <https://github.com/sphinx-doc/alabaster/blob/master/alabaster/static/alabaster.css_t>`_ + to see whether the option you're looking at is a basic variable + insertion or something more complicated.) + + +.. _custom-stylesheet: + +Custom stylesheet +================= + +If you need to modify Alabaster's default CSS styles in a way not covered by +the theme options from the next section, you may provide a custom CSS +stylesheet as follows: + +* Create a file named ``custom.css`` anywhere you prefer (typically + ``_static/``, but this is solely convention) containing your desired + overrides to the CSS found in Alabaster's ``static/alabaster_css_t``. +* Set the core Sphinx option `html_static_path + <https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_static_path>`_ + to either that file's path, or the directory it lives within. + + +.. _theme-options: + +Theme options +============= + +Alabaster's primary configuration route is the ``html_theme_options`` variable, +set in ``conf.py`` alongside the rest, e.g.: + +.. code-block:: python + + html_theme_options = { + 'logo': 'logo.png', + 'github_user': 'sphinx-doc', + 'github_repo': 'alabaster', + } + +The following subsections detail available such options, including notes about +behavior. Default values can be found by viewing `theme.conf +<https://github.com/sphinx-doc/alabaster/blob/master/alabaster/theme.conf>`_ +directly. + +Basics +------ + +Settings related to text display, logo, etc. + +* ``body_text_align``: Which CSS ``text-align`` value to use for body text + (if there is any.) +* ``canonical_url``: **Deprecated**, please use the html_baseurl_ Sphinx option instead. + If set, is used as the base URL (set before the relative + path/pagename) for a ``<link rel="canonical">`` `canonical URL + <https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls>`_ header tag. + + .. note:: This value must end with a trailing slash. + + .. _html_baseurl: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_baseurl + +* ``description``: Text blurb about your project, to appear under the logo. +* ``description_font_style``: Which CSS ``font-style`` to use for description + text. +* ``fixed_sidebar``: Makes the sidebar 'fixed' or pinned in place, so that the + main body of the page scrolls but the sidebar remains visible. (Applies only + to desktop window sizes; the mobile view is unaffected.) +* ``logo``: Relative path (from ``$PROJECT/_static/``) to a logo image, which + will appear in the upper left corner above the name of the project. + + * If ``logo`` is not set, your ``project`` name setting (from the top + level Sphinx config) will be used in a text header instead. This + preserves a link back to your homepage from inner doc pages. + +* ``logo_name``: Set to ``True`` to insert your site's ``project`` name + under the logo image as text, or to any string to include arbitrary text. + Useful if your logo doesn't include the project name itself. +* ``logo_text_align``: Which CSS ``text-align`` value to use for logo text + (if there is any.) +* ``page_width``: CSS width specifier controlling default content/page width. +* ``sidebar_width``: CSS width specifier controlling default sidebar width. +* ``touch_icon``: Path to an image (as with ``logo``, relative to + ``$PROJECT/_static/``) to be used for an iOS application icon, for when + pages are saved to an iOS device's home screen via Safari. + +Service links and badges +------------------------ + +Third-party services (GitHub, Travis-CI, etc etc) and related badges or +banners. + +* ``analytics_id``: Set to your `Google Analytics + <https://marketingplatform.google.com/about/analytics/>`_ ID (e.g. ``UA-#######-##``) to enable + tracking. +* ``badge_branch``: Set which branch is used in the Travis, CodeCov, etc + badges. +* ``codecov_button``: ``true``, ``false`` or a Github-style ``"account/repo"`` + string - used to display a `Codecov <https://about.codecov.io>`_ build status + button in the sidebar. If ``true``, uses your ``github_(user|repo)`` + settings. +* ``donate_url``: URL to generic/arbitrary donation service; causes display of + a basic 'Donate' badge/shield (from https://shields.io) linking to the URL + given. +* ``github_banner``: ``true`` or ``false`` - whether to apply a 'Fork me on + Github' banner in the top right corner of the page. + + * If ``true``, requires that you set ``github_user`` and ``github_repo`` + (see below). + * May also submit a string file path (as with ``logo``, relative to + ``$PROJECT/_static/``) to be used as the banner image instead of the + default. + +* ``github_button``: ``true`` or ``false`` - whether to link to your Github. + + * If ``true``, requires that you set ``github_user`` and ``github_repo``. + * There are also the ``github_type`` and ``github_count`` options, which + behave as described in `Github Buttons' documentation + <https://ghbtns.com>`_. + +* ``github_repo``: Used by ``github_button`` and ``github_banner`` (see above); + does nothing if both of those are set to ``false``. +* ``github_user``: Used by ``github_button`` and ``github_banner`` (see above); + does nothing if both of those are set to ``false``. +* ``gittip_user`` / ``gratipay_user``: **Deprecated**, as that service is no + longer running. These options still exist (removing them would break + backwards compatibility; Sphinx errors when users try to set nonexistent + options) but they no longer do anything. +* ``tidelift_url``: Set this to your `Tidelift <https://tidelift.com/>`_ + project URL if you want a "Professional support" section in your sidebar. + + - If copying the URL straight from Tidelift's site, you'll probably want to + change ``&utm_campaign=readme`` to ``&utm_campaign=docs``. + +* ``travis_button``: ``true``, ``false`` or a Github-style ``"account/repo"`` + string - used to display a `Travis-CI <https://travis-ci.org>`_ build status + button in the sidebar. If ``true``, uses your ``github_(user|repo)`` + settings. + +Non-service sidebar control +--------------------------- + +Sidebar-related options that aren't directly related to service links. + +* ``extra_nav_links``: Dictionary mapping link names to link targets; these + will be added in a UL below the main sidebar navigation (provided you've + enabled ``navigation.html`` via the ``html_sidebars`` option; see + :doc:`installation`.) Useful for static links outside your Sphinx doctree. +* ``show_related``: Boolean controlling whether the sidebar + 'next/previous/related' secondary navigation elements are hidden or + displayed. Defaults to ``false`` since on many sites these elements are + superfluous. + + .. note:: + This is distinct from the ``show_relbars`` setting found in the + header/footer options; the two visual components are orthogonal and may be + enabled/disabled independently of one another. + +* ``sidebar_collapse``: Boolean determining whether all TOC entries that + are not ancestors of the current page are collapsed. + You can read more about this in the Sphinx toctree + `docs <https://www.sphinx-doc.org/en/master/development/templating.html#toctree>`_. +* ``sidebar_includehidden``: Boolean determining whether the TOC sidebar + should include hidden Sphinx toctree elements. Defaults to ``true`` so you + can use ``:hidden:`` in your index page's root toctree & avoid having 2x + copies of your navigation on your landing page. + +Header/footer options +--------------------- + +Which elements should appear in the header and/or footer, or modification of +same. + +* ``show_powered_by``: Boolean controlling display of the ``Powered by + Sphinx N.N.N. & Alabaster M.M.M`` section of the footer. When ``true``, is + displayed next to the copyright information; when ``false``, is hidden. + + .. deprecated:: 0.17.14 + Set ``html_show_sphinx`` to ``True`` or ``False`` in ``conf.py`` instead. + +* ``show_relbars``: ``true`` or ``false`` - used to display *next* and + *previous* links above and below the main page content. If you only want to + display one, this setting can be further overridden through the + ``show_relbar_top`` and ``show_relbar_bottom`` settings. + + .. note:: + This is distinct from the ``show_related`` setting found in the sidebar + control options, which controls sidebar-only next/previous links. + +Style colors +------------ + +These should be fully qualified CSS color specifiers such as ``#004B6B`` or +``#444``. The first few items in the list are "global" colors used as defaults +for many of the others; update these to make sweeping changes to the +colorscheme. The more granular settings can be used to override as needed. + +* ``anchor``: Foreground color of section anchor links (the 'paragraph' + symbol that shows up when you mouseover page section headers.) +* ``anchor_hover_bg``: Background color of ``anchor`` text. +* ``anchor_hover_fg``: Foreground color of section anchor links (as above) + when moused over. +* ``body_text``: Main content text. +* ``code_highlight``: Color of highlight when using ``:emphasize-lines:`` in a code block. +* ``footer_text``: Footer text (includes links.) +* ``footnote_bg``: Background of footnote blocks. +* ``footnote_border``: Border of same. +* ``gray_1``: Dark gray. +* ``gray_2``: Light gray. +* ``gray_3``: Medium gray. +* ``link_hover``: Body links, hovered. +* ``link``: Non-hovered body links. +* ``narrow_sidebar_bg``: Background of 'sidebar' when narrow window forces + it to the bottom of the page. +* ``narrow_sidebar_fg``: Text color of same. +* ``narrow_sidebar_link``: Link color of same. +* ``note_bg``: Background of ``.. note::`` blocks. +* ``note_border``: Border of same. +* ``pink_1``: Light pink. +* ``pink_2``: Medium pink. +* ``pre_bg``: Background of preformatted text blocks (including code + snippets.) +* ``relbar_border``: Color of border between bar holding *next* and *previous* + links, and the rest of the page content. +* ``seealso_bg``: Background of ``.. seealso::`` blocks. +* ``seealso_border``: Border of same. +* ``sidebar_header``: Sidebar headers. +* ``sidebar_hr``: Color of sidebar horizontal rule dividers. +* ``sidebar_link``: Sidebar links (there is no hover variant.) Applies to + both header & text links. +* ``sidebar_list``: Foreground color of sidebar list bullets & unlinked text. +* ``sidebar_link_underscore``: Sidebar links' underline (technically a + bottom-border). +* ``sidebar_search_button``: Background color of the search field's 'Go' + button. +* ``sidebar_text``: Sidebar paragraph text. +* ``warn_bg``: Background of ``.. warn::`` blocks. +* ``warn_border``: Border of same. + +Fonts +----- + +* ``caption_font_size``: Font size of caption block text. +* ``caption_font_family``: Font family of caption block text. +* ``code_font_size``: Font size of code block text. +* ``code_font_family``: Font family of code block text. Defaults to + ``'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', + monospace``. +* ``font_family``: Font family of body text. +* ``font_size``: Font size of body text. +* ``head_font_family``: Font family of headings. Defaults to ``'Garamond', + 'Georgia', serif``. diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..3ceeaa2 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,49 @@ +========================= +Alabaster: a Sphinx theme +========================= + +.. include:: ../README.rst + +Features +======== + +* Easy ability to install/use as a Python package (tip o' the hat to `Dave & + Eric's sphinx_rtd_theme <https://github.com/readthedocs/sphinx_rtd_theme>`_ for + showing the way); +* Style tweaks compared to the source themes, such as better code-block + alignment, Github button placement, page source link moved to footer, + improved (optional) related-items sidebar item, and many more; +* Many customization hooks, including toggle of various sidebar & footer + components; header/link/etc color control; etc; +* Improved documentation for all customizations (pre-existing & new). + + +Project background +================== + +Alabaster is a modified (with permission) version of `Kenneth Reitz's +<https://www.kennethreitz.org/>`_ `"krTheme" Sphinx theme +<https://github.com/kennethreitz-archive/kr-sphinx-themes>`_ (it's the one used +in his `Requests <https://requests.readthedocs.io/>`_ project). Kenneth's +theme was itself originally based on Armin Ronacher's `Flask +<https://flask.palletsprojects.com/>`_ theme. Many thanks to both for their hard work. + + +Implementation notes +==================== + +* `Fabric #419 <https://github.com/fabric/fabric/issues/419>`_ contains a lot of + general exposition & thoughts as I developed Alabaster, specifically with a + mind towards using it on two nearly identical 'sister' sites (single-version + www 'info' site & versioned API docs site). +* Alabaster includes/requires a tiny Sphinx extension on top of the theme + itself; this is just so we can inject dynamic metadata (like Alabaster's own + version number) into template contexts. It doesn't add any additional + directives or the like, at least not yet. + + +.. toctree:: + :hidden: + :glob: + + * diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..487a1dd --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,67 @@ +============ +Installation +============ + +Alabaster requires **Sphinx 3.4 or newer**, and is included as the default +theme. + +.. note:: + If you distribute your documentation via `Read the Docs + <https://readthedocs.org>`_, you will need to explicitly enable + Alabaster by adding this line to your ``conf.py``: + + .. code-block:: python + + html_theme = 'alabaster' + +To set-up Alabaster, add an explicit ``html_sidebars`` setting so +Alabaster's customized sidebar templates are loaded: + + .. code-block:: python + + html_sidebars = { + '**': [ + 'about.html', + 'navigation.html', + 'relations.html', + 'searchbox.html', + 'donate.html', + ] + } + +That's it! You now have the standard Alabaster theme set up. Read on for more +core configuration concerns, or see :doc:`customization` for feature/style +options. + + +Sidebars +-------- + +Feel free to adjust ``html_sidebars`` as desired - the theme is designed +assuming you'll always have ``about.html`` activated, but otherwise it doesn't +care much. + +* See `the Sphinx docs + <https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_sidebars>`_ for details on + how this setting behaves. +* Alabaster provides ``about.html`` (logo, github button + blurb), + ``donate.html`` (donation/support buttons/links) and ``navigation.html`` (a + more flexible version of the builtin ``localtoc``/``globaltoc`` templates). + ``searchbox.html`` comes with Sphinx itself. + + +.. _static-path: + +Static path for images and/or custom stylesheet +----------------------------------------------- + +If you're using any of the image-related options listed on :doc:`customization` +(``logo`` or ``touch-icon``) or a :ref:`custom stylesheet <custom-stylesheet>`, +you'll also want to tell Sphinx where to get these files from. If so, add a +line like this (changing the path if necessary; see `the Sphinx docs for +'html_static_path' +<https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_static_path>`_) to your ``conf.py``: + +.. code-block:: python + + html_static_path = ['_static'] diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..9ae864f --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ +Sphinx>=3.4 diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..7378ef3 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,58 @@ +[build-system] +requires = ["flit_core>=3.7"] +build-backend = "flit_core.buildapi" + +# project metadata +[project] +name = "alabaster" +description = "A light, configurable Sphinx theme" +readme = "README.rst" +urls.Changelog = "https://alabaster.readthedocs.io/en/latest/changelog.html" +urls.Documentation = "https://alabaster.readthedocs.io/" +urls.Download = "https://pypi.org/project/alabaster/" +urls.Homepage = "https://alabaster.readthedocs.io/" +urls."Issue tracker" = "https://github.com/bitprophet/alabaster/issues" +urls.Source = "https://github.com/sphinx-doc/alabaster" +license.text = "BSD-3-Clause" +requires-python = ">=3.9" + +# Classifiers list: https://pypi.org/classifiers/ +classifiers = [ + "Development Status :: 5 - Production/Stable", + "Framework :: Sphinx", + "Framework :: Sphinx :: Theme", + "Intended Audience :: Developers", + "License :: OSI Approved :: BSD License", + "Operating System :: OS Independent", + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3 :: Only", + "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: 3.13", + "Programming Language :: Python :: Implementation :: CPython", + "Programming Language :: Python :: Implementation :: PyPy", + "Topic :: Documentation", + "Topic :: Documentation :: Sphinx", + "Topic :: Software Development :: Documentation", +] +dependencies = [] +dynamic = ["version"] + +[[project.authors]] +name = "Jeff Forcier" +email = "jeff@bitprophet.org" + +[[project.maintainers]] +name = "The Sphinx Developers" + +[project.entry-points."sphinx.html_themes"] +alabaster = "alabaster" + +[tool.flit.sdist] +include = [ + "LICENSE.rst", + # Documentation + "docs/", +] |