From 85e83e55aec629d503e3645980faa830a9b78c4d Mon Sep 17 00:00:00 2001
From: Daniel Baumann <daniel.baumann@progress-linux.org>
Date: Wed, 5 Jun 2024 18:23:57 +0200
Subject: Adding upstream version 0.7.16.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
---
 docs/changelog.rst     | 361 +++++++++++++++++++++++++++++++++++++++++++++++++
 docs/conf.py           |  38 ++++++
 docs/customization.rst | 272 +++++++++++++++++++++++++++++++++++++
 docs/index.rst         |  49 +++++++
 docs/installation.rst  |  67 +++++++++
 docs/requirements.txt  |   1 +
 6 files changed, 788 insertions(+)
 create mode 100644 docs/changelog.rst
 create mode 100644 docs/conf.py
 create mode 100644 docs/customization.rst
 create mode 100644 docs/index.rst
 create mode 100644 docs/installation.rst
 create mode 100644 docs/requirements.txt

(limited to 'docs')

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 ``&copy;`` 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
-- 
cgit v1.2.3