From 04663e0e21a14de4c8bebde360001949e0dcd6c6 Mon Sep 17 00:00:00 2001 From: Fabian Homborg Date: Fri, 2 Oct 2020 19:23:08 +0200 Subject: [PATCH] Replace the doc theme with the pydoctheme Released under the Python Software Foundation License, this one doesn't look awful (no green top bar, huzzah!). Lightly forked it to remove the donation footer (we don't take any) and to change the python references to fish references. The image is just our favicon, which is a stylized "f" and therefore not fantastic (are we facebook?), but it's the best I found, and the thing before had no images at all. Fixes #6500 (as far as I'm concerned) --- doc_src/_static/pygments.css | 2 +- doc_src/conf.py | 6 +- doc_src/python_docs_theme/__init__.py | 12 ++ doc_src/python_docs_theme/layout.html | 58 ++++++ .../python_docs_theme/static/copybutton.js | 64 ++++++ doc_src/python_docs_theme/static/fish.png | Bin 0 -> 192 bytes .../python_docs_theme/static/pydoctheme.css | 193 +++++++++++++++++ doc_src/python_docs_theme/static/sidebar.js | 194 ++++++++++++++++++ doc_src/python_docs_theme/theme.conf | 29 +++ 9 files changed, 555 insertions(+), 3 deletions(-) create mode 100644 doc_src/python_docs_theme/__init__.py create mode 100644 doc_src/python_docs_theme/layout.html create mode 100644 doc_src/python_docs_theme/static/copybutton.js create mode 100644 doc_src/python_docs_theme/static/fish.png create mode 100644 doc_src/python_docs_theme/static/pydoctheme.css create mode 100644 doc_src/python_docs_theme/static/sidebar.js create mode 100644 doc_src/python_docs_theme/theme.conf diff --git a/doc_src/_static/pygments.css b/doc_src/_static/pygments.css index c23283024..fd5bb9c8b 100644 --- a/doc_src/_static/pygments.css +++ b/doc_src/_static/pygments.css @@ -1,4 +1,4 @@ -@import "nature.css"; +@import "pydoctheme.css"; .highlight .hll { background-color: #ffffcc } .highlight { background: #f8f8f8; } diff --git a/doc_src/conf.py b/doc_src/conf.py index f1249f54c..4498ce361 100644 --- a/doc_src/conf.py +++ b/doc_src/conf.py @@ -29,6 +29,8 @@ def setup(app): os.path.join(this_dir, "fish_indent_lexer.py"), lexername="FishIndentLexer" ) lexers["fish-docs-samples"] = fish_indent_lexer + app.add_html_theme( + 'python_docs_theme', this_dir + '/python_docs_theme/') # add_css_file only appears in Sphinx 1.8.0 if hasattr(app, "add_css_file"): app.add_css_file("custom.css") @@ -111,8 +113,8 @@ pygments_style = None # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # !!! If you change this you also need to update the @import at the top -# of _static/fish-syntax-style.css -html_theme = "nature" +# of _static/pygments.css +html_theme = "python_docs_theme" # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the diff --git a/doc_src/python_docs_theme/__init__.py b/doc_src/python_docs_theme/__init__.py new file mode 100644 index 000000000..407d62a8b --- /dev/null +++ b/doc_src/python_docs_theme/__init__.py @@ -0,0 +1,12 @@ +import os + + +def setup(app): + current_dir = os.path.abspath(os.path.dirname(__file__)) + app.add_html_theme( + 'python_docs_theme', current_dir) + + return { + 'parallel_read_safe': True, + 'parallel_write_safe': True, + } diff --git a/doc_src/python_docs_theme/layout.html b/doc_src/python_docs_theme/layout.html new file mode 100644 index 000000000..e5374a96d --- /dev/null +++ b/doc_src/python_docs_theme/layout.html @@ -0,0 +1,58 @@ +{% extends "classic/layout.html" %} + +{% block rootrellink %} +
    • +
  • {{theme_root_name}}{{ reldelim1 }}
    • + {% if theme_root_include_title %} + {{ shorttitle }}{{ reldelim1 }} + {% endif %} +{% endblock %} + +{%- macro searchbox() %} +{# modified from sphinx/themes/basic/searchbox.html #} + {%- if builder != "htmlhelp" %} + + + {%- endif %} +{%- endmacro %} + +{% block relbar1 %} {% if builder != 'qthelp' %} {{ relbar() }} {% endif %} {% endblock %} +{% block relbar2 %} {% if builder != 'qthelp' %} {{ relbar() }} {% endif %} {% endblock %} +{% block relbaritems %} + {%- if pagename != "search" and builder != "singlehtml" and builder != "htmlhelp" %} +
  • + {{ searchbox() }} + {{ reldelim2 }} +
    • + {%- endif %} +{% endblock %} + +{% block extrahead %} + + {% if builder != "htmlhelp" %} + {% if not embedded %}{% endif %} + {% endif %} + {{ super() }} +{% endblock %} + +{% block footer %} +
    + © {% trans %}Copyright{% endtrans %} {{ copyright|e }}. +
    + {%- if last_updated %} + {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %} + {%- endif %} + {% if theme_issues_url %}{% trans pathto_bugs=theme_issues_url %}Found a bug?{% endtrans %}{% endif %} +
    + + {% trans sphinx_version=sphinx_version|e %}Created using Sphinx {{ sphinx_version }}.{% endtrans %} +
    +{% endblock %} diff --git a/doc_src/python_docs_theme/static/copybutton.js b/doc_src/python_docs_theme/static/copybutton.js new file mode 100644 index 000000000..f5960d268 --- /dev/null +++ b/doc_src/python_docs_theme/static/copybutton.js @@ -0,0 +1,64 @@ +$(document).ready(function() { + /* Add a [>>>] button on the top-right corner of code samples to hide + * the >>> and ... prompts and the output and thus make the code + * copyable. */ + var div = $('.highlight-python .highlight,' + + '.highlight-python3 .highlight,' + + '.highlight-pycon .highlight,' + + '.highlight-default .highlight'); + var pre = div.find('pre'); + + // get the styles from the current theme + pre.parent().parent().css('position', 'relative'); + var hide_text = 'Hide the prompts and output'; + var show_text = 'Show the prompts and output'; + var border_width = pre.css('border-top-width'); + var border_style = pre.css('border-top-style'); + var border_color = pre.css('border-top-color'); + var button_styles = { + 'cursor':'pointer', 'position': 'absolute', 'top': '0', 'right': '0', + 'border-color': border_color, 'border-style': border_style, + 'border-width': border_width, 'color': border_color, 'text-size': '75%', + 'font-family': 'monospace', 'padding-left': '0.2em', 'padding-right': '0.2em', + 'border-radius': '0 3px 0 0' + } + + // create and add the button to all the code blocks that contain >>> + div.each(function(index) { + var jthis = $(this); + if (jthis.find('.gp').length > 0) { + var button = $('>>>'); + button.css(button_styles) + button.attr('title', hide_text); + button.data('hidden', 'false'); + jthis.prepend(button); + } + // tracebacks (.gt) contain bare text elements that need to be + // wrapped in a span to work with .nextUntil() (see later) + jthis.find('pre:has(.gt)').contents().filter(function() { + return ((this.nodeType == 3) && (this.data.trim().length > 0)); + }).wrap(''); + }); + + // define the behavior of the button when it's clicked + $('.copybutton').click(function(e){ + e.preventDefault(); + var button = $(this); + if (button.data('hidden') === 'false') { + // hide the code output + button.parent().find('.go, .gp, .gt').hide(); + button.next('pre').find('.gt').nextUntil('.gp, .go').css('visibility', 'hidden'); + button.css('text-decoration', 'line-through'); + button.attr('title', show_text); + button.data('hidden', 'true'); + } else { + // show the code output + button.parent().find('.go, .gp, .gt').show(); + button.next('pre').find('.gt').nextUntil('.gp, .go').css('visibility', 'visible'); + button.css('text-decoration', 'none'); + button.attr('title', hide_text); + button.data('hidden', 'false'); + } + }); +}); + diff --git a/doc_src/python_docs_theme/static/fish.png b/doc_src/python_docs_theme/static/fish.png new file mode 100644 index 0000000000000000000000000000000000000000..41ba714e77d41e2b3dd0efcb5f7822b2e6f9109b GIT binary patch literal 192 zcmeAS@N?(olHy`uVBq!ia0vp^3LwnF3?v&v(vJfvmUKs7M+SzC{oH>NS%G}U;vjb? zhIQv;UIICC0X`wFnwpyb|NnpR;K9k0CzmW)l9`!#_3G8Vd-sNgg?;_{_36=yn?RKg zo-U3d8t0P}7N{o}iingrhUmKFgf8R3g84QU(; lXBv92D%1%cS9YjpV2JW$mD35ER0}kV!PC{xWt~$(696@PJ?j7f literal 0 HcmV?d00001 diff --git a/doc_src/python_docs_theme/static/pydoctheme.css b/doc_src/python_docs_theme/static/pydoctheme.css new file mode 100644 index 000000000..33f74d798 --- /dev/null +++ b/doc_src/python_docs_theme/static/pydoctheme.css @@ -0,0 +1,193 @@ +@import url("default.css"); + +body { + background-color: white; + margin-left: 1em; + margin-right: 1em; +} + +div.related { + margin-bottom: 1.2em; + padding: 0.5em 0; + border-top: 1px solid #ccc; + margin-top: 0.5em; +} + +div.related a:hover { + color: #0095C4; +} + +div.related:first-child { + border-top: 0; + border-bottom: 1px solid #ccc; +} + +.inline-search { + display: inline; +} +form.inline-search input { + display: inline; +} +form.inline-search input[type="submit"] { + width: 40px; +} + +div.sphinxsidebar { + background-color: #eeeeee; + border-radius: 5px; + line-height: 130%; + font-size: smaller; +} + +div.sphinxsidebar h3, div.sphinxsidebar h4 { + margin-top: 1.5em; +} + +div.sphinxsidebarwrapper > h3:first-child { + margin-top: 0.2em; +} + +div.sphinxsidebarwrapper > ul > li > ul > li { + margin-bottom: 0.4em; +} + +div.sphinxsidebar a:hover { + color: #0095C4; +} + +form.inline-search input, +div.sphinxsidebar input { + font-family: 'Lucida Grande',Arial,sans-serif; + border: 1px solid #999999; + font-size: smaller; + border-radius: 3px; +} + +div.sphinxsidebar input[type=text] { + max-width: 150px; +} + +div.body { + padding: 0 0 0 1.2em; +} + +div.body p { + line-height: 140%; +} + +div.body h1, div.body h2, div.body h3, div.body h4, div.body h5, div.body h6 { + margin: 0; + border: 0; + padding: 0.3em 0; +} + +div.body hr { + border: 0; + background-color: #ccc; + height: 1px; +} + +div.body pre { + border-radius: 3px; + border: 1px solid #ac9; +} + +div.body div.admonition, div.body div.impl-detail { + border-radius: 3px; +} + +div.body div.impl-detail > p { + margin: 0; +} + +div.body div.seealso { + border: 1px solid #dddd66; +} + +div.body a { + color: #0072aa; +} + +div.body a:visited { + color: #6363bb; +} + +div.body a:hover { + color: #00B0E4; +} + +tt, code, pre { + font-family: monospace, sans-serif; + font-size: 96.5%; +} + +div.body tt, div.body code { + border-radius: 3px; +} + +div.body tt.descname, div.body code.descname { + font-size: 120%; +} + +div.body tt.xref, div.body a tt, div.body code.xref, div.body a code { + font-weight: normal; +} + +table.docutils { + border: 1px solid #ddd; + min-width: 20%; + border-radius: 3px; + margin-top: 10px; + margin-bottom: 10px; +} + +table.docutils td, table.docutils th { + border: 1px solid #ddd !important; + border-radius: 3px; +} + +table p, table li { + text-align: left !important; +} + +table.docutils th { + background-color: #eee; + padding: 0.3em 0.5em; +} + +table.docutils td { + background-color: white; + padding: 0.3em 0.5em; +} + +table.footnote, table.footnote td { + border: 0 !important; +} + +div.footer { + line-height: 150%; + margin-top: -2em; + text-align: right; + width: auto; + margin-right: 10px; +} + +div.footer a:hover { + color: #0095C4; +} + +.refcount { + color: #060; +} + +.stableabi { + color: #229; +} + +.highlight { + background: none !important; +} + +dl > dt span ~ em { + font-family: monospace, sans-serif; +} diff --git a/doc_src/python_docs_theme/static/sidebar.js b/doc_src/python_docs_theme/static/sidebar.js new file mode 100644 index 000000000..0680c6c8e --- /dev/null +++ b/doc_src/python_docs_theme/static/sidebar.js @@ -0,0 +1,194 @@ +/* + * sidebar.js + * ~~~~~~~~~~ + * + * This script makes the Sphinx sidebar collapsible and implements intelligent + * scrolling. This is a slightly modified version of Sphinx's own sidebar.js. + * + * .sphinxsidebar contains .sphinxsidebarwrapper. This script adds in + * .sphixsidebar, after .sphinxsidebarwrapper, the #sidebarbutton used to + * collapse and expand the sidebar. + * + * When the sidebar is collapsed the .sphinxsidebarwrapper is hidden and the + * width of the sidebar and the margin-left of the document are decreased. + * When the sidebar is expanded the opposite happens. This script saves a + * per-browser/per-session cookie used to remember the position of the sidebar + * among the pages. Once the browser is closed the cookie is deleted and the + * position reset to the default (expanded). + * + * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +$(function() { + // global elements used by the functions. + // the 'sidebarbutton' element is defined as global after its + // creation, in the add_sidebar_button function + var jwindow = $(window); + var jdocument = $(document); + var bodywrapper = $('.bodywrapper'); + var documentwrapper = $('.documentwrapper'); + var sidebar = $('.sphinxsidebar'); + var sidebarwrapper = $('.sphinxsidebarwrapper'); + + // original margin-left of the bodywrapper and width of the sidebar + // with the sidebar expanded + var bw_margin_expanded = bodywrapper.css('margin-left'); + var ssb_width_expanded = sidebar.width(); + + // margin-left of the bodywrapper and width of the sidebar + // with the sidebar collapsed + var bw_margin_collapsed = '.8em'; + var ssb_width_collapsed = '.8em'; + + // colors used by the current theme + var dark_color = '#AAAAAA'; + var light_color = '#CCCCCC'; + + function get_viewport_height() { + if (window.innerHeight) + return window.innerHeight; + else + return jwindow.height(); + } + + function sidebar_is_collapsed() { + return sidebarwrapper.is(':not(:visible)'); + } + + function toggle_sidebar() { + if (sidebar_is_collapsed()) + expand_sidebar(); + else + collapse_sidebar(); + // adjust the scrolling of the sidebar + scroll_sidebar(); + } + + function collapse_sidebar() { + sidebarwrapper.hide(); + sidebar.css('width', ssb_width_collapsed); + bodywrapper.css('margin-left', bw_margin_collapsed); + sidebarbutton.css({ + 'margin-left': '0', + 'height': documentwrapper.height(), + 'border-radius': '5px' + }); + sidebarbutton.find('span').text('»'); + sidebarbutton.attr('title', _('Expand sidebar')); + document.cookie = 'sidebar=collapsed'; + } + + function expand_sidebar() { + bodywrapper.css('margin-left', bw_margin_expanded); + sidebar.css('width', ssb_width_expanded); + sidebarwrapper.show(); + sidebarbutton.css({ + 'margin-left': ssb_width_expanded-12, + 'height': Math.max(sidebarwrapper.height(), documentwrapper.height()), + 'border-radius': '0 5px 5px 0' + }); + sidebarbutton.find('span').text('«'); + sidebarbutton.attr('title', _('Collapse sidebar')); + //sidebarwrapper.css({'padding-top': + // Math.max(window.pageYOffset - sidebarwrapper.offset().top, 10)}); + document.cookie = 'sidebar=expanded'; + } + + function add_sidebar_button() { + sidebarwrapper.css({ + 'float': 'left', + 'margin-right': '0', + 'width': ssb_width_expanded - 28 + }); + // create the button + sidebar.append( + '
    «
    ' + ); + var sidebarbutton = $('#sidebarbutton'); + // find the height of the viewport to center the '<<' in the page + var viewport_height = get_viewport_height(); + var sidebar_offset = sidebar.offset().top; + var sidebar_height = Math.max(documentwrapper.height(), sidebar.height()); + sidebarbutton.find('span').css({ + 'display': 'block', + 'position': 'fixed', + 'top': Math.min(viewport_height/2, sidebar_height/2 + sidebar_offset) - 10 + }); + + sidebarbutton.click(toggle_sidebar); + sidebarbutton.attr('title', _('Collapse sidebar')); + sidebarbutton.css({ + 'border-radius': '0 5px 5px 0', + 'color': '#444444', + 'background-color': '#CCCCCC', + 'font-size': '1.2em', + 'cursor': 'pointer', + 'height': sidebar_height, + 'padding-top': '1px', + 'padding-left': '1px', + 'margin-left': ssb_width_expanded - 12 + }); + + sidebarbutton.hover( + function () { + $(this).css('background-color', dark_color); + }, + function () { + $(this).css('background-color', light_color); + } + ); + } + + function set_position_from_cookie() { + if (!document.cookie) + return; + var items = document.cookie.split(';'); + for(var k=0; k wintop && curbot > winbot) { + sidebarwrapper.css('top', $u.max([wintop - offset - 10, 0])); + } + else if (curtop < wintop && curbot < winbot) { + sidebarwrapper.css('top', $u.min([winbot - sidebar_height - offset - 20, + jdocument.height() - sidebar_height - 200])); + } + } + } + jwindow.scroll(scroll_sidebar); +}); diff --git a/doc_src/python_docs_theme/theme.conf b/doc_src/python_docs_theme/theme.conf new file mode 100644 index 000000000..28924d911 --- /dev/null +++ b/doc_src/python_docs_theme/theme.conf @@ -0,0 +1,29 @@ +[theme] +inherit = default +stylesheet = pydoctheme.css +pygments_style = sphinx + +[options] +bodyfont = 'Lucida Grande', Arial, sans-serif +headfont = 'Lucida Grande', Arial, sans-serif +footerbgcolor = white +footertextcolor = #555555 +relbarbgcolor = white +relbartextcolor = #666666 +relbarlinkcolor = #444444 +sidebarbgcolor = white +sidebartextcolor = #444444 +sidebarlinkcolor = #444444 +bgcolor = white +textcolor = #222222 +linkcolor = #0090c0 +visitedlinkcolor = #00608f +headtextcolor = #1a1a1a +headbgcolor = white +headlinkcolor = #aaaaaa + +issues_url = https://github.com/fish-shell/fish-shell/issues +root_name = fish-shell +root_url = https://fishshell.com/ +root_icon = fish.png +root_include_title = True