IntenseWebs/sphinx_rtd_theme
3
0
Fork 0
mirror of https://github.com/readthedocs/sphinx_rtd_theme.git synced 2025-02-25 18:55:21 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into foldable-local-toc

Browse Source
This commit is contained in:
Anthony 2018-03-29 17:35:01 -06:00 committed by GitHub
commit 8cf3a8db30
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
32 changed files with 581 additions and 686 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
.github/CODE_OF_CONDUCT.md vendored Normal file
View File

@ -0,0 +1,5 @@
# Code of Conduct
A copy of our code of conduct can be found on Read the Docs as seen below.
http://docs.readthedocs.io/en/latest/code-of-conduct.html

26
.github/ISSUE_TEMPLATE.md vendored Normal file
View File

@ -0,0 +1,26 @@
### Problem
Give details on your issue.
### Reproducible Project
Please give a link to a public reproducible project or provide an example of the Restructured Text that gives an issue.
```rst
Place RST code here (if any).
```
#### Error Logs/Results
Place any images or error logs that might be able to help solve the issue here.
#### Expected Results
Please describe how this should work properly.
### Environment Info
- Python Version:
- Sphinx Version:
- RTD Theme Version:

4
Gemfile
View File

@ -1,4 +0,0 @@
# A sample Gemfile
source "https://rubygems.org"
gem "compass"

16
Gemfile.lock
View File

@ -1,16 +0,0 @@
GEM
remote: https://rubygems.org/
specs:
chunky_png (1.2.9)
compass (0.12.2)
chunky_png (~> 1.2)
fssm (>= 0.2.7)
sass (~> 3.1)
fssm (0.2.10)
sass (3.2.12)
PLATFORMS
ruby
DEPENDENCIES
compass

23
Gruntfile.js
View File

@ -111,7 +111,26 @@ module.exports = function(grunt) {
dest: 'sphinx_rtd_theme/static/js/theme.js' dest: 'sphinx_rtd_theme/static/js/theme.js'
} }
}, },
uglify: {
dist: {
options: {
sourceMap: false,
mangle: {
reserved: ['jQuery'] // Leave 'jQuery' identifier unchanged
},
ie8: true // compliance with IE 6-8 quirks
},
files: [{
expand: true,
src: ['sphinx_rtd_theme/static/js/*.js', '!sphinx_rtd_theme/static/js/*.min.js'],
dest: 'sphinx_rtd_theme/static/js/',
rename: function (dst, src) {
// Use unminified file name for minified file
return src;
}
}]
}
},
exec: { exec: {
bower_update: { bower_update: {
cmd: 'bower update' cmd: 'bower update'
@ -162,5 +181,5 @@ module.exports = function(grunt) {
grunt.loadNpmTasks('grunt-browserify'); grunt.loadNpmTasks('grunt-browserify');
grunt.registerTask('default', ['exec:bower_update','clean','copy:fonts','sass:dev','browserify:dev','exec:build_sphinx','connect','open','watch']); grunt.registerTask('default', ['exec:bower_update','clean','copy:fonts','sass:dev','browserify:dev','exec:build_sphinx','connect','open','watch']);
grunt.registerTask('build', ['exec:bower_update','clean','copy:fonts','sass:build','browserify:build','exec:build_sphinx']); grunt.registerTask('build', ['exec:bower_update','clean','copy:fonts','sass:build','browserify:build','uglify','exec:build_sphinx']);
} }

2
LICENSE
View File

@ -1,6 +1,6 @@
The MIT License (MIT) The MIT License (MIT)
Copyright (c) 2013 Dave Snider Copyright (c) 2013-2018 Dave Snider, Read the Docs, Inc. & contributors
Permission is hereby granted, free of charge, to any person obtaining a copy of Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in this software and associated documentation files (the "Software"), to deal in

344
README.rst
View File

@ -1,332 +1,54 @@
.. _readthedocs.org: http://www.readthedocs.org
.. _bower: http://www.bower.io
.. _sphinx: http://www.sphinx-doc.org
.. _compass: http://www.compass-style.org
.. _sass: http://www.sass-lang.com
.. _wyrm: http://www.github.com/snide/wyrm/
.. _grunt: http://www.gruntjs.com
.. _node: http://www.nodejs.com
.. _demo: https://sphinx-rtd-theme.readthedocs.io/en/latest/
.. _hidden: http://sphinx-doc.org/markup/toctree.html
.. image:: https://img.shields.io/pypi/v/sphinx_rtd_theme.svg
:target: https://pypi.python.org/pypi/sphinx_rtd_theme
.. image:: https://travis-ci.org/rtfd/sphinx_rtd_theme.svg?branch=master
:target: https://travis-ci.org/rtfd/sphinx_rtd_theme
.. image:: https://img.shields.io/pypi/l/sphinx_rtd_theme.svg
:target: https://pypi.python.org/pypi/sphinx_rtd_theme/
:alt: license
.. image:: https://readthedocs.org/projects/sphinx-rtd-theme/badge/?version=latest
:target: http://sphinx-rtd-theme.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
************************** **************************
Read the Docs Sphinx Theme Read the Docs Sphinx Theme
************************** **************************
.. contents:: .. image:: https://img.shields.io/pypi/v/sphinx_rtd_theme.svg
:backlinks: none :target: https://pypi.python.org/pypi/sphinx_rtd_theme
:alt: Pypi Version
.. image:: https://travis-ci.org/rtfd/sphinx_rtd_theme.svg?branch=master
:target: https://travis-ci.org/rtfd/sphinx_rtd_theme
:alt: Build Status
.. image:: https://img.shields.io/pypi/l/sphinx_rtd_theme.svg
:target: https://pypi.python.org/pypi/sphinx_rtd_theme/
:alt: License
.. image:: https://readthedocs.org/projects/sphinx-rtd-theme/badge/?version=latest
:target: http://sphinx-rtd-theme.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
View a working demo_ over on readthedocs.org_. The ``sphinx_rtd_theme`` is a sphinx_ theme designed to look modern and be mobile-friendly.
This theme is primary focused to be used on readthedocs.org_ but can work with your
own sphinx projects. To read more and see a working demo_ head over to readthedocs.org_.
This is a mobile-friendly sphinx_ theme I made for readthedocs.org_. .. _sphinx: http://www.sphinx-doc.org
.. _readthedocs.org: http://www.readthedocs.org
.. _demo: https://sphinx-rtd-theme.readthedocs.io/en/latest/
If you'd like to update the theme,
please make your edits to the SASS files here,
rather than the .css files on checked into the repo.
Installation Installing
============ ==========
Via package The theme is distributed on PyPI_ and can be installed with pip::
-----------
Download the package or add it to your ``requirements.txt`` file: pip install sphinx_rtd_theme
.. code:: bash For more information read the full installing docs
`here <https://sphinx-rtd-theme.readthedocs.io/en/latest/installing.html>`__.
pip install sphinx_rtd_theme .. _PyPI: https://pypi.python.org/pypi/sphinx_rtd_theme
In your ``conf.py`` file:
.. code:: python
import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
or (since v0.2.5):
.. code:: python
html_theme = "sphinx_rtd_theme"
Via git or download
-------------------
Symlink or subtree the ``sphinx_rtd_theme/sphinx_rtd_theme`` repository into your documentation at
``docs/_themes/sphinx_rtd_theme`` then add the following two settings to your Sphinx
``conf.py`` file:
.. code:: python
html_theme = "sphinx_rtd_theme"
html_theme_path = ["_themes", ]
Configuration Configuration
============= =============
You can configure different parts of the theme. The ``sphinx_rtd_theme`` is highly customizable on both the page level and on a global level.
To see all the possible configuration options read the configuring docs
`here <https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html>`__.
Project-wide configuration
--------------------------
The theme's project-wide options are defined in the ``sphinx_rtd_theme/theme.conf`` Contributing
file of this repository, and can be defined in your project's ``conf.py`` via ============
``html_theme_options``. For example:
.. code:: python If you would like to help improve the theme or have more control
over the theme in case of a fork please read our contributing guide
html_theme_options = { `here <https://sphinx-rtd-theme.readthedocs.io/en/latest/contributing.html>`__.
'typekit_id': '',
'canonical_url': '',
'analytics_id': '',
'logo_only': False,
'display_version': True,
'prev_next_buttons_location': bottom,
'style_external_links': False,
# Toc options
'collapse_navigation': False,
'sticky_navigation': True,
'navigation_depth': 4,
'includehidden': True,
'titles_only': False
}
The following options are available:
Base options
~~~~~~~~~~~~
* ``typekit_id`` This will let users specify a typekit id to use for displaying nicer fonts.
* ``canonical_url`` String. This will specify a `canonical url <https://en.wikipedia.org/wiki/Canonical_link_element>`__
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``.
TOC Options
~~~~~~~~~~~
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
* ``collapse_navigation`` Bool. With this enabled, you will lose the `[+]` drop downs next to each section in the sidebar.
This is useful for _very large_ documents.
* ``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, all levels are included.
* ``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.
Page-level configuration
------------------------
Pages support metadata that changes how the theme renders.
You can currently add the following:
* ``: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
Changelog
=========
master
------
* Include fontawesome-webfont.woff2 in pip package
* Updated wyrm_ and Font Awesome
* Split multiple data types on different lines
* Italicize ``.versionmodified``
* Fix line number spacing to align with the code lines
* Hide Edit links on auto created pages
* Align ``.. centered::`` text to the center
* Increase contrast for footnotes
* Add language to the JS output variable
* Include the lato italics font with the theme
* Fix padding on field lists
* Add setuptools entry point allowing to use ``sphinx_rtd_theme`` as
Sphinx ``html_theme`` directly.
v0.2.4
------
* Yet another patch to deal with extra builders outside Spinx, such as the
singlehtml builders from the Read the Docs Sphinx extension
v0.2.3
------
* Temporarily patch Sphinx issue with ``singlehtml`` builder by inspecting the
builder in template.
v0.2.2
------
* Roll back toctree fix in 0.2.1 (#367). This didn't fix the issue and
introduced another bug with toctrees display.
v0.2.1
------
* Add the ``rel`` HTML attribute to the footer links which point to
the previous and next pages.
* Fix toctree issue caused by Sphinx singlehtml builder (#367)
v0.2.0
------
* Adds the ``comments`` block after the ``body`` block in the template
* Added "Edit on GitLab" support
* Many bug fixes
v0.1.10-alpha
-------------
.. note:: This is a pre-release version
* Removes Sphinx dependency
* Fixes hamburger on mobile display
* Adds a ``body_begin`` block to the template
* Added ``prev_next_buttons_location``
v0.1.9
------
* Intermittent scrollbar visibility bug fixed. This change introduces a
backwards incompatible change to the theme's layout HTML. This should only be
a problem for derivative themes that have overridden styling of nav elements
using direct decendant selectors. See `#215`_ for more information.
* Safari overscroll bug fixed
* Version added to the nav header
* Revision id was added to the documentation footer if you are using RTD
* An extra block, ``extrafooter`` was added to allow extra content in the
document footer block
* Fixed modernizr URL
* Small display style changes on code blocks, figure captions, and nav elements
.. _#215: https://github.com/rtfd/sphinx_rtd_theme/pull/215
v0.1.8
------
* Start keeping changelog :)
* Support for third and fourth level headers in the sidebar
* Add support for Sphinx 1.3
* Add sidebar headers for :caption: in Sphinx toctree
* Clean up sidebar scrolling behavior so it never scrolls out of view
How the Table of Contents builds
================================
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.
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.
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.
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``.
Contributing or modifying the theme
===================================
The sphinx_rtd_theme is primarily a sass_ project that requires a few other sass libraries. I'm
using bower_ to manage these dependencies and sass_ to build the css. The good news is
I have a very nice set of grunt_ operations that will not only load these dependencies, but watch
for changes, rebuild the sphinx demo docs and build a distributable version of the theme.
The bad news is this means you'll need to set up your environment similar to that
of a front-end developer (vs. that of a python developer). That means installing node and ruby.
Set up your environment
-----------------------
#. Install sphinx_ into a virtual environment.
.. code:: bash
pip install sphinx sphinxcontrib-httpdomain
#. Install sass.
.. code:: bash
gem install sass
#. Install node, bower, grunt, and theme dependencies.
.. code:: bash
# Install node
brew install node
# Install bower and grunt
npm install -g bower grunt-cli
# Now that everything is installed, let's install the theme dependencies.
npm install
Now that our environment is set up, make sure you're in your virtual environment, go to
this repository in your terminal and run grunt:
.. code::
grunt
This default task will do the following **very cool things that make it worth the trouble**:
#. Install and update any bower dependencies.
#. Run sphinx and build new docs.
#. Watch for changes to the sass files and build css from the changes.
#. Rebuild the sphinx docs anytime it notices a change to ``.rst``, ``.html``, ``.js``
or ``.css`` files.
Before you create an issue
--------------------------
I don't have a lot of time to maintain this project due to other responsibilities.
I know there are a lot of Python engineers out there that can't code sass / css and
are unable to submit pull requests. That said, submitting random style bugs without
at least providing sample documentation that replicates your problem is a good
way for me to ignore your request. RST unfortunately can spit out a lot of things
in a lot of ways. I don't have time to research your problem for you, but I do
have time to fix the actual styling issue if you can replicate the problem for me.
Releasing the Theme
===================
When you release a new version,
you should do the following:
#. Bump the version in ``sphinx_rtd_theme/__init__.py`` – we try to follow `semver <http://semver.org/>`_, so be careful with breaking changes.
#. Run a ``grunt build`` to rebuild all the theme assets.
#. Commit that change.
#. Tag the release in git: ``git tag $NEW_VERSION``.
#. Push the tag to GitHub: ``git push --tags origin``.
#. Upload the package to PyPI: ``python setup.py sdist bdist_wheel upload``.
#. 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.
TODO
====
* Separate some sass variables at the theme level so you can overwrite some basic colors.

2
bower.json
View File

@ -3,7 +3,7 @@
"version": "0.2.4", "version": "0.2.4",
"homepage": "https://github.com/rtfd/sphinx_rtd_theme", "homepage": "https://github.com/rtfd/sphinx_rtd_theme",
"authors": [ "authors": [
"Dave Snider <dave.snider@gmail.com>" "Dave Snider, Read the Docs, Inc. & contributors <dev@readthedocs.org>"
], ],
"description": "Sphinx theme for readthedocs.org.", "description": "Sphinx theme for readthedocs.org.",
"license": "MIT", "license": "MIT",

2
docs/Makefile
View File

@ -6,7 +6,7 @@ SPHINXOPTS =
SPHINXBUILD = sphinx-build SPHINXBUILD = sphinx-build
SPHINXPROJ = ReadtheDocsSphinxTheme SPHINXPROJ = ReadtheDocsSphinxTheme
SOURCEDIR = . SOURCEDIR = .
BUILDDIR = _build BUILDDIR = build
# Put it first so that "make" without argument is like "make help". # Put it first so that "make" without argument is like "make help".
help: help:

107
docs/changelog.rst Normal file
View File

@ -0,0 +1,107 @@
*********
Changelog
*********
master
======
v0.2.5
======
New Features
-------------
* Add html language attribute
* Allow setting 'rel' and 'title' attributes for stylesheets (#551)
* Add option to style external links
* Add github, gitlab, bitbucket page arguments option
* Add pygments support
* Add setuptools entry point allowing to use ``sphinx_rtd_theme`` as
Sphinx ``html_theme`` directly.
* Add language to the JS output variable
Fixes
-----
* Fix some HTML warnings and errors
* Fix many styling issues
* Fix many sidebar glitches
* Fix line number spacing to align with the code lines
* Hide Edit links on auto created pages
* Include missing font files with the theme
Other Changes
--------------
* Significant improvement of our documentation
* Compress our Javascript files
* Updated dependencies
v0.2.4
======
* Yet another patch to deal with extra builders outside Spinx, such as the
singlehtml builders from the Read the Docs Sphinx extension
v0.2.3
======
* Temporarily patch Sphinx issue with ``singlehtml`` builder by inspecting the
builder in template.
v0.2.2
======
* Roll back toctree fix in 0.2.1 (#367). This didn't fix the issue and
introduced another bug with toctrees display.
v0.2.1
======
* Add the ``rel`` HTML attribute to the footer links which point to
the previous and next pages.
* Fix toctree issue caused by Sphinx singlehtml builder (#367)
v0.2.0
======
* Adds the ``comments`` block after the ``body`` block in the template
* Added "Edit on GitLab" support
* Many bug fixes
v0.1.10-alpha
=============
.. note:: This is a pre-release version
* Removes Sphinx dependency
* Fixes hamburger on mobile display
* Adds a ``body_begin`` block to the template
* Added ``prev_next_buttons_location``
v0.1.9
======
* Intermittent scrollbar visibility bug fixed. This change introduces a
backwards incompatible change to the theme's layout HTML. This should only be
a problem for derivative themes that have overridden styling of nav elements
using direct descendant selectors. See `#215`_ for more information.
* Safari overscroll bug fixed
* Version added to the nav header
* Revision id was added to the documentation footer if you are using RTD
* An extra block, ``extrafooter`` was added to allow extra content in the
document footer block
* Fixed modernizr URL
* Small display style changes on code blocks, figure captions, and nav elements
.. _#215: https://github.com/rtfd/sphinx_rtd_theme/pull/215
v0.1.8
======
* Start keeping changelog :)
* Support for third and fourth level headers in the sidebar
* Add support for Sphinx 1.3
* Add sidebar headers for :caption: in Sphinx toctree
* Clean up sidebar scrolling behavior so it never scrolls out of view

23
docs/conf.py
View File

@ -33,14 +33,15 @@ from sphinx_rtd_theme import __version__
# Add any Sphinx extension module names here, as strings. They can be extensions # Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [ extensions = [
'sphinx.ext.intersphinx',
'sphinx.ext.autodoc', 'sphinx.ext.autodoc',
'sphinx.ext.mathjax', 'sphinx.ext.mathjax',
'sphinx.ext.viewcode', 'sphinx.ext.viewcode',
'sphinxcontrib.httpdomain', 'sphinxcontrib.httpdomain',
] ]
# Math # Do not warn about external images (status badges in README.rst)
mathjax_path = "http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML" suppress_warnings = ['image.nonlocal_uri']
# Add any paths that contain templates here, relative to this directory. # Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates'] templates_path = ['_templates']
@ -56,7 +57,7 @@ master_doc = 'index'
# General information about the project. # General information about the project.
project = u'Read the Docs Sphinx Theme' project = u'Read the Docs Sphinx Theme'
copyright = u'Read the Docs, Inc & contributors' copyright = u'Dave Snider, Read the Docs, Inc. & contributors'
# The version info for the project you're documenting, acts as replacement for # The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the # |version| and |release|, also used in various other places throughout the
@ -96,11 +97,13 @@ exclude_patterns = []
#show_authors = False #show_authors = False
# The name of the Pygments (syntax highlighting) style to use. # The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx' pygments_style = 'default'
# A list of ignored prefixes for module index sorting. # A list of ignored prefixes for module index sorting.
#modindex_common_prefix = [] #modindex_common_prefix = []
intersphinx_mapping = {'rtd': ('https://docs.readthedocs.io/en/latest/', None)}
# -- Options for HTML output --------------------------------------------------- # -- Options for HTML output ---------------------------------------------------
@ -112,9 +115,7 @@ html_theme = 'sphinx_rtd_theme'
# further. For a list of options available for each theme, see the # further. For a list of options available for each theme, see the
# documentation. # documentation.
html_theme_options = { html_theme_options = {
# 'sticky_navigation': True # Set to False to disable the sticky nav while scrolling. 'logo_only': True
# 'logo_only': True, # if we have a html_logo below, this shows /only/ the logo with no title text
# 'titles_only': False # If True, it'll remove headers within a page from the sidebar.
} }
# Add any paths that contain custom themes here, relative to this directory. # Add any paths that contain custom themes here, relative to this directory.
@ -203,7 +204,7 @@ latex_elements = {
# (source start file, target name, title, author, documentclass [howto/manual]). # (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [ latex_documents = [
('index', 'SphinxRTDthemedemo.tex', u'Sphinx RTD theme demo Documentation', ('index', 'SphinxRTDthemedemo.tex', u'Sphinx RTD theme demo Documentation',
u'Dave Snider', 'manual'), u'Dave Snider, Read the Docs, Inc. & contributors', 'manual'),
] ]
# The name of an image file (relative to this directory) to place at the top of # The name of an image file (relative to this directory) to place at the top of
@ -233,7 +234,7 @@ latex_documents = [
# (source start file, name, description, authors, manual section). # (source start file, name, description, authors, manual section).
man_pages = [ man_pages = [
('index', 'sphinxrtdthemedemo', u'Sphinx RTD theme demo Documentation', ('index', 'sphinxrtdthemedemo', u'Sphinx RTD theme demo Documentation',
[u'Dave Snider'], 1) [u'Dave Snider, Read the Docs, Inc. & contributors'], 1)
] ]
# If true, show URL addresses after external links. # If true, show URL addresses after external links.
@ -247,8 +248,8 @@ man_pages = [
# dir menu entry, description, category) # dir menu entry, description, category)
texinfo_documents = [ texinfo_documents = [
('index', 'SphinxRTDthemedemo', u'Sphinx RTD theme demo Documentation', ('index', 'SphinxRTDthemedemo', u'Sphinx RTD theme demo Documentation',
u'Dave Snider', 'SphinxRTDthemedemo', 'One line description of project.', u'Dave Snider, Read the Docs, Inc. & contributors', 'SphinxRTDthemedemo',
'Miscellaneous'), 'One line description of project.', 'Miscellaneous'),
] ]
# Documents to append as an appendix to all manuals. # Documents to append as an appendix to all manuals.

101
docs/configuring.rst Normal file
View File

@ -0,0 +1,101 @@
*************
Configuration
*************
You can configure different parts of the theme.
Project-wide Configuration
==========================
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:
.. code:: python
html_theme_options = {
'canonical_url': '',
'analytics_id': '',
'logo_only': False,
'display_version': True,
'prev_next_buttons_location': 'bottom',
'style_external_links': False,
'vcs_pageview_mode': '',
# Toc options
'collapse_navigation': False,
'sticky_navigation': True,
'navigation_depth': 4,
'includehidden': True,
'titles_only': False
}
The following options are available:
Base options
~~~~~~~~~~~~
* ``canonical_url`` String. This will specify a `canonical url <https://en.wikipedia.org/wiki/Canonical_link_element>`__
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`.
TOC Options
~~~~~~~~~~~
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
* ``collapse_navigation`` Bool. With this enabled, you will lose the ``[+]`` drop downs next to each section in the sidebar.
This is useful for *very large* documents.
* ``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, all levels are included.
* ``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.
HTML Context Options
--------------------
TODO.
Page-level Configuration
========================
Pages support metadata that changes how the theme renders.
You can currently add the following:
* ``: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
How the Table of Contents builds
================================
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.
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.
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: <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 vertically too large, it will revert to static positioning. To disable the sticky nav
altogether change the setting in ``conf.py``.
.. _hidden: http://sphinx-doc.org/markup/toctree.html

85
docs/contributing.rst Normal file
View File

@ -0,0 +1,85 @@
***********************************
Contributing or modifying the theme
***********************************
The sphinx_rtd_theme is primarily a sass_ project that requires a few other sass libraries. I'm
using bower_ to manage these dependencies and sass_ to build the css. The good news is
I have a very nice set of grunt_ operations that will not only load these dependencies, but watch
for changes, rebuild the sphinx demo docs and build a distributable version of the theme.
The bad news is this means you'll need to set up your environment similar to that
of a front-end developer (vs. that of a python developer). That means installing node and ruby.
.. seealso::
If you are unsure of appropriate actions to take while interacting with our
community please read our :doc:`Code of Conduct <rtd:/code-of-conduct>`.
Set up your environment
=======================
#. Install sphinx_ into a virtual environment.
.. code:: bash
pip install sphinx sphinxcontrib-httpdomain
#. Install sass.
.. code:: bash
gem install sass
#. Install node, bower, grunt, and theme dependencies.
.. code:: bash
# Install node
brew install node
# Install bower and grunt
npm install -g bower grunt-cli
# Now that everything is installed, let's install the theme dependencies.
npm install
Now that our environment is set up, make sure you're in your virtual environment, go to
this repository in your terminal and run grunt:
.. code::
grunt
This default task will do the following **very cool things that make it worth the trouble**:
#. Install and update any bower dependencies.
#. Run sphinx and build new docs.
#. Watch for changes to the sass files and build css from the changes.
#. Rebuild the sphinx docs anytime it notices a change to ``.rst``, ``.html``, ``.js``
or ``.css`` files.
.. _bower: http://www.bower.io
.. _sass: http://www.sass-lang.com
.. _wyrm: http://www.github.com/snide/wyrm/
.. _grunt: http://www.gruntjs.com
.. _node: http://www.nodejs.com
.. _sphinx: http://www.sphinx-doc.org/en/stable/
Releasing the Theme
===================
When you release a new version,
you should do the following:
#. Bump the version in ``sphinx_rtd_theme/__init__.py`` --
we try to follow `semver <http://semver.org/>`_, so be careful with breaking changes.
#. Run a ``grunt build`` to rebuild all the theme assets.
#. Commit that change.
#. Tag the release in git: ``git tag $NEW_VERSION``.
#. Push the tag to GitHub: ``git push --tags origin``.
#. Upload the package to PyPI: ``python setup.py sdist bdist_wheel upload``.
#. 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.

5
docs/demo/api.rst
View File

@ -10,6 +10,11 @@
:private-members: :private-members:
:special-members: :special-members:
Generated Index
===============
Part of the sphinx build process in generate and index file: :ref:`genindex`.
Optional parameter args Optional parameter args
======================= =======================

28
docs/demo/index.rst
View File

@ -1,28 +0,0 @@
Read the Docs Theme Demo
************************
These documents are used to test and stress test the Read the Docs Theme.
:Last Reviewed: 2017-3-15
Contents
========
.. toctree::
:maxdepth: 3
:numbered:
:caption: Syntax Constructs
structure
demo
lists_tables
api
.. toctree::
:maxdepth: 3
:numbered:
:caption: This is an incredibly long caption for a long menu
long
You can also read the :ref:`genindex`

27
docs/index.rst
View File

@ -1,13 +1,28 @@
.. include:: ../README.rst .. include:: ../README.rst
Content .. toctree::
======= :caption: Theme Documentation
:maxdepth: 2
installing
configuring
changelog
contributing
.. toctree:: .. toctree::
:caption: Theme :maxdepth: 2
:numbered:
:caption: Demo Documents
demo/structure
demo/demo
demo/lists_tables
demo/api
.. toctree:: .. toctree::
:caption: Demo :maxdepth: 3
:numbered:
:caption: This is an incredibly long caption for a long menu
demo/index demo/long

32
docs/installing.rst Normal file
View File

@ -0,0 +1,32 @@
************
Installation
************
Via Python Package
==================
Install the package (or add it to your ``requirements.txt`` file):
.. code:: bash
pip install sphinx_rtd_theme
In your ``conf.py`` file:
.. code:: python
html_theme = "sphinx_rtd_theme"
Via Git or Download
===================
Symlink or subtree the ``sphinx_rtd_theme/sphinx_rtd_theme`` repository into your documentation at
``docs/_themes/sphinx_rtd_theme`` then add the following two settings to your Sphinx
``conf.py`` file:
.. code:: python
html_theme = "sphinx_rtd_theme"
html_theme_path = ["_themes", ]

2
docs/make.bat
View File

@ -10,7 +10,7 @@ if "%SPHINXBUILD%" == "" (
set SPHINXOPTS= set SPHINXOPTS=
set SPHINXBUILD=sphinx-build set SPHINXBUILD=sphinx-build
set SOURCEDIR=. set SOURCEDIR=.
set BUILDDIR=_build set BUILDDIR=build
set SPHINXPROJ=ReadtheDocsSphinxTheme set SPHINXPROJ=ReadtheDocsSphinxTheme
if "%1" == "" goto help if "%1" == "" goto help

2
docs/requirements.txt
View File

@ -1,2 +1,2 @@
sphinxcontrib.httpdomain sphinxcontrib-httpdomain
sphinx sphinx

54
js/theme.js
View File

@ -114,36 +114,40 @@ function ThemeNav () {
nav.reset = function () { nav.reset = function () {
// Get anchor from URL and open up nested nav // Get anchor from URL and open up nested nav
var anchor = encodeURI(window.location.hash); var anchor = encodeURI(window.location.hash) || '#';
if (anchor) {
try { try {
var link = $('.wy-menu-vertical') var vmenu = $('.wy-menu-vertical');
.find('[href="' + anchor + '"]'); var link = vmenu.find('[href="' + anchor + '"]');
// If we didn't find a link, it may be because we clicked on if (link.length === 0) {
// something that is not in the sidebar (eg: when using // this link was not found in the sidebar.
// sphinxcontrib.httpdomain it generates headerlinks but those // Find associated id element, then its closest section
// aren't picked up and placed in the toctree). So let's find // in the document and try with that one.
// the closest header in the document and try with that one. var id_elt = $('.document [id="' + anchor.substring(1) + '"]');
var closest_section = id_elt.closest('div.section');
link = vmenu.find('[href="#' + closest_section.attr("id") + '"]');
if (link.length === 0) { if (link.length === 0) {
var doc_link = $('.document a[href="' + anchor + '"]'); // still not found in the sidebar. fall back to main section
var closest_section = doc_link.closest('div.section'); link = vmenu.find('[href="#"]');
// Try again with the closest section entry.
link = $('.wy-menu-vertical')
.find('[href="#' + closest_section.attr("id") + '"]');
}
// If we found a matching link then reset current and re-apply
// otherwise retain the existing match
if (link.length > 0) {
$('.wy-menu-vertical li.toctree-l1 li.current').removeClass('current');
link.closest('li.toctree-l2').addClass('current');
link.closest('li.toctree-l3').addClass('current');
link.closest('li.toctree-l4').addClass('current');
} }
} }
catch (err) { // If we found a matching link then reset current and re-apply
console.log("Error expanding nav for anchor", err); // otherwise retain the existing match
if (link.length > 0) {
$('.wy-menu-vertical .current').removeClass('current');
link.addClass('current');
link.closest('li.toctree-l1').addClass('current');
link.closest('li.toctree-l1').parent().addClass('current');
link.closest('li.toctree-l1').addClass('current');
link.closest('li.toctree-l2').addClass('current');
link.closest('li.toctree-l3').addClass('current');
link.closest('li.toctree-l4').addClass('current');
} }
} }
catch (err) {
console.log("Error expanding nav for anchor", err);
}
}; };
nav.onScroll = function () { nav.onScroll = function () {

1
package.json
View File

@ -12,6 +12,7 @@
"grunt-contrib-connect": "^1.0.2", "grunt-contrib-connect": "^1.0.2",
"grunt-contrib-copy": "~1.0.0", "grunt-contrib-copy": "~1.0.0",
"grunt-contrib-sass": "~1.0.0", "grunt-contrib-sass": "~1.0.0",
"grunt-contrib-uglify": "~3.3.0",
"grunt-contrib-watch": "~1.0.0", "grunt-contrib-watch": "~1.0.0",
"grunt-exec": "~1.0.1", "grunt-exec": "~1.0.1",
"grunt-open": "0.2.3", "grunt-open": "0.2.3",

4
sass/_theme_badge.sass
View File

@ -2,10 +2,10 @@
position: fixed position: fixed
bottom: 0 bottom: 0
left: 0 left: 0
overflow-y: scroll
width: $nav-desktop-width width: $nav-desktop-width
color: $section-background-color color: $section-background-color
background: darken($menu-background-color, 8%) background: darken($menu-background-color, 8%)
border-top: solid 10px $menu-background-color
font-family: $base-font-family font-family: $base-font-family
z-index: $z-index-tray z-index: $z-index-tray
a a
@ -34,6 +34,8 @@
&.rst-active-old-version &.rst-active-old-version
background-color: $yellow background-color: $yellow
color: $black color: $black
&.shift-up
max-height: 100%
&.shift-up .rst-other-versions &.shift-up .rst-other-versions
display: block display: block
.rst-other-versions .rst-other-versions

16
sass/_theme_layout.sass
View File

@ -78,8 +78,6 @@
position: relative position: relative
background: $menu-vertical-background-color background: $menu-vertical-background-color
border: none border: none
border-bottom: solid 1px darken($menu-vertical-background-color, 20%)
border-top: solid 1px darken($menu-vertical-background-color, 20%)
padding-left: $gutter -4px padding-left: $gutter -4px
+font-smooth +font-smooth
&:hover &:hover
@ -94,6 +92,10 @@
line-height: 1.6em line-height: 1.6em
color: darken($menu-link-medium, 30%) color: darken($menu-link-medium, 30%)
li.toctree-l1.current > a
border-bottom: solid 1px darken($menu-vertical-background-color, 20%)
border-top: solid 1px darken($menu-vertical-background-color, 20%)
// This is the on state for pages beyond second level // This is the on state for pages beyond second level
li.toctree-l1.current li.toctree-l2, li.toctree-l2.current li.toctree-l3 li.toctree-l1.current li.toctree-l2, li.toctree-l2.current li.toctree-l3
> ul > ul
@ -123,8 +125,6 @@
display: block display: block
background: darken($menu-vertical-background-color, 25%) background: darken($menu-vertical-background-color, 25%)
padding: $gutter / 4 $gutter * 3.5 padding: $gutter / 4 $gutter * 3.5
border-top: none
border-bottom: none
a:hover span.toctree-expand a:hover span.toctree-expand
color: $menu-link-medium color: $menu-link-medium
span.toctree-expand span.toctree-expand
@ -244,9 +244,7 @@
.wy-body-for-nav .wy-body-for-nav
background: left repeat-y $section-background-color background: $section-background-color
background-image: url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAyRpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8+IDx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IkFkb2JlIFhNUCBDb3JlIDUuMy1jMDExIDY2LjE0NTY2MSwgMjAxMi8wMi8wNi0xNDo1NjoyNyAgICAgICAgIj4gPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4gPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIgeG1sbnM6eG1wPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvIiB4bWxuczp4bXBNTT0iaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wL21tLyIgeG1sbnM6c3RSZWY9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9zVHlwZS9SZXNvdXJjZVJlZiMiIHhtcDpDcmVhdG9yVG9vbD0iQWRvYmUgUGhvdG9zaG9wIENTNiAoTWFjaW50b3NoKSIgeG1wTU06SW5zdGFuY2VJRD0ieG1wLmlpZDoxOERBMTRGRDBFMUUxMUUzODUwMkJCOThDMEVFNURFMCIgeG1wTU06RG9jdW1lbnRJRD0ieG1wLmRpZDoxOERBMTRGRTBFMUUxMUUzODUwMkJCOThDMEVFNURFMCI+IDx4bXBNTTpEZXJpdmVkRnJvbSBzdFJlZjppbnN0YW5jZUlEPSJ4bXAuaWlkOjE4REExNEZCMEUxRTExRTM4NTAyQkI5OEMwRUU1REUwIiBzdFJlZjpkb2N1bWVudElEPSJ4bXAuZGlkOjE4REExNEZDMEUxRTExRTM4NTAyQkI5OEMwRUU1REUwIi8+IDwvcmRmOkRlc2NyaXB0aW9uPiA8L3JkZjpSREY+IDwveDp4bXBtZXRhPiA8P3hwYWNrZXQgZW5kPSJyIj8+EwrlwAAAAA5JREFUeNpiMDU0BAgwAAE2AJgB9BnaAAAAAElFTkSuQmCC)
background-size: $nav-desktop-width 1px
.wy-grid-for-nav .wy-grid-for-nav
position: absolute position: absolute
@ -308,7 +306,7 @@
.wy-nav-content .wy-nav-content
padding: $gutter $gutter * 2 padding: $gutter $gutter * 2
height: 100% height: 100%
max-width: 800px max-width: $nav-content-width
margin: auto margin: auto
.wy-body-mask .wy-body-mask
@ -389,7 +387,7 @@ footer
height: 100% height: 100%
overflow: hidden overflow: hidden
+media($desktop-wider) @media screen and (min-width: $nav-media-query)
.wy-nav-content-wrap .wy-nav-content-wrap
background: rgba(0,0,0,.05) background: rgba(0,0,0,.05)
.wy-nav-content .wy-nav-content

48
sass/_theme_rst.sass
View File

@ -19,13 +19,12 @@
max-width: 100% max-width: 100%
height: auto height: auto
.highlight > pre, .linenodiv > pre
line-height: normal
div.figure div.figure
margin-bottom: $base-line-height margin-bottom: $base-line-height
p.caption p.caption
font-style: italic font-style: italic
p:last-child.caption
margin-bottom: 0px
div.figure.align-center div.figure.align-center
text-align: center text-align: center
@ -53,8 +52,41 @@
margin-left: $base-line-height margin-left: $base-line-height
line-height: $base-line-height line-height: $base-line-height
margin-bottom: $base-line-height margin-bottom: $base-line-height
.literal-block, pre.literal-block
@extend .codeblock pre.literal-block, div[class^='highlight']
border: 1px solid $table-border-color
padding: 0px
overflow-x: auto
// 1px hack otherwise border won't show. lame
margin: 1px 0 $base-line-height 0
div[class^='highlight']
border: none
margin: 0
// Needs 100% width for line highlighting to work properly
div[class^='highlight'] td.code
width: 100%
.linenodiv pre
border-right: solid 1px lighten($table-border-color, 2%)
margin: 0
padding: $base-line-height / 2 $base-line-height / 2
font-family: $code-font-family
user-select: none
pointer-events: none
div[class^='highlight'] pre
white-space: pre
margin: 0
padding: $base-line-height / 2 $base-line-height / 2
font-family: $code-font-family
display: block
overflow: auto
pre.literal-block, div[class^='highlight'] pre, .linenodiv pre
font-size: 12px
line-height: normal
@media print
.codeblock, div[class^='highlight'], div[class^='highlight'] pre
white-space: pre-wrap
// These are the various note pullouts that sphinx applies // These are the various note pullouts that sphinx applies
.note, .attention, .caution, .danger, .error, .hint, .important, .tip, .warning, .seealso, .admonition-todo, .admonition .note, .attention, .caution, .danger, .error, .hint, .important, .tip, .warning, .seealso, .admonition-todo, .admonition
@extend .wy-alert @extend .wy-alert
@ -91,7 +123,11 @@
.section ol p, .section ul p .section ol p, .section ul p
margin-bottom: $base-line-height / 2 margin-bottom: $base-line-height / 2
.line-block .line-block
margin-left: 0px
margin-bottom: $base-line-height
.line-block .line-block
margin-left: $base-line-height margin-left: $base-line-height
margin-bottom: 0px
// Generics handling of headings and toc stuff. // Generics handling of headings and toc stuff.
.topic-title .topic-title
@ -197,6 +233,8 @@
table.docutils table.docutils
@extend .wy-table @extend .wy-table
@extend .wy-table-bordered-all @extend .wy-table-bordered-all
th
border-color: $table-border-color
&:not(.field-list) &:not(.field-list)
@extend .wy-table-striped @extend .wy-table-striped
// This table is what gets spit out for auto-generated API stuff. I style it smaller bits of padding. // This table is what gets spit out for auto-generated API stuff. I style it smaller bits of padding.

4
sass/_theme_variables.sass
View File

@ -4,6 +4,10 @@
$font-awesome-dir: "../fonts/" $font-awesome-dir: "../fonts/"
$static-img: "../img/" $static-img: "../img/"
$nav-content-width: 800px
$nav-media-query: (($nav-desktop-width) + ($nav-content-width))
$mathjax-color: $text-color $mathjax-color: $text-color
$headerlink-color: $text-color $headerlink-color: $text-color

4
sass/theme.sass
View File

@ -40,10 +40,6 @@
@import wyrm_core/table @import wyrm_core/table
@import wyrm_core/type @import wyrm_core/type
// Pygments styling
@import wyrm_addons/pygments/pygments
@import wyrm_addons/pygments/pygments_light
// Theme specific styles. These are likely the files you want to edit. // Theme specific styles. These are likely the files you want to edit.
@import theme_breadcrumbs @import theme_breadcrumbs
@import theme_layout @import theme_layout

6
setup.py
View File

@ -1,7 +1,7 @@
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
"""`sphinx_rtd_theme` lives on `Github`_. """`sphinx_rtd_theme` lives on `Github`_.
.. _github: https://www.github.com/snide/sphinx_rtd_theme .. _github: https://github.com/rtfd/sphinx_rtd_theme
""" """
from io import open from io import open
@ -14,8 +14,8 @@ setup(
version=__version__, version=__version__,
url='https://github.com/rtfd/sphinx_rtd_theme/', url='https://github.com/rtfd/sphinx_rtd_theme/',
license='MIT', license='MIT',
author='Dave Snider', author='Dave Snider, Read the Docs, Inc. & contributors',
author_email='dave.snider@gmail.com', author_email='dev@readthedocs.org',
description='Read the Docs theme for Sphinx', description='Read the Docs theme for Sphinx',
long_description=open('README.rst', encoding='utf-8').read(), long_description=open('README.rst', encoding='utf-8').read(),
zip_safe=False, zip_safe=False,

6
sphinx_rtd_theme/breadcrumbs.html
View File

@ -42,21 +42,21 @@
<!-- User defined GitHub URL --> <!-- User defined GitHub URL -->
<a href="{{ meta['github_url'] }}" class="fa fa-github"> {{ _('Edit on GitHub') }}</a> <a href="{{ meta['github_url'] }}" class="fa fa-github"> {{ _('Edit on GitHub') }}</a>
{% else %} {% else %}
<a href="https://{{ github_host|default("github.com") }}/{{ github_user }}/{{ github_repo }}/blob/{{ github_version }}{{ conf_py_path }}{{ pagename }}{{ suffix }}" class="fa fa-github"> {{ _('Edit on GitHub') }}</a> <a href="https://{{ github_host|default("github.com") }}/{{ github_user }}/{{ github_repo }}/{{ theme_vcs_pageview_mode|default("blob") }}/{{ github_version }}{{ conf_py_path }}{{ pagename }}{{ suffix }}" class="fa fa-github"> {{ _('Edit on GitHub') }}</a>
{% endif %} {% endif %}
{% elif display_bitbucket %} {% elif display_bitbucket %}
{% if check_meta and 'bitbucket_url' in meta %} {% if check_meta and 'bitbucket_url' in meta %}
<!-- User defined Bitbucket URL --> <!-- User defined Bitbucket URL -->
<a href="{{ meta['bitbucket_url'] }}" class="fa fa-bitbucket"> {{ _('Edit on Bitbucket') }}</a> <a href="{{ meta['bitbucket_url'] }}" class="fa fa-bitbucket"> {{ _('Edit on Bitbucket') }}</a>
{% else %} {% else %}
<a href="https://bitbucket.org/{{ bitbucket_user }}/{{ bitbucket_repo }}/src/{{ bitbucket_version}}{{ conf_py_path }}{{ pagename }}{{ suffix }}" class="fa fa-bitbucket"> {{ _('Edit on Bitbucket') }}</a> <a href="https://bitbucket.org/{{ bitbucket_user }}/{{ bitbucket_repo }}/src/{{ bitbucket_version}}{{ conf_py_path }}{{ pagename }}{{ suffix }}?mode={{ theme_vcs_pageview_mode|default("view") }}" class="fa fa-bitbucket"> {{ _('Edit on Bitbucket') }}</a>
{% endif %} {% endif %}
{% elif display_gitlab %} {% elif display_gitlab %}
{% if check_meta and 'gitlab_url' in meta %} {% if check_meta and 'gitlab_url' in meta %}
<!-- User defined GitLab URL --> <!-- User defined GitLab URL -->
<a href="{{ meta['gitlab_url'] }}" class="fa fa-gitlab"> {{ _('Edit on GitLab') }}</a> <a href="{{ meta['gitlab_url'] }}" class="fa fa-gitlab"> {{ _('Edit on GitLab') }}</a>
{% else %} {% else %}
<a href="https://{{ gitlab_host|default("gitlab.com") }}/{{ gitlab_user }}/{{ gitlab_repo }}/blob/{{ gitlab_version }}{{ conf_py_path }}{{ pagename }}{{ suffix }}" class="fa fa-gitlab"> {{ _('Edit on GitLab') }}</a> <a href="https://{{ gitlab_host|default("gitlab.com") }}/{{ gitlab_user }}/{{ gitlab_repo }}/{{ theme_vcs_pageview_mode|default("blob") }}/{{ gitlab_version }}{{ conf_py_path }}{{ pagename }}{{ suffix }}" class="fa fa-gitlab"> {{ _('Edit on GitLab') }}</a>
{% endif %} {% endif %}
{% elif show_source and source_url_prefix %} {% elif show_source and source_url_prefix %}
<a href="{{ source_url_prefix }}{{ pagename }}{{ suffix }}">{{ _('View page source') }}</a> <a href="{{ source_url_prefix }}{{ pagename }}{{ suffix }}">{{ _('View page source') }}</a>

2
sphinx_rtd_theme/footer.html
View File

@ -43,7 +43,7 @@
</div> </div>
{%- if show_sphinx %} {%- if show_sphinx %}
{% trans %}Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>{% endtrans %}. {% trans %}Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>{% endtrans %}.
{%- endif %} {%- endif %}
{%- block extrafooter %} {% endblock %} {%- block extrafooter %} {% endblock %}

60
sphinx_rtd_theme/layout.html
View File

@ -33,50 +33,47 @@
{# OPENSEARCH #} {# OPENSEARCH #}
{% if not embedded %} {% if not embedded %}
{% if use_opensearch %} {% if use_opensearch %}
<link rel="search" type="application/opensearchdescription+xml" title="{% trans docstitle=docstitle|e %}Search within {{ docstitle }}{% endtrans %}" href="{{ pathto('_static/opensearch.xml', 1) }}"/> <link rel="search" type="application/opensearchdescription+xml"
title="{% trans docstitle=docstitle|e %}Search within {{ docstitle }}{% endtrans %}"
href="{{ pathto('_static/opensearch.xml', 1) }}"/>
{% endif %} {% endif %}
{% endif %} {% endif %}
{# RTD hosts this file, so just load on non RTD builds #} {# RTD hosts this file, so just load on non RTD builds #}
{% if not READTHEDOCS %} {%- if not READTHEDOCS %}
<link rel="stylesheet" href="{{ pathto('_static/' + style, 1) }}" type="text/css" /> <link rel="stylesheet" href="{{ pathto('_static/' + style, 1) }}" type="text/css" />
{% endif %} {%- endif %}
<link rel="stylesheet" href="{{ pathto('_static/pygments.css', 1) }}" type="text/css" /> <link rel="stylesheet" href="{{ pathto('_static/pygments.css', 1) }}" type="text/css" />
{%- for css in css_files %}
{% for cssfile in css_files %} {%- if css|attr("rel") %}
<link rel="{{ css.rel }}" href="{{ pathto(css.filename, 1) }}" type="text/css"{% if css.title is not none %} title="{{ css.title }}"{% endif %} />
{%- else %}
<link rel="stylesheet" href="{{ pathto(css, 1) }}" type="text/css" />
{%- endif %}
{%- endfor %}
{%- for cssfile in extra_css_files %}
<link rel="stylesheet" href="{{ pathto(cssfile, 1) }}" type="text/css" /> <link rel="stylesheet" href="{{ pathto(cssfile, 1) }}" type="text/css" />
{% endfor %} {%- endfor %}
{% for cssfile in extra_css_files %}
<link rel="stylesheet" href="{{ pathto(cssfile, 1) }}" type="text/css" />
{% endfor %}
{%- block linktags %} {%- block linktags %}
{%- if hasdoc('about') %} {%- if hasdoc('about') %}
<link rel="author" title="{{ _('About these documents') }}" <link rel="author" title="{{ _('About these documents') }}" href="{{ pathto('about') }}" />
href="{{ pathto('about') }}"/>
{%- endif %} {%- endif %}
{%- if hasdoc('genindex') %} {%- if hasdoc('genindex') %}
<link rel="index" title="{{ _('Index') }}" <link rel="index" title="{{ _('Index') }}" href="{{ pathto('genindex') }}" />
href="{{ pathto('genindex') }}"/>
{%- endif %} {%- endif %}
{%- if hasdoc('search') %} {%- if hasdoc('search') %}
<link rel="search" title="{{ _('Search') }}" href="{{ pathto('search') }}"/> <link rel="search" title="{{ _('Search') }}" href="{{ pathto('search') }}" />
{%- endif %} {%- endif %}
{%- if hasdoc('copyright') %} {%- if hasdoc('copyright') %}
<link rel="copyright" title="{{ _('Copyright') }}" href="{{ pathto('copyright') }}"/> <link rel="copyright" title="{{ _('Copyright') }}" href="{{ pathto('copyright') }}" />
{%- endif %}
<link rel="top" title="{{ docstitle|e }}" href="{{ pathto('index') }}"/>
{%- if parents %}
<link rel="up" title="{{ parents[-1].title|striptags|e }}" href="{{ parents[-1].link|e }}"/>
{%- endif %} {%- endif %}
{%- if next %} {%- if next %}
<link rel="next" title="{{ next.title|striptags|e }}" href="{{ next.link|e }}"/> <link rel="next" title="{{ next.title|striptags|e }}" href="{{ next.link|e }}" />
{%- endif %} {%- endif %}
{%- if prev %} {%- if prev %}
<link rel="prev" title="{{ prev.title|striptags|e }}" href="{{ prev.link|e }}"/> <link rel="prev" title="{{ prev.title|striptags|e }}" href="{{ prev.link|e }}" />
{%- endif %} {%- endif %}
{%- endblock %} {%- endblock %}
{%- block extrahead %} {% endblock %} {%- block extrahead %} {% endblock %}
@ -86,7 +83,7 @@
</head> </head>
<body class="wy-body-for-nav" role="document"> <body class="wy-body-for-nav">
{% block extrabody %} {% endblock %} {% block extrabody %} {% endblock %}
<div class="wy-grid-for-nav"> <div class="wy-grid-for-nav">
@ -104,8 +101,10 @@
{% endif %} {% endif %}
{% if logo %} {% if logo %}
{# Not strictly valid HTML, but it's the only way to display/scale it properly, without weird scripting or heaps of work #} {# Not strictly valid HTML, but it's the only way to display/scale
<img src="{{ pathto('_static/' + logo, 1) }}" class="logo" /> it properly, without weird scripting or heaps of work
#}
<img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="Logo"/>
{% endif %} {% endif %}
</a> </a>
@ -152,7 +151,7 @@
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"> <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
{# MOBILE NAV, TRIGGLES SIDE NAV ON TOGGLE #} {# MOBILE NAV, TRIGGLES SIDE NAV ON TOGGLE #}
<nav class="wy-nav-top" role="navigation" aria-label="top navigation"> <nav class="wy-nav-top" aria-label="top navigation">
{% block mobile_nav %} {% block mobile_nav %}
<i data-toggle="wy-nav-top" class="fa fa-bars"></i> <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="{{ pathto(master_doc) }}">{{ project }}</a> <a href="{{ pathto(master_doc) }}">{{ project }}</a>
@ -160,8 +159,8 @@
</nav> </nav>
{# PAGE CONTENT #}
<div class="wy-nav-content"> <div class="wy-nav-content">
{%- block content %}
{% if theme_style_external_links|tobool %} {% if theme_style_external_links|tobool %}
<div class="rst-content style-external-links"> <div class="rst-content style-external-links">
{% else %} {% else %}
@ -169,15 +168,20 @@
{% endif %} {% endif %}
{% include "breadcrumbs.html" %} {% include "breadcrumbs.html" %}
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
{%- block document %}
<div itemprop="articleBody"> <div itemprop="articleBody">
{% block body %}{% endblock %} {% block body %}{% endblock %}
</div> </div>
{% if self.comments()|trim %}
<div class="articleComments"> <div class="articleComments">
{% block comments %}{% endblock %} {% block comments %}{% endblock %}
</div> </div>
{% endif%}
</div> </div>
{%- endblock %}
{% include "footer.html" %} {% include "footer.html" %}
</div> </div>
{%- endblock %}
</div> </div>
</section> </section>

224
sphinx_rtd_theme/static/js/theme.js
View File

@ -1,223 +1 @@
require=(function e(t,n,r){function s(o,u){if(!n[o]){if(!t[o]){var a=typeof require=="function"&&require;if(!u&&a)return a(o,!0);if(i)return i(o,!0);var f=new Error("Cannot find module '"+o+"'");throw f.code="MODULE_NOT_FOUND",f}var l=n[o]={exports:{}};t[o][0].call(l.exports,function(e){var n=t[o][1][e];return s(n?n:e)},l,l.exports,e,t,n,r)}return n[o].exports}var i=typeof require=="function"&&require;for(var o=0;o<r.length;o++)s(r[o]);return s})({"sphinx-rtd-theme":[function(require,module,exports){ require=function n(e,t,i){function o(s,a){if(!t[s]){if(!e[s]){var l="function"==typeof require&&require;if(!a&&l)return l(s,!0);if(r)return r(s,!0);var c=new Error("Cannot find module '"+s+"'");throw c.code="MODULE_NOT_FOUND",c}var u=t[s]={exports:{}};e[s][0].call(u.exports,function(n){var t=e[s][1][n];return o(t||n)},u,u.exports,n,e,t,i)}return t[s].exports}for(var r="function"==typeof require&&require,s=0;s<i.length;s++)o(i[s]);return o}({"sphinx-rtd-theme":[function(n,e,t){var jQuery="undefined"!=typeof window?window.jQuery:n("jquery");e.exports.ThemeNav=function(){var n={navBar:null,win:null,winScroll:!1,winResize:!1,linkScroll:!1,winPosition:0,winHeight:null,docHeight:null,isRunning:!1};return n.enable=function(n){var e=this;e.isRunning||(e.isRunning=!0,jQuery(function(t){e.init(t),e.reset(),e.win.on("hashchange",e.reset),n&&e.win.on("scroll",function(){e.linkScroll||e.winScroll||(e.winScroll=!0,requestAnimationFrame(function(){e.onScroll()}))}),e.win.on("resize",function(){e.winResize||(e.winResize=!0,requestAnimationFrame(function(){e.onResize()}))}),e.onResize()}))},n.enableSticky=function(){this.enable(!0)},n.init=function(n){n(document);var e=this;this.navBar=n("div.wy-side-scroll:first"),this.win=n(window),n(document).on("click","[data-toggle='wy-nav-top']",function(){n("[data-toggle='wy-nav-shift']").toggleClass("shift"),n("[data-toggle='rst-versions']").toggleClass("shift")}).on("click",".wy-menu-vertical .current ul li a",function(){var t=n(this);n("[data-toggle='wy-nav-shift']").removeClass("shift"),n("[data-toggle='rst-versions']").toggleClass("shift"),e.toggleCurrent(t),e.hashChange()}).on("click","[data-toggle='rst-current-version']",function(){n("[data-toggle='rst-versions']").toggleClass("shift-up")}),n("table.docutils:not(.field-list,.footnote,.citation)").wrap("<div class='wy-table-responsive'></div>"),n("table.docutils.footnote").wrap("<div class='wy-table-responsive footnote'></div>"),n("table.docutils.citation").wrap("<div class='wy-table-responsive citation'></div>"),n(".wy-menu-vertical ul").not(".simple").siblings("a").each(function(){var t=n(this);expand=n('<span class="toctree-expand"></span>'),expand.on("click",function(n){return e.toggleCurrent(t),n.stopPropagation(),!1}),t.prepend(expand)})},n.reset=function(){var n=encodeURI(window.location.hash)||"#";try{var e=$(".wy-menu-vertical").find('[href="'+n+'"]');if(0===e.length){var t=$('.document a[href="'+n+'"]').closest("div.section");e=$(".wy-menu-vertical").find('[href="#'+t.attr("id")+'"]')}e.length>0&&($(".wy-menu-vertical .current").removeClass("current"),e.addClass("current"),e.closest("li.toctree-l1").addClass("current"),e.closest("li.toctree-l1").parent().addClass("current"),e.closest("li.toctree-l1").addClass("current"),e.closest("li.toctree-l2").addClass("current"),e.closest("li.toctree-l3").addClass("current"),e.closest("li.toctree-l4").addClass("current"))}catch(i){console.log("Error expanding nav for anchor",i)}},n.onScroll=function(){this.winScroll=!1;var n=this.win.scrollTop(),e=n+this.winHeight,t=this.navBar.scrollTop()+(n-this.winPosition);n<0||e>this.docHeight||(this.navBar.scrollTop(t),this.winPosition=n)},n.onResize=function(){this.winResize=!1,this.winHeight=this.win.height(),this.docHeight=$(document).height()},n.hashChange=function(){this.linkScroll=!0,this.win.one("hashchange",function(){this.linkScroll=!1})},n.toggleCurrent=function(n){var e=n.closest("li");e.siblings("li.current").removeClass("current"),e.siblings().find("li.current").removeClass("current"),e.find("> ul li.current").removeClass("current"),e.toggleClass("current")},n}(),"undefined"!=typeof window&&(window.SphinxRtdTheme={Navigation:e.exports.ThemeNav}),function(){for(var n=0,e=["ms","moz","webkit","o"],t=0;t<e.length&&!window.requestAnimationFrame;++t)window.requestAnimationFrame=window[e[t]+"RequestAnimationFrame"],window.cancelAnimationFrame=window[e[t]+"CancelAnimationFrame"]||window[e[t]+"CancelRequestAnimationFrame"];window.requestAnimationFrame||(window.requestAnimationFrame=function(e,t){var i=(new Date).getTime(),o=Math.max(0,16-(i-n)),r=window.setTimeout(function(){e(i+o)},o);return n=i+o,r}),window.cancelAnimationFrame||(window.cancelAnimationFrame=function(n){clearTimeout(n)})}()},{jquery:"jquery"}]},{},["sphinx-rtd-theme"]);
var jQuery = (typeof(window) != 'undefined') ? window.jQuery : require('jquery');
// Sphinx theme nav state
function ThemeNav () {
var nav = {
navBar: null,
win: null,
winScroll: false,
winResize: false,
linkScroll: false,
winPosition: 0,
winHeight: null,
docHeight: null,
isRunning: false
};
nav.enable = function (withStickyNav) {
var self = this;
if (self.isRunning) {
// Only allow enabling nav logic once
return;
}
self.isRunning = true;
jQuery(function ($) {
self.init($);
self.reset();
self.win.on('hashchange', self.reset);
if (withStickyNav) {
// Set scroll monitor
self.win.on('scroll', function () {
if (!self.linkScroll) {
if (!self.winScroll) {
self.winScroll = true;
requestAnimationFrame(function() { self.onScroll(); });
}
}
});
}
// Set resize monitor
self.win.on('resize', function () {
if (!self.winResize) {
self.winResize = true;
requestAnimationFrame(function() { self.onResize(); });
}
});
self.onResize();
});
};
nav.enableSticky = function() {
this.enable(true);
};
nav.init = function ($) {
var doc = $(document),
self = this;
this.navBar = $('div.wy-side-scroll:first');
this.win = $(window);
// Set up javascript UX bits
$(document)
// Shift nav in mobile when clicking the menu.
.on('click', "[data-toggle='wy-nav-top']", function() {
$("[data-toggle='wy-nav-shift']").toggleClass("shift");
$("[data-toggle='rst-versions']").toggleClass("shift");
})
// Nav menu link click operations
.on('click', ".wy-menu-vertical .current ul li a", function() {
var target = $(this);
// Close menu when you click a link.
$("[data-toggle='wy-nav-shift']").removeClass("shift");
$("[data-toggle='rst-versions']").toggleClass("shift");
// Handle dynamic display of l3 and l4 nav lists
self.toggleCurrent(target);
self.hashChange();
})
.on('click', "[data-toggle='rst-current-version']", function() {
$("[data-toggle='rst-versions']").toggleClass("shift-up");
})
// Make tables responsive
$("table.docutils:not(.field-list,.footnote,.citation)")
.wrap("<div class='wy-table-responsive'></div>");
// Add extra class to responsive tables that contain
// footnotes or citations so that we can target them for styling
$("table.docutils.footnote")
.wrap("<div class='wy-table-responsive footnote'></div>");
$("table.docutils.citation")
.wrap("<div class='wy-table-responsive citation'></div>");
// Add expand links to all parents of nested ul
$('.wy-menu-vertical ul').not('.simple').siblings('a').each(function () {
var link = $(this);
expand = $('<span class="toctree-expand"></span>');
expand.on('click', function (ev) {
self.toggleCurrent(link);
ev.stopPropagation();
return false;
});
link.prepend(expand);
});
};
nav.reset = function () {
// Get anchor from URL and open up nested nav
var anchor = encodeURI(window.location.hash);
if (anchor) {
try {
var link = $('.wy-menu-vertical')
.find('[href="' + anchor + '"]');
// If we didn't find a link, it may be because we clicked on
// something that is not in the sidebar (eg: when using
// sphinxcontrib.httpdomain it generates headerlinks but those
// aren't picked up and placed in the toctree). So let's find
// the closest header in the document and try with that one.
if (link.length === 0) {
var doc_link = $('.document a[href="' + anchor + '"]');
var closest_section = doc_link.closest('div.section');
// Try again with the closest section entry.
link = $('.wy-menu-vertical')
.find('[href="#' + closest_section.attr("id") + '"]');
}
// If we found a matching link then reset current and re-apply
// otherwise retain the existing match
if (link.length > 0) {
$('.wy-menu-vertical li.toctree-l1 li.current').removeClass('current');
link.closest('li.toctree-l2').addClass('current');
link.closest('li.toctree-l3').addClass('current');
link.closest('li.toctree-l4').addClass('current');
}
}
catch (err) {
console.log("Error expanding nav for anchor", err);
}
}
};
nav.onScroll = function () {
this.winScroll = false;
var newWinPosition = this.win.scrollTop(),
winBottom = newWinPosition + this.winHeight,
navPosition = this.navBar.scrollTop(),
newNavPosition = navPosition + (newWinPosition - this.winPosition);
if (newWinPosition < 0 || winBottom > this.docHeight) {
return;
}
this.navBar.scrollTop(newNavPosition);
this.winPosition = newWinPosition;
};
nav.onResize = function () {
this.winResize = false;
this.winHeight = this.win.height();
this.docHeight = $(document).height();
};
nav.hashChange = function () {
this.linkScroll = true;
this.win.one('hashchange', function () {
this.linkScroll = false;
});
};
nav.toggleCurrent = function (elem) {
var parent_li = elem.closest('li');
parent_li.siblings('li.current').removeClass('current');
parent_li.siblings().find('li.current').removeClass('current');
parent_li.find('> ul li.current').removeClass('current');
parent_li.toggleClass('current');
}
return nav;
};
module.exports.ThemeNav = ThemeNav();
if (typeof(window) != 'undefined') {
window.SphinxRtdTheme = { Navigation: module.exports.ThemeNav };
}
// requestAnimationFrame polyfill by Erik Möller. fixes from Paul Irish and Tino Zijdel
// https://gist.github.com/paulirish/1579671
// MIT license
(function() {
var lastTime = 0;
var vendors = ['ms', 'moz', 'webkit', 'o'];
for(var x = 0; x < vendors.length && !window.requestAnimationFrame; ++x) {
window.requestAnimationFrame = window[vendors[x]+'RequestAnimationFrame'];
window.cancelAnimationFrame = window[vendors[x]+'CancelAnimationFrame']
|| window[vendors[x]+'CancelRequestAnimationFrame'];
}
if (!window.requestAnimationFrame)
window.requestAnimationFrame = function(callback, element) {
var currTime = new Date().getTime();
var timeToCall = Math.max(0, 16 - (currTime - lastTime));
var id = window.setTimeout(function() { callback(currTime + timeToCall); },
timeToCall);
lastTime = currTime + timeToCall;
return id;
};
if (!window.cancelAnimationFrame)
window.cancelAnimationFrame = function(id) {
clearTimeout(id);
};
}());
},{"jquery":"jquery"}]},{},["sphinx-rtd-theme"]);

2
sphinx_rtd_theme/theme.conf
View File

@ -4,7 +4,6 @@ stylesheet = css/theme.css
pygments_style = default pygments_style = default
[options] [options]
typekit_id = hiw1hhg
canonical_url = canonical_url =
analytics_id = analytics_id =
collapse_navigation = False collapse_navigation = False
@ -16,3 +15,4 @@ logo_only =
display_version = True display_version = True
prev_next_buttons_location = bottom prev_next_buttons_location = bottom
style_external_links = False style_external_links = False
vcs_pageview_mode =