Merge branch 'sphinx-basic-updates' of github.com:tony/sphinx_rtd_theme into tony-sphinx-basic-updates

Conflicts:
	src/sphinx_rtd_theme/static/theme.css

demo_docs/source/conf.py

@@ -13,6 +13,9 @@
 
 import sys, os
 
+sys.path.append(os.path.abspath('.'))
+sys.path.append(os.path.abspath('./test_py_module'))
+
 # 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.
@@ -25,7 +28,7 @@ import sys, os
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = []
+extensions = ['sphinx.ext.autodoc',]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

demo_docs/source/index.rst

@@ -13,6 +13,55 @@ Contents:
 
 test
 
+API Test
+========
+
+.. automodule:: test_py_module.test
+    :members:
+    :private-members:
+    :special-members:
+
+Code test
+=========
+
+.. code-block:: json
+
+    {
+    "windows": [
+        {
+        "panes": [
+            {
+            "shell_command": [
+                "echo 'did you know'", 
+                "echo 'you can inline'"
+            ]
+            }, 
+            {
+            "shell_command": "echo 'single commands'"
+            }, 
+            "echo 'for panes'"
+        ], 
+        "window_name": "long form"
+        }
+    ], 
+    "session_name": "shorthands"
+    }
+
+Sidebar
+=======
+
+.. sidebar:: Ch'ien / The Creative
+
+    .. image:: static/yi_jing_01_chien.jpg
+
+    *Above* CH'IEN THE CREATIVE, HEAVEN
+
+    *Below* CH'IEN THE CREATIVE, HEAVEN
+
+The first hexagram is made up of six unbroken lines. These unbroken lines stand for the primal power, which is light-giving, active, strong, and of the spirit. The hexagram is consistently strong in character, and since it is without weakness, its essence is power or energy. Its image is heaven. Its energy is represented as unrestricted by any fixed conditions in space and is therefore conceived of as motion. Time is regarded as the basis of this motion. Thus the hexagram includes also the power of time and the power of persisting in time, that is, duration.
+
+The power represented by the hexagram is to be interpreted in a dual sense in terms of its action on the universe and of its action on the world of men. In relation to the universe, the hexagram expresses the strong, creative action of the Deity. In relation to the human world, it denotes the creative action of the holy man or sage, of the ruler or leader of men, who through his power awakens and develops their higher nature.
+
 Indices and tables
 ==================
 

demo_docs/source/test_py_module/test.py

@@ -0,0 +1,52 @@
+# -*- coding: utf-8 -*-
+
+class Foo:
+    """Docstring for class Foo."""
+
+    #: Doc comment for class attribute Foo.bar.
+    #: It can have multiple lines.
+    bar = 1
+
+    flox = 1.5   #: Doc comment for Foo.flox. One line only.
+
+    baz = 2
+    """Docstring for class attribute Foo.baz."""
+
+    def __init__(self, qux, spam=False):
+        """Start the Foo.
+
+        :param qux: The first argument to initialize class.
+        :type qux: string
+        :param spam: Spam me yes or no...
+        :type spam: bool
+
+        """
+        #: Doc comment for instance attribute qux.
+        self.qux = 3
+
+        self.spam = 4
+        """Docstring for instance attribute spam."""
+
+    def add(self, val1, val2):
+        """Return the added values.
+
+        :param val1: First number to add.
+        :type val1: int
+        :param val2: Second number to add.
+        :type val2: int
+        :rtype: int
+
+        """
+
+        return val1 + val2
+
+    def capitalize(self, myvalue):
+        """Return a string as uppercase.
+
+        :param myvalue: String to change
+        :type myvalue: string
+        :rtype: string
+
+        """
+
+        return myvalue.upper()

sass/_theme_rst.sass

@@ -1,8 +1,12 @@
 .rst-content
   // sometimes people provide sizing in their rst, while will break the responsive layout
+  // - the role/directive does. there is no workaround for that. it's true the output of
+  //   rst is not aiding to designers, however it can be depended on that ::image, ::figure
+  //   and ::aafig is going to output dimensions (either via style="" or width/height in html)
   img
-    max-width: 100%
-    height: auto !important
+    max-width: none
+    // max-width: 100% // causes img in ::sidebar to take up space
+    // height: auto !important // makes ::aafig directives stretch
   .section > img
     margin-bottom: $base-line-height
   .note, .attention, .caution, .danger, .error, .hint, .important, .tip, .warning
@@ -68,9 +72,72 @@
     .field-body
       text-align: left
       padding-left: 0
+  /* -- code displays ---------------------------------------------------------
+
+  div[class^='highlight']
+    // override width: 100% from another sass file
+    // 100% makes code-block:: that up .sidebar space
+    width: auto
+
+  pre
+    overflow: auto
+    overflow-y: hidden
+    /* fixes display issues on Chrome browsers
+
+  td.linenos pre
+    padding: 5px 0px
+    border: 0
+    background-color: transparent
+    color: #aaa
+
+  table.highlighttable
+    margin-left: 0.5em
+    td
+      padding: 0 0.5em 0 0.5em
+
+  tt
+    &.descname
+      background-color: transparent
+      font-weight: bold
+      font-size: 1.2em
+    &.descclassname
+      background-color: transparent
+    &.xref
+      background-color: transparent
+      font-weight: bold
+
+  a tt
+    background-color: transparent
+    font-weight: bold
+
+  h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt
+    background-color: transparent
+
+  .viewcode-link
+    float: right
+
+  .viewcode-back
+    float: right
+    font-family: sans-serif
+
+  div.viewcode-block:target
+    margin: -1px -10px
+    padding: 0 10px
+
+  /* -- sidebars --------------------------------------------------------------
+
+  div.sidebar
+    margin: 0 0 0.5em 1em
+    padding: 7px 7px 0 7px
+    width: 40%
+    float: right
+
+  p.sidebar-title
+    font-weight: bold
+
+  /* -- until we find best place to apply -------------------------------------
   dl
     dt
-      @extend code
       display: inline-block
       margin: $base-line-height / 4 0
       font-size: 80%
@@ -93,7 +160,6 @@
 
   dl dl
     dt
-      @extend code
       display: inline-block
       margin-bottom: $base-line-height / 4
       font-size: 80%