diff options
Diffstat (limited to 'docs')
| -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 |
6 files changed, 788 insertions, 0 deletions
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 |