From 31b7c3b46ac9687e796796ef8435e505c5570df9 Mon Sep 17 00:00:00 2001 From: Anthony Johnson Date: Wed, 26 Sep 2018 14:35:45 -0600 Subject: [PATCH 01/35] Much cleanup for configuration docs * Clean up a lot of copy. * Reduce usage of internal Sphinx concepts like "toctree" * Make language clearer * Fix a few factual inaccuracies * Remove noisey/placeholder/introduction to a paragraph sort of text, this just distracts readers. * Make `confval` domain role to allow for creation of config value field lists that are linkable and can be referenced. Also include type/default fields * Reduce redundancy in heading * Intersphinx to Sphinx docs * Use new role to intersphinx to Sphinx confvals * Add copy on using logo/etc. These are common questions for us for those not familiar with Sphinx. Link to appropriate docs. --- docs/conf.py | 260 ++++++++----------------------------------- docs/configuring.rst | 232 +++++++++++++++++++++++++++----------- 2 files changed, 212 insertions(+), 280 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 36dd0d26..1528eda7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,37 +1,25 @@ # -*- coding: utf-8 -*- -# -# Sphinx RTD theme demo documentation build configuration file, created by -# sphinx-quickstart on Sun Nov 3 11:56:36 2013. -# -# This file is executed with the current directory set to its containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. import sys import os - +import re sys.path.append(os.path.abspath('..')) sys.path.append(os.path.abspath('./demo/')) +from sphinx.locale import _ + from sphinx_rtd_theme import __version__ -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('.')) -# -- General configuration ----------------------------------------------------- +project = u'Read the Docs Sphinx Theme' +slug = re.sub(r'\W+', '-', project.lower()) +version = __version__ +release = __version__ +author = u'Dave Snider, Read the Docs, Inc. & contributors' +copyright = author +language = 'en' -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = [ 'sphinx.ext.intersphinx', 'sphinx.ext.autodoc', @@ -40,223 +28,65 @@ extensions = [ 'sphinxcontrib.httpdomain', ] -# Do not warn about external images (status badges in README.rst) -suppress_warnings = ['image.nonlocal_uri'] - -# Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] - -# The suffix of source filenames. source_suffix = '.rst' - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'Read the Docs Sphinx Theme' -copyright = u'Dave Snider, Read the Docs, Inc. & contributors' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = __version__ -# The full version, including alpha/beta/rc tags. -release = __version__ - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -language = 'en' - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. exclude_patterns = [] -# The reST default role (used for this markup: `text`) to use for all documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. +master_doc = 'index' +suppress_warnings = ['image.nonlocal_uri'] pygments_style = 'default' -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] +intersphinx_mapping = { + 'rtd': ('https://docs.readthedocs.io/en/latest/', None), + 'sphinx': ('http://www.sphinx-doc.org/en/master/', None), +} -intersphinx_mapping = {'rtd': ('https://docs.readthedocs.io/en/latest/', None)} - - -# -- Options for HTML output --------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. html_theme = 'sphinx_rtd_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 -# documentation. html_theme_options = { 'logo_only': True } - -# Add any paths that contain custom themes here, relative to this directory. html_theme_path = ["../.."] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. html_logo = "demo/static/logo-wordmark-light.svg" - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -#html_static_path = ['_static'] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. html_show_sourcelink = True -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True +htmlhelp_basename = slug -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Output file base name for HTML help builder. -htmlhelp_basename = 'SphinxRTDthemedemodoc' - - -# -- Options for LaTeX output -------------------------------------------------- - -latex_elements = { -# The paper size ('letterpaper' or 'a4paper'). -#'papersize': 'letterpaper', - -# The font size ('10pt', '11pt' or '12pt'). -#'pointsize': '10pt', - -# Additional stuff for the LaTeX preamble. -#'preamble': '', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ - ('index', 'SphinxRTDthemedemo.tex', u'Sphinx RTD theme demo Documentation', - u'Dave Snider, Read the Docs, Inc. & contributors', 'manual'), + ('index', '{0}.tex'.format(slug), project, author, 'manual'), ] -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - - -# -- Options for manual page output -------------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). man_pages = [ - ('index', 'sphinxrtdthemedemo', u'Sphinx RTD theme demo Documentation', - [u'Dave Snider, Read the Docs, Inc. & contributors'], 1) + ('index', slug, project, [author], 1) ] -# If true, show URL addresses after external links. -#man_show_urls = False - - -# -- Options for Texinfo output ------------------------------------------------ - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) texinfo_documents = [ - ('index', 'SphinxRTDthemedemo', u'Sphinx RTD theme demo Documentation', - u'Dave Snider, Read the Docs, Inc. & contributors', 'SphinxRTDthemedemo', - 'One line description of project.', 'Miscellaneous'), + ('index', slug, project, author, slug, project, 'Miscellaneous'), ] -# Documents to append as an appendix to all manuals. -#texinfo_appendices = [] -# If false, no module index is generated. -#texinfo_domain_indices = True +# Extensions to theme docs +def setup(app): + from sphinx.domains.python import PyField + from sphinx.util.docfields import Field -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' + app.add_object_type( + 'confval', + 'confval', + objname='configuration value', + indextemplate='pair: %s; configuration value', + doc_field_types=[ + PyField( + 'type', + label=_('Type'), + has_arg=False, + names=('type',), + bodyrolename='class' + ), + Field( + 'default', + label=_('Default'), + has_arg=False, + names=('default',), + ), + ] + ) diff --git a/docs/configuring.rst b/docs/configuring.rst index 67c91bce..b31c2b0d 100644 --- a/docs/configuring.rst +++ b/docs/configuring.rst @@ -1,31 +1,25 @@ - ************* Configuration ************* -You can configure different parts of the theme. +Theme options +============= -Project-wide Configuration -========================== +The following options can be defined in your project's ``conf.py`` file, using +the :confval:`html_theme_options ` configuration option. -HTML Theme Options ------------------- - -The theme's project-wide options are defined in the ``sphinx_rtd_theme/theme.conf`` -file of this repository, and can be defined in your project's ``conf.py`` via -``html_theme_options``. For example: +For example: .. code:: python html_theme_options = { - 'canonical_url': '', + 'canonical_url': 'https://example.com/en/latest/', 'analytics_id': '', 'logo_only': False, 'display_version': True, 'prev_next_buttons_location': 'bottom', 'style_external_links': False, 'vcs_pageview_mode': '', - # Toc options 'collapse_navigation': True, 'sticky_navigation': True, 'navigation_depth': 4, @@ -33,76 +27,184 @@ file of this repository, and can be defined in your project's ``conf.py`` via 'titles_only': False } -The following options are available: +Table of contents options +------------------------- -Base options -~~~~~~~~~~~~ +The following options affect the `table of contents configuration options`_ +Sphinx uses to generate the documentation navigation. -* ``canonical_url`` String. This will specify a `canonical url `__ - to let search engines know they should give higher ranking to latest version of the docs. - The url points to the root of the documentation and requires a trailing slash. -* ``analytics_id`` String. Change the Google Analytics ID that is included on pages. -* ``display_version`` Bool. With this disabled, the version number isn't shown at the top of the sidebar. -* ``prev_next_buttons_location`` String. can take the value ``bottom``, ``top``, ``both`` , or ``None`` - and will display the "Next" and "Previous" buttons accordingly. -* ``style_external_links`` Bool. Add an icon next to external links. Defaults to ``False``. -* ``vcs_pageview_mode`` String. Changes how to view files when using `display_github`, `display_gitlab`, etc. - When using Github or Gitlab this can be: `blob` (default), `edit`, or `raw`, - on Bitbucket, this can be either: `view` (default) or `edit`. +.. confval:: collapse_navigation -TOC Options -~~~~~~~~~~~ + :type: boolean + :default: ``False`` -These effect how we display the Table of Contents in the side bar. You can read more about them here: http://www.sphinx-doc.org/en/stable/templating.html#toctree + With this enabled, navigation entries are not expandable -- the ``[+]`` + icons next to each entry are removed. -* ``collapse_navigation`` Bool. With this enabled, you will lose the ``[+]`` drop downs next to each section in the sidebar. -* ``sticky_navigation`` Bool. This causes the sidebar to scroll with the main page content as you scroll the page. -* ``navigation_depth`` Int. Indicate the max depth of the tree; by default, 4 levels are included; - set it to -1 to allow unlimited depth. -* ``includehidden`` Bool. Specifies if the sidebar includes toctrees marked with the ``:hidden:`` option -* ``titles_only`` Bool. If True, removes headers within a page from the sidebar. +.. confval:: sticky_navigation + + :type: boolean + :default: ``True`` + + Scroll the with the main page content as you scroll the page. + +.. confval:: navigation_depth + + :type: integer + :default: ``4`` + + The maximum depth of the table of contents tree. Set + this to ``-1`` to allow unlimited depth + +.. confval:: includehidden + + :type: boolean + :default: ``True`` + + Specifies if the navigation includes TOC trees marked with + the ``:hidden:`` option + +.. confval:: titles_only + + :type: boolean + :default: False + + When enabled, page subheadings are not included in the + navigation. .. note:: - - Setting ``collapse_navigation`` to False and using a high ``navigation_depth`` - can cause projects with many files and a deep file structure to generate HTML files - that are significantly larger in file size and much longer compilation times. + Setting :confval:`collapse_navigation` to ``False`` and using a high value + for :confval:`navigation_depth` on projects with many files and a deep file + structure can cause long compilation times and can result in HTML files that + are significantly larger in file size. + +.. _table of contents configuration options: http://www.sphinx-doc.org/en/stable/templating.html#toctree -HTML Context Options --------------------- - -TODO. +.. + TODO + . + HTML context options + ~~~~~~~~~~~~~~~~~~~~ -Page-level Configuration -======================== +Miscellaneous options +--------------------- -Pages support metadata that changes how the theme renders. -You can currently add the following: +.. confval:: analytics_id -* ``:github_url:`` This will force the "Edit on GitHub" to the configured URL -* ``:bitbucket_url:`` This will force the "Edit on Bitbucket" to the configured URL -* ``:gitlab_url:`` This will force the "Edit on GitLab" to the configured URL + :type: string + + Change the Google Analytics ID that is included on pages. + +.. confval:: canonical_url + + :type: URL + + This will specify a `canonical URL`_ meta link element to tell search + engines which URL should be ranked as the primary URL for your + documentation. This is important if you have multiple URLs that your + documentation is available through. The URL points to the root path of the + documentation and requires a trailing slash. + +.. confval:: display_version + + :type: boolean + + If ``True``, the version number is shown at the top of the sidebar. + +.. confval:: logo_only + + :type: boolean + :default: ``False`` + + Only display the logo image, do not display the project name at the top of + the sidebar + +.. confval:: prev_next_buttons_location + + :type: string + + Location to display :guilabel:`Next` and :guilabel:`Previous` buttons. This + can be either ``bottom``, ``top``, ``both`` , or ``None`` + +.. confval:: style_external_links + + :type: boolean + :default: ``False`` + + Add an icon next to external links + +.. confval:: vcs_pageview_mode + + :type: string + :default: ``blob`` or ``view`` + + Changes how to view files when using ``display_github``, ``display_gitlab``, + etc. When using GitHub or GitLab this can be: ``blob`` (default), ``edit``, + or ``raw``. On Bitbucket, this can be either: ``view`` (default) or + ``edit``. + +.. _canonical URL: https://en.wikipedia.org/wiki/Canonical_link_element -How the Table of Contents builds -================================ +File-wide metadata +================== -Currently the left menu will build based upon any ``toctree(s)`` defined in your ``index.rst`` file. -It outputs 2 levels of depth, which should give your visitors a high level of access to your -docs. If no toctrees are set the theme reverts to sphinx's usual local toctree. +The following options can be used as :ref:`file-wide metadata +`: -It's important to note that if you don't follow the same styling for your rST headers across -your documents, the toctree will misbuild, and the resulting menu might not show the correct -depth when it renders. +.. confval:: github_url -Also note that by default the table of contents is set with ``includehidden=True``. This allows you -to set a hidden toc in your index file with the `:hidden: `_ property that will allow you -to build a toc without it rendering in your index. + Force the :guilabel:`Edit on GitHub` button to use the configured URL -By default, the navigation will "stick" to the screen as you scroll. However if your toc -is vertically too large, it will revert to static positioning. To disable the sticky nav -altogether change the setting in ``conf.py``. +.. confval:: bitbucket_url -.. _hidden: http://sphinx-doc.org/markup/toctree.html + Force the :guilabel:`Edit on Bitbucket` button to use the configured URL + +.. confval:: gitlab_url + + Force the :guilabel:`Edit on GitLab` button to use the configured URL + + +Other configuration +=================== + +Adding a logo +------------- + +Using the Sphinx standard option :py:confval:`html_logo `, +you can set an image file to be used as a logo at the top of the sidebar. The +theme option :py:confval:`logo_only` also allows for *only* the logo to be shown +at the top of the sidebar. + +Adding custom CSS or Javascript +------------------------------- + +Adding custom CSS or Javascript can help you alter the look and feel of this +theme without forking the theme for local use. + +In order to add custom CSS or Javascript without disrupting the existing theme +files, you can :doc:`add files to be included in your documentation output +`. + +How the table of contents displays +================================== + +Currently the left menu will build based upon any ``toctree`` directives defined +in your source files. It outputs 4 levels of depth by default, to allow for +quick navigation through topics. If no TOC trees are defined, Sphinx's default +behavior is to use the page headings instead. + +It's important to note that if you don't follow the same styling for your reST +headings across your documents, the TOC tree will build incorrectly, and the +resulting menu might not show the correct depth when it renders. + +Also note that by default the table of contents is set with +``includehidden=True``. This allows you to set a hidden TOC in your index file +with the :ref:`:hidden: ` property that will allow you +to build a TOC without it rendering in your index. + +By default, the navigation will "stick" to the screen as you scroll. However if +your TOC is not tall enough, it will revert to static positioning. To disable the +sticky navigation altogether, change the :confval:`sticky_navigation` theme option. From 7ea8ac15291361363f28f9df029e7a5c0fb690f1 Mon Sep 17 00:00:00 2001 From: Aaron Carlisle Date: Fri, 5 Oct 2018 15:04:58 -0400 Subject: [PATCH 02/35] Tests: Include Tests in Pypi distribution --- MANIFEST.in | 2 ++ 1 file changed, 2 insertions(+) diff --git a/MANIFEST.in b/MANIFEST.in index 1e6a2ebd..1f40dd3b 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -9,3 +9,5 @@ recursive-include sphinx_rtd_theme *.svg recursive-include sphinx_rtd_theme *.ttf recursive-include sphinx_rtd_theme *.woff recursive-include sphinx_rtd_theme *.woff2 +recursive-include tests *.py +recursive-include tests *.rst From 8e376af4fc64cf809c8233bd8e571a51edb21317 Mon Sep 17 00:00:00 2001 From: Jesse Tan Date: Fri, 30 Nov 2018 17:50:09 +0100 Subject: [PATCH 03/35] Fix inconsistent font size and line height for autodoc "raises" and "returns" (#691) --- docs/changelog.rst | 17 +++++++++++++++++ sass/_theme_rst.sass | 3 +++ 2 files changed, 20 insertions(+) diff --git a/docs/changelog.rst b/docs/changelog.rst index 717125d0..7c660d68 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -3,6 +3,23 @@ Changelog ********* +master +====== + +:Date: TBD + +New Features +------------- + +Fixes +----- + +* Fix inconsistent font size and line height for autodoc "raises" and "returns" (#267) + +Other Changes +-------------- + + v0.4.2 ====== diff --git a/sass/_theme_rst.sass b/sass/_theme_rst.sass index 458722c8..6a89405b 100644 --- a/sass/_theme_rst.sass +++ b/sass/_theme_rst.sass @@ -263,6 +263,9 @@ border: none td border: none + p + font-size: inherit + line-height: inherit td > strong display: inline-block .field-name From 28e7c4a47a873554c271d1bbf8eb9a230a425683 Mon Sep 17 00:00:00 2001 From: Jesse Tan Date: Fri, 30 Nov 2018 18:05:18 +0100 Subject: [PATCH 04/35] Style code block captions (#689) * Give code block captions same permalink as other elems * Style code block captions like table captions * Revert "Give code block captions same permalink as other elems" This reverts commit 4f7e6da24682153d3d783a907a1e95e36724abf1. --- sass/_theme_rst.sass | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/sass/_theme_rst.sass b/sass/_theme_rst.sass index 6a89405b..ad19eb68 100644 --- a/sass/_theme_rst.sass +++ b/sass/_theme_rst.sass @@ -95,6 +95,13 @@ font-size: 12px line-height: 1.4 + .code-block-caption + font-style: italic + font-size: 85% + line-height: 1 + padding: 1em 0 + text-align: center + @media print .codeblock, div[class^='highlight'], div[class^='highlight'] pre white-space: pre-wrap From b9bf19f5be9ec18fc60ada9220d222cf57c21394 Mon Sep 17 00:00:00 2001 From: Eric Holscher <25510+ericholscher@users.noreply.github.com> Date: Fri, 30 Nov 2018 12:11:20 -0500 Subject: [PATCH 05/35] Remove RTD integration now that it isn't requiremed (#684) --- docs/contributing.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 3e4b241a..a47c3b80 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -87,7 +87,3 @@ you should do the following: $ rm -rf dist/ $ python setup.py sdist bdist_wheel $ twine upload --sign --identity security@readthedocs.org dist/* - -#. In the ``readthedocs.org`` repo, edit the ``bower.json`` file to point at the correct version - (``sphinx-rtd-theme": "https://github.com/rtfd/sphinx-rtd-theme.git#$NEW_VERSION"``). -#. In the ``readthedocs.org`` repo, run ``gulp build`` to update the distributed theme files. From 139a56abee34ce6d71338fdebb8bdf58c23f826e Mon Sep 17 00:00:00 2001 From: Jesse Tan Date: Tue, 4 Dec 2018 16:41:13 +0100 Subject: [PATCH 06/35] Style caption link for code and literal blocks (#690) --- docs/changelog.rst | 2 ++ sass/_theme_rst.sass | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/changelog.rst b/docs/changelog.rst index 7c660d68..e5736672 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -14,8 +14,10 @@ New Features Fixes ----- +* Style caption link for code and literal blocks * Fix inconsistent font size and line height for autodoc "raises" and "returns" (#267) + Other Changes -------------- diff --git a/sass/_theme_rst.sass b/sass/_theme_rst.sass index ad19eb68..7e7542df 100644 --- a/sass/_theme_rst.sass +++ b/sass/_theme_rst.sass @@ -172,7 +172,7 @@ @extend h2 // This is the #href that shows up on hover. Sphinx's is terrible so I hack it away. - h1, h2, h3, h4, h5, h6, dl dt, p.caption, table > caption + h1, h2, h3, h4, h5, h6, dl dt, p.caption, table > caption, .code-block-caption .headerlink visibility: hidden font-size: 14px From 5b7d202a110ec00ef3f5e261716c4f4b8fc55b2f Mon Sep 17 00:00:00 2001 From: Aaron Carlisle Date: Tue, 4 Dec 2018 12:43:45 -0500 Subject: [PATCH 07/35] Small visual improvement to captions in toctree (#665) * Small visual improvement to captions in toctree * Add new nav-caption internal var * Use colored text and add margin * Nav captions now have independent color Co-Authored-By: Blendify * De saturate the bright blue captions Co-Authored-By: Blendify --- sass/_theme_layout.sass | 5 +++-- sass/_theme_variables.sass | 1 + 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/sass/_theme_layout.sass b/sass/_theme_layout.sass index 421fe5b9..904e9ae1 100644 --- a/sass/_theme_layout.sass +++ b/sass/_theme_layout.sass @@ -31,15 +31,16 @@ html width: $nav-desktop-width header, p.caption + color: $nav-caption height: $base-font-size * 2 display: inline-block line-height: $base-font-size * 2 padding: 0 $gutter - margin-bottom: 0 + margin: $base-line-height / 2 0 0 0 display: block font-weight: bold text-transform: uppercase - font-size: 80% + font-size: 85% white-space: nowrap ul diff --git a/sass/_theme_variables.sass b/sass/_theme_variables.sass index 6361ad0f..b4f09152 100644 --- a/sass/_theme_variables.sass +++ b/sass/_theme_variables.sass @@ -51,6 +51,7 @@ $nav-link-color: $blue $nav-link-color-visited: $purple $nav-link-color-hover: lighten($nav-link-color, 6%) !default $nav-link-color-alt: hsl(33, 100%, 51%) +$nav-caption: desaturate($blue, 15%) // Sidebar colors $sidebar-background-color: $table-stripe-color From 7e4592f95c0a1c01a420e6bb3e2bd3f043fd4d11 Mon Sep 17 00:00:00 2001 From: Eric Holscher <25510+ericholscher@users.noreply.github.com> Date: Tue, 4 Dec 2018 15:08:29 -0500 Subject: [PATCH 08/35] Add support for Google Analytics to theme. (#411) * Add support for Google Analytics to theme. This setting has actually existed in the default config since the original version, but doesn't currently work. This fixes that and supports GA if it's set. * Add docs around analytics_id * Do not conflict with RTD insertion of analytics script * Remove dupliate analytics_id * Add analytics_id to the configuration in its new place --- docs/configuring.rst | 2 +- sphinx_rtd_theme/layout.html | 17 +++++++++++++++++ 2 files changed, 18 insertions(+), 1 deletion(-) diff --git a/docs/configuring.rst b/docs/configuring.rst index 67c91bce..94beb09d 100644 --- a/docs/configuring.rst +++ b/docs/configuring.rst @@ -19,7 +19,7 @@ file of this repository, and can be defined in your project's ``conf.py`` via html_theme_options = { 'canonical_url': '', - 'analytics_id': '', + 'analytics_id': 'UA-XXXXXXX-1', # Provided by Google in your dashboard 'logo_only': False, 'display_version': True, 'prev_next_buttons_location': 'bottom', diff --git a/sphinx_rtd_theme/layout.html b/sphinx_rtd_theme/layout.html index 7d9a25df..dccfac1d 100644 --- a/sphinx_rtd_theme/layout.html +++ b/sphinx_rtd_theme/layout.html @@ -221,6 +221,23 @@ }); + {# Do not conflict with RTD insertion of analytics script #} + {% if not READTHEDOCS %} + {% if theme_analytics_id %} + + + + {% endif %} + {% endif %} + {%- block footer %} {% endblock %} From a42c4d74fec660835393a4c9b1e7cb9e654ccc90 Mon Sep 17 00:00:00 2001 From: Aaron Carlisle Date: Tue, 4 Dec 2018 20:27:37 -0500 Subject: [PATCH 09/35] Move javascript back to head (#545) * Move javascript back to head * Move jQuery function back to bottom * Do not change white space * Update comment + whitespace cleanup * Address review points * Fix code comments --- sphinx_rtd_theme/layout.html | 76 ++++++++++++++++-------------------- 1 file changed, 34 insertions(+), 42 deletions(-) diff --git a/sphinx_rtd_theme/layout.html b/sphinx_rtd_theme/layout.html index dccfac1d..2df1b39c 100644 --- a/sphinx_rtd_theme/layout.html +++ b/sphinx_rtd_theme/layout.html @@ -28,18 +28,42 @@ {% endif %} - {# CSS #} - - {# OPENSEARCH #} - {% if not embedded %} - {% if use_opensearch %} - + {# JAVASCRIPTS #} + + {%- if not embedded %} + {# XXX Sphinx 1.8.0 made this an external js-file, quick fix until we refactor the template to inherert more blocks directly from sphinx #} + {% if sphinx_version >= "1.8.0" %} + + {%- for scriptfile in script_files %} + {{ js_tag(scriptfile) }} + {%- endfor %} + {% else %} + + {%- for scriptfile in script_files %} + + {%- endfor %} {% endif %} + - {% endif %} + {# OPENSEARCH #} + {%- if use_opensearch %} + + {%- endif %} + {%- endif %} + {# CSS #} {%- for css in css_files %} @@ -49,6 +73,7 @@ {%- endif %} {%- endfor %} + {%- for cssfile in extra_css_files %} {%- endfor %} @@ -74,10 +99,6 @@ {%- endif %} {%- endblock %} {%- block extrahead %} {% endblock %} - - {# Keep modernizr in head - http://modernizr.com/docs/#installing #} - - @@ -186,35 +207,6 @@ {% include "versions.html" %} - {% if not embedded %} - - {# XXX Sphinx 1.8.0 made this an external js-file, quick fix until we refactor the template to inherert more blocks directly from sphinx #} - {% if sphinx_version >= "1.8.0" %} - - {%- for scriptfile in script_files %} - {{ js_tag(scriptfile) }} - {%- endfor %} - {% else %} - - {%- for scriptfile in script_files %} - - {%- endfor %} - {% endif %} - - {% endif %} - - -