Need to replace all the font-weights being used with variables. I think it's causing some issues in Windows chrome when weights like "bold" are being used instead of "700".

This will likely require a wyrm push as well.

From Alex Gaynor.

http://i.imgur.com/eSpykrE.png on

https://cryptography.io/en/latest/glossary/

Thinking of adding a right aligned down caret for the secondary ability of opening a subtree in the menu.

sphinx will use class .external for external http hyperlinks.

http://tmuxp-zh.readthedocs.org/en/latest/
http://tmuxp.readthedocs.org/en/latest/

See under translations: https://readthedocs.org/projects/tmuxp/

@ericholscher Where do things stand currently (old theme, i never used the feature before) with translation? did we have a way to switch back and forth between translations? subprojects?

Especially useful for anything that's meant to be read sequentially.

A pattern for a packaged sphinx theme is at https://github.com/ryan-roemer/sphinx-bootstrap-theme. This would be helpful for wanting to implement the theme as a requirement. People may want to use the rtd theme outside readthedocs.org w/o worrying affecting git modules or theme paths.

http://tmuxp.readthedocs.org/en/latest/about.html#differences-from-tmuxinator-teamocil

We should probably consider including the copyright notice/footer somewhere in the design.

I have put

import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

so I can use sphinx_rtd_theme locally, but when I commit this and push this to my bitbucket repo which readthedocs builds upon, the build fails:

Exception occurred:
  File "/var/build/user_builds/docs-windows/checkouts/latest/conf.py", line 95, in <module>
    import sphinx_rtd_theme
ImportError: No module named sphinx_rtd_theme
The full traceback has been saved in /tmp/sphinx-err-jkBFke.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
Either send bugs to the mailing list at <http://groups.google.com/group/sphinx-dev/>,
or report them in the tracker at <http://bitbucket.org/birkenfeld/sphinx/issues/>. Thanks!

https://github.com/snide/wyrm is a dependency of the project.

We are python.

To build it requires node. Then ruby. In the particular instance of the sphinx_rtd_theme, I have a proposal:

https://github.com/hcatlin/libsass + https://pypi.python.org/pypi/libsass/0.2.4 and I can make a python script to build the CSS for us! 💃 Then there is no need for ruby or node.

We can use snide/wyrm as a gitsubmodule or vendorize (directly copy it in) or make a pypi package of wyrm directly.

What do you think? Can I give it a shot? The benefit is it would stay 100% python.

images loaded like:

.. image:: blah.png
:align: center

are left justified

Looking at 2.

I know why it pushes out (it is a or

 tag) but it should provide scroll bars or something in those cases.

To reproduce this issue, render something like the following:

.. note:: Every other line in this table will have white text on a white background.
            This is bad.

    +---------+                                                                     
    | Example |                                                                        
    +=========+                                                                     
    | Thing1  |                                                                     
    +---------+                                                                     
    | Thing2  |                                                                     
    +---------+                                                                     
    | Thing3  |                                                                     
    +---------+  

Some lists are missing list styling.

For example: http://docs.mopidy.com/en/develop/codestyle/

See at: http://tmuxp.readthedocs.org/en/latest/examples.html

Code is clearing below the sidebar

Checked under IE11:

Although headers can be referred to by anchor links (http://configs.readthedocs.org/en/latest/#installation), there is no easy way to get a ready-to-share permalink, like it was in the old theme.

E.g.:

Looks like this is #bedcf0 on #2980b9, which has a contrast of 3:1 according to this calculator. I believe WCAG AA would require a minimum of 4.5:1 here.

If one tries using a 'catchall' hidden toctree somewhere in their index.rst (e.g. as a catchall for documents that are explicitly linked inline but which aren't otherwise part of toctree elements), the call to the toctree() template method/object in this theme's sidebar raises an AttributeError.

I dug and this is because Sphinx's code (sphinx.environment.get_toctree_for()) returns None when fetching hidden toctrees, unless the includehidden kwarg is given (this seems to be covered by **kwargs all the way back to the method used in-template, FWIW.)

I need to rethink how the doctree in question is structured anyways, given how the new theme exposes its navigation (:heart:). Regardless, I think at least there should be an FAQ for this item; or the template call should say includehidden=True. Otherwise users who innocently use a basic Sphinx feature will be confused like I was :)

I'm comparing this with the kr theme, as it appears in https://github.com/ericholscher/ericholscher.com

--- all on OS/X Mavericks -----
Firefox 25: both render search items (yellow highlight of term once you follow link)
Chrome 31.0.1650.57: rtd: No search context in results; no highlighted terms in items kr: no search context in results highlighted terms in search results pages;
Safari 7.0: rtd: No search functionality; kr: search results, w/ context, highlighted terms in result page;

http://sphinx-doc.org/markup/para.html#directive-seealso - seealso is an official and commonly used admonition in sphinx.

http://tmuxp.readthedocs.org/en/latest/quickstart.html#cli

Shows up almost indistinguishable in current form: Examples, Command Line Interface, Bash completion.

@snide The theme looks attractive, clean and much more readable than the current RTD theme (even other popular sphinx themes).

An area really critical to sphinx / readthedocs is sphinx.ext.autodoc.

Current theme sphinx.ext.autodoc: http://tmuxp.readthedocs.org/en/latest/api.html

Examples

Current RTD theme: http://django-tastypie.readthedocs.org/en/latest/api.html

Others sphinx.ext.autodoc examples:

• python 3.4: http://docs.python.org/3.4/library/subprocess.html
• python 2 docs: http://docs.python.org/2.7/library/subprocess.html
• cloud_sptheme: http://inasafe.readthedocs.org/en/latest/lib/cloud_sptheme.html
• flask: http://flask.pocoo.org/docs/api/
• django: https://docs.djangoproject.com/en/dev/ref/class-based-views/base/
• sphinx: http://sphinx-doc.org/ext/autodoc.html,

The <dl> lists has a tad too little space between a <dd> element and the next <dt> element.

Example: http://docs.mopidy.com/en/develop/commands/mopidy/#files

Certain characters will render white on white when nesting stuff like this:

.. note::
    Look at this::

        a = {
            'b': {
                'c': "d",
            },
        }

Real world example: http://docs.blockwart.org/en/latest/nodes.py.html

IMHO there's too little spacing between images and succeeding headers.

For an example, go to http://docs.mopidy.com/en/develop/installation/raspberrypi/#how-to-for-raspbian-wheezy-and-debian-wheezy and scroll up a bit.

Example here:
https://libcloud.readthedocs.org/en/latest/supported_providers.html

Should looki into maybe using zurb's solution for this kind of stuff.
http://zurb.com/playground/projects/responsive-tables/index.html

Example: http://django-payments.readthedocs.org/en/latest/modules.html

In #55, an example demonstrates that emphasized lines are shifted rightward. Also, there is an undesired horizontal scrollbar.

A sidebar directive-built sidebar is rendered incorrectly, see for example: http://configs.readthedocs.org/en/latest/#usage

Could you add support for "View source"? (html_show_sourcelink = True in conf.py)

When built locally, we see:

When built on RTD, we see:

Live demo is here. We'd like no scrollbars.

Sphinx has JS that adds highlighting on the page when you search for stuff:

example

An example of it on the Sphinx docs here:

http://sphinx-doc.org/?highlight=python

Currently we don't have any styles for it, so it doesn't display in the theme.

see also is white and on the light gray background is not visible....

http://python-subreg.readthedocs.org/en/latest/api/

I followed the Readme and when I run make html everything builds fine and looks good locally. However the latest build on readthedocs.org has this error.

Making output directory...

Exception occurred:
  File "/var/build/user_builds/epicserve-docs/checkouts/latest/conf.py", line 1, in <module>
    import sphinx_rtd_theme
ImportError: No module named sphinx_rtd_theme
The full traceback has been saved in /tmp/sphinx-err-PNBx0R.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
Either send bugs to the mailing list at <http://groups.google.com/group/sphinx-dev/>,
or report them in the tracker at <http://bitbucket.org/birkenfeld/sphinx/issues/>. Thanks!

So how does one use this theme locally and on the readthedocs.org site?

http://tmuxp.readthedocs.org/en/latest/about_tmux.html

These are default .. aafig:: directives. Aafig will hard code a height and width into the output.

The height: 100% !important is causing the images to stretch.

fields currently have very little style. just white.

i.e. this kind of markup

:Page Status: Incomplete
:Last Reviewed: 2013-10-29

in most sphinx themes, this rendered with a border, and the fields names have a background color. e.g. see the top of https://python-packaging-user-guide.readthedocs.org/en/latest/

Looking at 1 in the top left. I am on a pretty bare OSX Lion install using Firefox

Hi,

the theme works great with two levels but has some problems with 3+ levels. The main problem I see is that it's hard to go back up to the parent document once level 3 is reached or easily see the current position in the doctree since the breadcrumbs only show the root and current page and the menu does not highlight anything (also no parents)

One negative example: https://quodlibet.readthedocs.org/en/latest/guide/tags/tags.html

I've modified the theme for another project:

Here is an example: http://lazka.github.io/pgi-docs/api/ClutterGst_2.0/classes/VideoSink.html

1. Set toctree maxdepth=3 but hide any non current entries in level 3 so only the active page from level 3 is shown.

.wy-menu-vertical li .toctree-l3 {
    display: none;
}

.wy-menu-vertical li .current {
    display: block;
}

2. Extend the breadcrumbs to show all parents to allow easier navigation to the parent document.

<ul class="wy-breadcrumbs">
  <li><a href="{{ pathto(master_doc) }}">Docs</a> &raquo;</li>
  {% for parent in parents %}
  <li></li><a href="{{ parent.link|e }}">{{ parent.title }}</a> &raquo;</li>
  {% endfor %}
  <li><a href="">{{ title }}</a></li>
  ...

@snide nice work!

I tried to apply it to my project, but it looks like PyPI distribution is missing a file:

➜ pip install sphinx_rtd_theme
Downloading/unpacking sphinx-rtd-theme
  Downloading sphinx_rtd_theme-0.1.3.tar.gz
  Running setup.py egg_info for package sphinx-rtd-theme
    Traceback (most recent call last):
      File "<string>", line 16, in <module>
      File "/Users/dvs/.venv/unipag-doc/build/sphinx-rtd-theme/setup.py", line 30, in <module>
        install_requires=open('requirements.txt').read().splitlines(),
    IOError: [Errno 2] No such file or directory: 'requirements.txt'
    Complete output from command python setup.py egg_info:
    Traceback (most recent call last):

  File "<string>", line 16, in <module>

  File "/Users/dvs/.venv/unipag-doc/build/sphinx-rtd-theme/setup.py", line 30, in <module>

    install_requires=open('requirements.txt').read().splitlines(),

IOError: [Errno 2] No such file or directory: 'requirements.txt'

----------------------------------------
Command python setup.py egg_info failed with error code 1 in /Users/dvs/.venv/unipag-doc/build/sphinx-rtd-theme
Storing complete log in /Users/dvs/.pip/pip.log

API docs are currently a bit anemic, with everything looking the same. E.g. classes should be made more visible than a random class member.

For an example, see http://docs.mopidy.com/en/develop/api/models/#module-mopidy.models

let´s take this example:

.. py:class:: FileListing(path, filter_func=None, sorting_by=None, sorting_order=None)

    Returns a list of FileObjects for a given directory, see :ref:`fileobject`.

    :param path: Relative path to a location within `site.storage.location`.
    :param filter_func: Filter function, see example below.
    :param sorting_by: Sort the files by any attribute of FileObject.
    :param sorting_order: Sorting order, either "asc" or "desc".

when rendered, the word "Parameters:" is vertically not aligned with "path" (the first item within parameters). this is only true if you have more than one parameter.

A typical code block might appear as:

<div class="highlight-python">

which is handled by:

div[class^='highlight']

However, Sphinx sometimes represents code blocks as:

<div class="last highlight-python">

And these blocks are not highlighted by the above rule.

When using the sphinx.contrib.viewcode extension together with API docs, you get now nicely styled [source] links from the API docs to the source code. Though, the [docs] links from the source code back to the API docs are not styled, and are aligned to the left of the source code, obstructing the source code view.

Example: http://pyspotify.readthedocs.org/en/v2.x-develop/_modules/spotify/session/#Social

@snide is a winner.

http://tmuxp.readthedocs.org/en/latest/cli.html

This is using @ribozz https://github.com/ribozz/sphinx-argparse plugin.

Right now I ignore the logo if it's set. This is bad.

When images are wider than the page, they are made narrower without making them lower, distorting the image size ratio.

Example: http://docs.mopidy.com/en/develop/clients/http/#mopidy-lux

In the low resolution case with the header centered on top, the title link points to "/" instead to the index. This breaks in case the docs are in a sub directory. It works correctly with the link in the sidebar.

Example: http://lazka.github.io/pgi-docs/

Source links inserted because of the use of html_show_sourcelink should probably be right aligned or similar.

Example: http://docs.mopidy.com/en/develop/api/models/#mopidy.models.Album

See .sidebar on http://tmuxp.readthedocs.org/en/latest/examples.html. (this is according to /static/ css)

1. Alignment

   No CSS yet for .sidebar.

2. height: auto !important seems to stretch my svg image.

   This is generated by aafig.

   .rst-content img {
     max-width: 100%;
     height: auto !important;
   }

Great job on this new theme, it looks awesome!

I've noticed something wrong with the generated CSS for the pre.literal-block:
See in sphinx_rtd_theme/static/css/theme.css:

pre.literal-block{@extends .codeblock;}

As a result, the current .. parsed-literal:: are not styled.