From 7993cd00e55d2b21be5726e59f35ba81bce462a2 Mon Sep 17 00:00:00 2001 From: Nikita Marchant Date: Sat, 9 Jan 2021 22:33:33 +0100 Subject: [PATCH] Initial fork commit --- README.md | 27 ++ README.rst | 19 -- {alabaster => alabaster_hotwire}/__init__.py | 6 +- {alabaster => alabaster_hotwire}/_version.py | 0 {alabaster => alabaster_hotwire}/about.html | 0 {alabaster => alabaster_hotwire}/donate.html | 0 {alabaster => alabaster_hotwire}/layout.html | 30 +- .../navigation.html | 0 .../relations.html | 0 .../static/alabaster.css_t | 152 ++++++++-- .../static/custom.css | 0 {alabaster => alabaster_hotwire}/support.py | 2 +- {alabaster => alabaster_hotwire}/theme.conf | 6 +- docs/changelog.rst | 243 ---------------- docs/conf.py | 36 --- docs/customization.rst | 265 ------------------ docs/index.rst | 49 ---- docs/installation.rst | 90 ------ setup.py | 8 +- 19 files changed, 185 insertions(+), 748 deletions(-) create mode 100644 README.md delete mode 100644 README.rst rename {alabaster => alabaster_hotwire}/__init__.py (77%) rename {alabaster => alabaster_hotwire}/_version.py (100%) rename {alabaster => alabaster_hotwire}/about.html (100%) rename {alabaster => alabaster_hotwire}/donate.html (100%) rename {alabaster => alabaster_hotwire}/layout.html (78%) rename {alabaster => alabaster_hotwire}/navigation.html (100%) rename {alabaster => alabaster_hotwire}/relations.html (100%) rename {alabaster => alabaster_hotwire}/static/alabaster.css_t (83%) rename {alabaster => alabaster_hotwire}/static/custom.css (100%) rename {alabaster => alabaster_hotwire}/support.py (99%) rename {alabaster => alabaster_hotwire}/theme.conf (90%) delete mode 100644 docs/changelog.rst delete mode 100644 docs/conf.py delete mode 100644 docs/customization.rst delete mode 100644 docs/index.rst delete mode 100644 docs/installation.rst diff --git a/README.md b/README.md new file mode 100644 index 0000000..76d06f8 --- /dev/null +++ b/README.md @@ -0,0 +1,27 @@ +What is this ? +============== + +Alabaster Hotwire is a fork of [Alabaster](http://alabaster.readthedocs.io), the default Sphinx theme, +quickly modified (hacked ?) to follow the same style as [Hotwire.dev](https://hotwire.dev). + +How to use it for Django Hotwire projects ? +=========================================== + +Change the theme in the `conf.py` file +```python +html_theme = "alabaster_hotwire" +``` + +Then, add this variable to populate the top bar with the following: +```python +html_context = { + 'topbar' : [ + {"url": "https://turbo-django.readthedocs.io/", "name": "Turbo Django", "active": True}, + {"url": "https://django-turbo-response.readthedocs.io/", "name": "Django Turbo Response"}, + {"name": "Stimulus Django"}, + ] +} +``` + +We should try to keep the same like on every documentation website we have so users won't be surprised. +Just change `active` to `True` to match the current repo. diff --git a/README.rst b/README.rst deleted file mode 100644 index 08093fb..0000000 --- a/README.rst +++ /dev/null @@ -1,19 +0,0 @@ -What is Alabaster? -================== - -Alabaster is a visually (c)lean, responsive, configurable theme for the `Sphinx -`_ documentation system. It is Python 2+3 compatible. - -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 -`_, `paramiko.org `_, -`fabfile.org `_ and `pyinvoke.org `_. - -For more documentation, please see http://alabaster.readthedocs.io. - -.. note:: - You can install the development version via ``pip install -e - git+https://github.com/bitprophet/alabaster/#egg=alabaster``. diff --git a/alabaster/__init__.py b/alabaster_hotwire/__init__.py similarity index 77% rename from alabaster/__init__.py rename to alabaster_hotwire/__init__.py index c88b2b5..7f09089 100644 --- a/alabaster/__init__.py +++ b/alabaster_hotwire/__init__.py @@ -1,6 +1,6 @@ import os -from alabaster import _version as version +from alabaster_hotwire import _version as version def get_path(): @@ -12,13 +12,13 @@ def get_path(): def update_context(app, pagename, templatename, context, doctree): - context["alabaster_version"] = version.__version__ + context["alabaster_hotwire_version"] = version.__version__ def setup(app): # add_html_theme is new in Sphinx 1.6+ if hasattr(app, "add_html_theme"): theme_path = os.path.abspath(os.path.dirname(__file__)) - app.add_html_theme("alabaster", theme_path) + app.add_html_theme("alabaster_hotwire", theme_path) app.connect("html-page-context", update_context) return {"version": version.__version__, "parallel_read_safe": True} diff --git a/alabaster/_version.py b/alabaster_hotwire/_version.py similarity index 100% rename from alabaster/_version.py rename to alabaster_hotwire/_version.py diff --git a/alabaster/about.html b/alabaster_hotwire/about.html similarity index 100% rename from alabaster/about.html rename to alabaster_hotwire/about.html diff --git a/alabaster/donate.html b/alabaster_hotwire/donate.html similarity index 100% rename from alabaster/donate.html rename to alabaster_hotwire/donate.html diff --git a/alabaster/layout.html b/alabaster_hotwire/layout.html similarity index 78% rename from alabaster/layout.html rename to alabaster_hotwire/layout.html index 0885d03..a4adc7e 100644 --- a/alabaster/layout.html +++ b/alabaster_hotwire/layout.html @@ -10,6 +10,9 @@ {% endif %} + + + {% endblock %} {# top+bottom related navs; we also have our own in sidebar #} @@ -41,6 +44,18 @@ {# Nav should appear before content, not after #} {%- block content %} + {%- if theme_fixed_sidebar|lower == 'true' %}
{{ sidebar() }} @@ -86,17 +101,10 @@ {%- block footer %}
- {% if show_copyright %}©{{ copyright }}.{% endif %} - {% if theme_show_powered_by|lower == 'true' %} - {% if show_copyright %}|{% endif %} - Powered by Sphinx {{ sphinx_version }} - & Alabaster {{ alabaster_version }} - {% endif %} - {%- if show_source and has_source and sourcename %} - {% if show_copyright or theme_show_powered_by %}|{% endif %} - {{ _('Page source') }} - {%- endif %} + Brought to you by the + Hotwire Django team. + Standing on the shoulder of Giants. + Hotwire Django is not affiliated with Hotwire.dev nor Basecamp
{% if theme_github_banner|lower != 'false' %} diff --git a/alabaster/navigation.html b/alabaster_hotwire/navigation.html similarity index 100% rename from alabaster/navigation.html rename to alabaster_hotwire/navigation.html diff --git a/alabaster/relations.html b/alabaster_hotwire/relations.html similarity index 100% rename from alabaster/relations.html rename to alabaster_hotwire/relations.html diff --git a/alabaster/static/alabaster.css_t b/alabaster_hotwire/static/alabaster.css_t similarity index 83% rename from alabaster/static/alabaster.css_t rename to alabaster_hotwire/static/alabaster.css_t index b6f790b..3722dab 100644 --- a/alabaster/static/alabaster.css_t +++ b/alabaster_hotwire/static/alabaster.css_t @@ -58,10 +58,9 @@ /* -- page layout ----------------------------------------------------------- */ body { - font-family: {{ theme_font_family }}; - font-size: {{ theme_font_size }}; - background-color: {{ theme_base_bg }}; - color: {{ theme_base_text }}; + font-size: 16px; + background-color: #fff; + color: black; margin: 0; padding: 0; } @@ -85,6 +84,8 @@ div.sphinxsidebar { width: {{ theme_sidebar_width }}; font-size: 14px; line-height: 1.5; + font-family: "Jost", sans-serif; + } hr { @@ -92,8 +93,6 @@ hr { } div.body { - background-color: {{ theme_body_bg }}; - color: {{ theme_body_text }}; padding: 0 30px 0 30px; } @@ -104,17 +103,15 @@ div.body > .section { div.footer { width: {{ theme_page_width }}; margin: 20px auto 30px auto; - font-size: 14px; - color: {{ theme_footer_text }}; - text-align: right; + font-size: 0.85em; + font-style: italic; } -div.footer a { - color: {{ theme_footer_text }}; +div.footer .dim { + color: #888; } p.caption { - font-family: {{ theme_caption_font_family }}; font-size: {{ theme_caption_font_size }}; } @@ -162,7 +159,6 @@ div.sphinxsidebarwrapper p.blurb { div.sphinxsidebar h3, div.sphinxsidebar h4 { - font-family: {{ theme_head_font_family }}; color: {{ theme_sidebar_header }}; font-size: 24px; font-weight: normal; @@ -206,7 +202,6 @@ div.sphinxsidebar ul li.toctree-l2 > a { div.sphinxsidebar input { border: 1px solid {{ theme_sidebar_search_button }}; - font-family: {{ theme_font_family }}; font-size: 1em; } @@ -252,10 +247,13 @@ 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; + margin-top: 1.5em; + margin-bottom: 0.75em; + font-family: "Jost", sans-serif; + font-weight: 600; + letter-spacing: -.01em; + line-height: 1.1em; + word-wrap: break-word; } div.body h1 { margin-top: 0; padding-top: 0; font-size: 240%; } @@ -293,7 +291,6 @@ div.admonition tt.xref, div.admonition code.xref, div.admonition a tt { } div.admonition p.admonition-title { - font-family: {{ theme_head_font_family }}; font-weight: normal; font-size: 24px; margin: 0 0 10px 0; @@ -382,7 +379,6 @@ p.admonition-title:after { } pre, tt, code { - font-family: {{theme_code_font_family}}; font-size: {{ theme_code_font_size }}; } @@ -494,7 +490,7 @@ ul, ol { } pre { - background: {{ theme_pre_bg }}; + background: #fbf7f0; padding: 7px 30px; margin: 15px 0px; line-height: 1.3em; @@ -510,7 +506,7 @@ dl pre, blockquote pre, li pre { } tt, code { - background-color: {{ theme_code_bg }}; + background-color: #fbf7f0; color: {{ theme_code_text }}; /* padding: 1px 2px; */ } @@ -767,3 +763,115 @@ nav#breadcrumbs li+li:before { display: none; } } + + + +// + +:root { + --color-white: #fff; + --color-black: #191919; + --color-django: #f0fbf5; + --color-yellow: #ffe801; + --color-teal: #15d1d8; + --color-pink: #ef6baa; + --color-text: var(--color-black); + --color-sheet: var(--color-white); + --color-neutral: var(--color-django); + --color-link: var(--color-yellow); + --color-accent: var(--color-yellow); + --color-positive: var(--color-teal); + --color-negative: var(--color-pink); + --space-xs: 0.25em; + --space-s: 0.5em; + --space-m: 1em; + --space-l: 1.5em; + --space-xl: 3em; + --space-xxl: 4em; + --space-xxxl: 6em; + --font-main: "Bitter", serif; + --type-base: max(1.8em,min(calc(1em + 0.9vw),2.4em)); + --type-xxxs: 55%; + --type-xxs: 65%; + --type-xs: 75%; + --type-s: 85%; + --type-m: 100%; + --type-l: 120%; + --type-xl: 150%; + --type-xxl: 200%; + --type-xxxl: 300%; + --type-xxxxl: 600%; + --leading-s: 1.1; + --leading-m: 1.4; + --leading-l: 1.7; + --leading-xl: 2; +} + +body { + /* background-color: var(--color-django); */ + font-family: var(--font-main); + //font-size: var(--type-base); + font-variation-settings: "wdth" 180; + color: var(--color-text); +} + + +.jump { + margin: 0; + padding: 4px 1em; + color: #FFF; + background-color: #000; + display: flex; + align-items: center; + justify-content: center; + font-family: "Jost", sans-serif; + text-transform: uppercase; + font-style: italic; } + @media (min-width: 40em) { + .jump { + justify-content: flex-start; } } + +.jump__list { + list-style-type: none; + display: flex; + align-items: center; + justify-content: center; + margin: 0; + padding: 0; } + .jump__list li { + margin: 0; + padding: 0; } + .jump__list li:nth-child(2)::after, .jump__list li:nth-child(3)::after { + content: "/"; + display: inline-block; + margin: 0 0.25em 0 0.125em; } + +.jump__list-link { + display: inline-block; + margin: 0; + padding: 0.5em 0.125em; + color: #FFF; + font-weight: 500; + text-decoration: none; } + @media (min-width: 40em) { + .jump__list-link { + padding: 0.125em; + font-size: 0.85em; } } + .jump__list-link:visited { + color: #FFF; } + .jump__list-link:hover { + color: #ffe801; } + +.jump__list-link--hotwire { + font-weight: 700; + margin-right: 0.25em; } + +.jump__list-link--active { + color: #5cd8e5 !important; + text-decoration: none; + pointer-events: none; } + +.jump__list-link--disabled { + opacity: 0.5; + text-decoration: none; + pointer-events: none; } diff --git a/alabaster/static/custom.css b/alabaster_hotwire/static/custom.css similarity index 100% rename from alabaster/static/custom.css rename to alabaster_hotwire/static/custom.css diff --git a/alabaster/support.py b/alabaster_hotwire/support.py similarity index 99% rename from alabaster/support.py rename to alabaster_hotwire/support.py index ebde7b3..6331f0c 100644 --- a/alabaster/support.py +++ b/alabaster_hotwire/support.py @@ -18,7 +18,7 @@ # Originally based on FlaskyStyle which was based on 'tango'. -class Alabaster(Style): +class AlabasterHotwire(Style): background_color = "#f8f8f8" # doesn't seem to override CSS 'pre' styling? default_style = "" diff --git a/alabaster/theme.conf b/alabaster_hotwire/theme.conf similarity index 90% rename from alabaster/theme.conf rename to alabaster_hotwire/theme.conf index b6cdc8d..30bcaeb 100644 --- a/alabaster/theme.conf +++ b/alabaster_hotwire/theme.conf @@ -1,7 +1,7 @@ [theme] inherit = basic stylesheet = alabaster.css -pygments_style = alabaster.support.Alabaster +pygments_style = alabaster_hotwire.support.AlabasterHotwire [options] analytics_id = @@ -123,8 +123,4 @@ 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 deleted file mode 100644 index 5f14e3e..0000000 --- a/docs/changelog.rst +++ /dev/null @@ -1,243 +0,0 @@ -========= -Changelog -========= - -- :release:`0.7.12 <2018-10-02>` -- :bug:`-` 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. -- :support:`- backported` Reorganize the :doc:`customization page - ` 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 backported` (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 - `_. - - 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 backported` 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. -- :release:`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 - ` ``font_family`` and/or ``head_font_family`` in your - ``conf.py``'s ``html_theme_options``, e.g.:: - - 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 backported` (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. -- :support:`- backported` Miscellaneous project maintenance updates such as - adding to Travis CI and enforcing the use of ``flake8``. -- :feature:`110 backported` Add ``badge_branch`` option allowing - configurability of which specific Git branch the Travis, Codecov, etc buttons - default to. Credit: ``@TitanSnow``. -- :support:`111 backported` Add setuptools-level entrypoint for improved theme - distribution compatibility. Thanks to Aaron Carlisle for the patch. -- :release:`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 `_, - 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. -- :release:`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 ```` (i.e. canonical - URLs). Thanks to Ben Gamari for the patch. -- :support:`7` Generate real documentation site, both because the README is - just too big now, and so we can `eat our own dog food - `_. -- :release:`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. -- :release:`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 `_ badge support to sidebar. -- :release:`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. -- :release:`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 ```` from the footer 'show source' section. Credit to - Marcin Wojdyr. -- :release:`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. -- :release:`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. -- :release:`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. -- :release:`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. -- :release:`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. -- :release:`0.6.1 <2014-09-04>` -- Update Gittip support to acknowledge the service's rename to Gratipay. -- :release:`0.6.0 <2014-04-17>` -- Allow hiding the 'powered by' section of the footer. -- Fix outdated name in ``setup.py`` URL field. -- :release:`0.5.1 <2014-04-15>` -- Fix a bug in the new Travis support, re: its default value. -- :release:`0.5.0 <2014-04-09>` -- Add support for sidebar Travis status buttons. -- :release:`0.4.1 <2014-04-06>` -- Fix an inaccuracy in the description of ``logo_text_align``. -- Update logo & text styling to be more sensible. -- :release:`0.4.0 <2014-04-06>` -- Add an option to allow un-hiding one's toctree. -- :release:`0.3.1 <2014-03-13>` -- Improved Python 3 compatibility. -- Update styling of changelog pages generated by `bitprophet/releases - `_. -- :release:`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. -- :release:`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. -- :release:`0.1.0 <2013-12-31>` -- First tagged/PyPI'd version. diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index 40f7b72..0000000 --- a/docs/conf.py +++ /dev/null @@ -1,36 +0,0 @@ -from datetime import datetime - - -extensions = [] -templates_path = ["_templates"] -source_suffix = ".rst" -master_doc = "index" - -project = u"Alabaster" -year = datetime.now().year -copyright = u"%d Jeff Forcier" % year - -exclude_patterns = ["_build"] - -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": "bitprophet", - "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 -} - -extensions.append("releases") -releases_github_path = "bitprophet/alabaster" -# Our pre-0.x releases are unstable / mix bugs+features -releases_unstable_prehistory = True diff --git a/docs/customization.rst b/docs/customization.rst deleted file mode 100644 index 11c245f..0000000 --- a/docs/customization.rst +++ /dev/null @@ -1,265 +0,0 @@ -============= -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 `. 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 - `_ - 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 - `_ - 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': 'bitprophet', - 'github_repo': 'alabaster', - } - -The following subsections detail available such options, including notes about -behavior. Default values can be found by viewing `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``: If set, is used as the base URL (set before the relative - path/pagename) for a ```` `canonical URL - `_ header tag. - - .. note:: This value must end with a trailing slash. - -* ``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. 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 - `_ 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 `_ 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 - `_. - -* ``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 `_ - 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 `_ 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 `_. -* ``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. -* ``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 deleted file mode 100644 index f2957d7..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,49 +0,0 @@ -========================= -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 `_ 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 -`_ `"krTheme" Sphinx theme -`_ (it's the one used -in his `Requests `_ project). Kenneth's -theme was itself originally based on Armin Ronacher's `Flask -`_ theme. Many thanks to both for their hard work. - - -Implementation notes -==================== - -* `Fabric #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 deleted file mode 100644 index 1060f9b..0000000 --- a/docs/installation.rst +++ /dev/null @@ -1,90 +0,0 @@ -============ -Installation -============ - -The bare minimum required to install Alabaster is as follows: - -* If you're on **Sphinx 1.2 or older**: - - * ``pip install alabaster`` or equivalent. - * Add the following to your ``conf.py`` so Alabaster's theme location & - mini-extension are located & loaded: - - .. code-block:: python - - import alabaster - - html_theme_path = [alabaster.get_path()] - extensions = ['alabaster'] - html_theme = 'alabaster' - - * If you've installed Alabaster by hand (without using ``pip``) and/or are - doing funky things to your PYTHONPATH, you may need to replace the - ``alabaster.get_path()`` call with your own explicit string, as per `the - Sphinx config docs - `_. - -* If you have **Sphinx 1.3 or above**: - - * You already have Alabaster installed as a dependency! No need to manually - install it or explicitly load it. - - .. note:: - If you distribute your documentation via the excellent `Read the Docs - `_, you may need to explicitly enable - Alabaster (as RTD defaults to using its own theme) by adding this line - to your ``conf.py``:: - - html_theme = 'alabaster' - -* **Either way**, 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 - `_ 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 `, -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' -`_) to your ``conf.py``: - -.. code-block:: python - - html_static_path = ['_static'] diff --git a/setup.py b/setup.py index b7a1779..74fceef 100644 --- a/setup.py +++ b/setup.py @@ -5,7 +5,7 @@ # Version info -- read without importing _locals = {} -with open("alabaster/_version.py") as fp: +with open("alabaster_hotwire/_version.py") as fp: exec(fp.read(), None, _locals) version = _locals["__version__"] @@ -14,16 +14,16 @@ readme = f.read() setup( - name="alabaster", + name="alabaster_hotwire", version=version, description="A configurable sidebar-enabled Sphinx theme", long_description=readme, author="Jeff Forcier", author_email="jeff@bitprophet.org", url="https://alabaster.readthedocs.io", - packages=["alabaster"], + packages=["alabaster_hotwire"], include_package_data=True, - entry_points={"sphinx.html_themes": ["alabaster = alabaster"]}, + entry_points={"sphinx.html_themes": ["alabaster_hotwire = alabaster_hotwire"]}, classifiers=[ "Development Status :: 5 - Production/Stable", "Intended Audience :: Developers",