From 31b7c3b46ac9687e796796ef8435e505c5570df9 Mon Sep 17 00:00:00 2001 From: Anthony Johnson Date: Wed, 26 Sep 2018 14:35:45 -0600 Subject: [PATCH 01/13] 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/13] 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 da20d3e82e71fa238709a567a91b6d8edef0c2ff Mon Sep 17 00:00:00 2001 From: Jan-Philip Gehrcke Date: Sat, 15 Dec 2018 17:52:45 +0100 Subject: [PATCH 03/13] footer.html: show last_updated below copyright Without this patch the following text can appear on the same line: Copyright year-year, name Last updated on Mmm DD, YYY. The additional container ensures that the last_updated notice is placed below the copyright notice. --- sphinx_rtd_theme/footer.html | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/sphinx_rtd_theme/footer.html b/sphinx_rtd_theme/footer.html index 66261c11..8303b8b0 100644 --- a/sphinx_rtd_theme/footer.html +++ b/sphinx_rtd_theme/footer.html @@ -36,7 +36,9 @@ {% endtrans %} {%- elif last_updated %} - {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %} +
+ {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %} +
{%- endif %}

From 6635e76c5a9587d50c539d0c145d8b7b9f9e8605 Mon Sep 17 00:00:00 2001 From: Jan-Philip Gehrcke Date: Sat, 15 Dec 2018 17:59:37 +0100 Subject: [PATCH 04/13] Update changelog.rst --- docs/changelog.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/changelog.rst b/docs/changelog.rst index 1cd1c5a7..64db8f11 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -18,6 +18,7 @@ Fixes * Fix scrolling to active item in sidebar on load (#214) * Style caption link for code and literal blocks * Fix inconsistent font size and line height for autodoc "raises" and "returns" (#267) +* Fix last_updated notice appearing in same line as copyright notice (#704) Other Changes From 3af8d2f664dfaecc43ed776490aae6d1dcd406ab Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Wed, 19 Dec 2018 11:09:15 +0100 Subject: [PATCH 05/13] Making the background of search configurable Signed-off-by: Gergely Csatari --- sphinx_rtd_theme/layout.html | 3 +-- sphinx_rtd_theme/theme.conf | 3 ++- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/sphinx_rtd_theme/layout.html b/sphinx_rtd_theme/layout.html index 2df1b39c..8d497e9a 100644 --- a/sphinx_rtd_theme/layout.html +++ b/sphinx_rtd_theme/layout.html @@ -105,11 +105,10 @@ {% block extrabody %} {% endblock %}
- {# SIDE NAV, TOGGLES ON MOBILE #}