refs #1346. Add new default theme.

- Rename 'default' theme to 'classic'.
  - rename `themes/default` to `themes/classic`
  - add new `themes/default` theme that derives from 'classic' theme for compatibility.
- setup.py depends to 'alabaster' and 'rtd' theme.
- theming.py import and run `alabaster.get_path()` to append path for alabaster theme.
- theming.py also import and run `sphinx_rtd_theme.get_html_theme_path()` to append path.
- sphinx-quickstart will generate `html_theme = 'alabaster'`.
- If user use 'default', sphinx emit notice (WARNING) suggestion to use 'alabaster' or use 'classic'.
- add documentation for new alabaster and readthedoc theme and link to original pages:
  - https://pypi.python.org/pypi/alabaster
  - https://pypi.python.org/pypi/sphinx_rtd_theme

CHANGES

@@ -13,6 +13,14 @@ Incompatible changes
 Features added
 --------------
 
+* #1346: Add new default theme;
+
+  * Add 'alabaster' theme.
+  * Add 'sphinx_rtd_theme' theme.
+  * The 'default' html theme has been renamed to 'classic'. 'default' is still
+    available, however it will emit notice a recommendation that using new
+    'alabaster' theme.
+
 * Added ``highlight_options`` configuration value.
 * The ``language`` config value is now available in the HTML templates.
 * The ``env-updated`` event can now return a value, which is interpreted

doc/config.rst

@@ -516,7 +516,7 @@ that use Sphinx's HTMLWriter class.
 .. confval:: html_theme
 
    The "theme" that the HTML output should use.  See the :doc:`section about
-   theming <theming>`.  The default is ``'default'``.
+   theming <theming>`.  The default is ``'alabaster'``.
 
    .. versionadded:: 0.6
 

doc/theming.rst

@@ -24,13 +24,13 @@ need to set the :confval:`html_theme` config value.  With the
 that change the look and feel.  For example, you could have the following in
 your :file:`conf.py`::
 
-    html_theme = "default"
+    html_theme = "classic"
     html_theme_options = {
         "rightsidebar": "true",
         "relbarbgcolor": "black"
     }
 
-That would give you the default theme, but with a sidebar on the right side and
+That would give you the classic theme, but with a sidebar on the right side and
 a black background for the relation bar (the bar with the navigation links at
 the page's top and bottom).
 
@@ -86,9 +86,13 @@ Builtin themes
 +--------------------+--------------------+
 | **Theme overview** |                    |
 +--------------------+--------------------+
-| |default|          | |sphinxdoc|        |
+| |alabaster|        | |sphinx_rtd_theme| |
 |                    |                    |
-| *default*          | *sphinxdoc*        |
+| *alabaster*        | *sphinx_rtd_theme* |
++--------------------+--------------------+
+| |classic|          | |sphinxdoc|        |
+|                    |                    |
+| *classic*          | *sphinxdoc*        |
 +--------------------+--------------------+
 | |scrolls|          | |agogo|            |
 |                    |                    |
@@ -107,18 +111,22 @@ Builtin themes
 | *bizstyle*         |                    |
 +--------------------+--------------------+
 
-.. |default|     image:: themes/default.png
-.. |sphinxdoc|   image:: themes/sphinxdoc.png
-.. |scrolls|     image:: themes/scrolls.png
-.. |agogo|       image:: themes/agogo.png
-.. |traditional| image:: themes/traditional.png
-.. |nature|      image:: themes/nature.png
-.. |haiku|       image:: themes/haiku.png
-.. |pyramid|     image:: themes/pyramid.png
-.. |bizstyle|    image:: themes/bizstyle.png
+.. |alabaster|        image:: themes/alabaster.png
+.. |sphinx_rtd_theme| image:: themes/sphinx_rtd_theme.png
+.. |classic|          image:: themes/classic.png
+.. |sphinxdoc|        image:: themes/sphinxdoc.png
+.. |scrolls|          image:: themes/scrolls.png
+.. |agogo|            image:: themes/agogo.png
+.. |traditional|      image:: themes/traditional.png
+.. |nature|           image:: themes/nature.png
+.. |haiku|            image:: themes/haiku.png
+.. |pyramid|          image:: themes/pyramid.png
+.. |bizstyle|         image:: themes/bizstyle.png
 
 Sphinx comes with a selection of themes to choose from.
 
+.. cssclass:: clear
+
 These themes are:
 
 * **basic** -- This is a basically unstyled layout used as the base for the
@@ -132,7 +140,21 @@ These themes are:
   - **sidebarwidth** (an integer): Width of the sidebar in pixels.  (Do not
     include ``px`` in the value.)  Defaults to 230 pixels.
 
-* **default** -- This is the default theme, which looks like `the Python
+* **alabaster** -- `Alabaster theme`_ is a modified "Kr" Sphinx theme from @kennethreitz
+  (especially as used in his Requests project), which was itself originally based on
+  @mitsuhiko's theme used for Flask & related projects. You can get options information
+  at `Alabaster theme`_ page.
+
+  .. _Alabaster theme: https://pypi.python.org/pypi/alabaster
+
+* **sphinx_rtd_theme** -- `Read the Docs Sphinx Theme`_.
+  This is a mobile-friendly sphinx theme that was made for readthedocs.org.
+  View a working demo over on readthedocs.org. You can get options information
+  at `Read the Docs Sphinx Theme`_ page.
+
+  .. _Read the Docs Sphinx Theme: https://pypi.python.org/pypi/sphinx_rtd_theme
+
+* **classic** -- This is the classic theme, which looks like `the Python
   documentation <https://docs.python.org/>`_.  It can be customized via these
   options:
 
@@ -249,8 +271,12 @@ These themes are:
     Defaults to ``False``.
 
 .. versionadded:: 1.3
-   'bizstyle' theme.
+   'alabaster', 'sphinx_rtd_theme' and 'bizstyle' theme.
 
+.. versionchanged:: 1.3
+   The 'default' theme has been renamed to 'classic'. 'default' is still
+   available, however it will emit notice a recommendation that using new
+   'alabaster' theme.
 
 Creating themes
 ---------------
@@ -324,10 +350,10 @@ so-called "static templates", like this:
 If the name of a file in the ``static/`` directory of a theme (or in the user's
 static path, for that matter) ends with ``_t``, it will be processed by the
 template engine.  The ``_t`` will be left from the final file name.  For
-example, the *default* theme has a file ``static/default.css_t`` which uses
+example, the *classic* theme has a file ``static/classic.css_t`` which uses
 templating to put the color options into the stylesheet.  When a documentation
-is built with the default theme, the output directory will contain a
-``_static/default.css`` file where all template tags have been processed.
+is built with the classic theme, the output directory will contain a
+``_static/classic.css`` file where all template tags have been processed.
 
 
 .. [1] It is not an executable Python file, as opposed to :file:`conf.py`,

setup.py

@@ -52,6 +52,8 @@ requires = [
     'docutils>=0.11',
     'snowballstemmer>=1.1',
     'babel',
+    'alabaster',
+    'sphinx_rtd_theme',
 ]
 extras_require = {
     # Environment Marker works for wheel 0.24 or later

sphinx/application.py

@@ -131,6 +131,12 @@ class Sphinx(object):
         if self.confdir is None:
             self.confdir = self.srcdir
 
+        # extension loading support for alabaster theme
+        # self.config.html_theme is not set from conf.py at here
+        # for now, sphinx always load a 'alabaster' extension.
+        if 'alabaster' not in self.config.extensions:
+            self.config.extensions.append('alabaster')
+
         # load all user-given extension modules
         for extension in self.config.extensions:
             self.setup_extension(extension)

sphinx/builders/html.py

@@ -137,7 +137,7 @@ class StandaloneHTMLBuilder(Builder):
         Theme.init_themes(self.confdir, self.config.html_theme_path,
                           warn=self.warn)
         themename, themeoptions = self.get_theme_config()
-        self.theme = Theme(themename)
+        self.theme = Theme(themename, warn=self.warn)
         self.theme_options = themeoptions.copy()
         self.create_template_bridge()
         self.templates.init(self, self.theme)

sphinx/config.py

@@ -82,7 +82,7 @@ class Config(object):
                          'env'),
 
         # HTML options
-        html_theme = ('default', 'html'),
+        html_theme = ('alabaster', 'html'),
         html_theme_path = ([], 'html'),
         html_theme_options = ({}, 'html'),
         html_title = (lambda self: l_('%s %s documentation') %

sphinx/quickstart.py

@@ -177,7 +177,7 @@ todo_include_todos = %(ext_todo)s
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+html_theme = 'alabaster'
 
 # 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

sphinx/themes/classic/theme.conf

@@ -0,0 +1,32 @@
+[theme]
+inherit = basic
+stylesheet = classic.css
+pygments_style = sphinx
+
+[options]
+rightsidebar = false
+stickysidebar = false
+collapsiblesidebar = false
+externalrefs = false
+
+footerbgcolor    = #11303d
+footertextcolor  = #ffffff
+sidebarbgcolor   = #1c4e63
+sidebarbtncolor  = #3c6e83
+sidebartextcolor = #ffffff
+sidebarlinkcolor = #98dbcc
+relbarbgcolor    = #133f52
+relbartextcolor  = #ffffff
+relbarlinkcolor  = #ffffff
+bgcolor          = #ffffff
+textcolor        = #000000
+headbgcolor      = #f2f2f2
+headtextcolor    = #20435c
+headlinkcolor    = #c60f0f
+linkcolor        = #355f7c
+visitedlinkcolor = #355f7c
+codebgcolor      = #eeffcc
+codetextcolor    = #333333
+
+bodyfont = sans-serif
+headfont = 'Trebuchet MS', sans-serif

sphinx/themes/default/theme.conf

@@ -1,32 +1,2 @@
 [theme]
-inherit = basic
-stylesheet = default.css
-pygments_style = sphinx
-
-[options]
-rightsidebar = false
-stickysidebar = false
-collapsiblesidebar = false
-externalrefs = false
-
-footerbgcolor    = #11303d
-footertextcolor  = #ffffff
-sidebarbgcolor   = #1c4e63
-sidebarbtncolor  = #3c6e83
-sidebartextcolor = #ffffff
-sidebarlinkcolor = #98dbcc
-relbarbgcolor    = #133f52
-relbartextcolor  = #ffffff
-relbarlinkcolor  = #ffffff
-bgcolor          = #ffffff
-textcolor        = #000000
-headbgcolor      = #f2f2f2
-headtextcolor    = #20435c
-headlinkcolor    = #c60f0f
-linkcolor        = #355f7c
-visitedlinkcolor = #355f7c
-codebgcolor      = #eeffcc
-codetextcolor    = #333333
-
-bodyfont = sans-serif
-headfont = 'Trebuchet MS', sans-serif
+inherit = classic

sphinx/theming.py

@@ -26,6 +26,8 @@ except ImportError:
 from sphinx import package_dir
 from sphinx.errors import ThemeError
 
+import alabaster
+import sphinx_rtd_theme
 
 NODEFAULT = object()
 THEMECONF = 'theme.conf'
@@ -68,23 +70,41 @@ class Theme(object):
                 cls.themes[tname] = (path.join(themedir, theme), tinfo)
 
     @classmethod
-    def load_extra_themes(cls):
+    def load_extra_theme(cls, name):
+        if name == 'alabaster':
+            cls.themes[name] = (os.path.join(alabaster.get_path(), name), None)
+            # alabaster theme also requires 'alabaster' extension, it will be loaded at
+            # sphinx.******* module.
+            return
+
+        if name == 'sphinx_rtd_theme':
+            cls.themes[name] = (
+                os.path.join(sphinx_rtd_theme.get_html_theme_path(), name), None)
+            return
+
         for themedir in load_theme_plugins():
             if not path.isdir(themedir):
                 continue
             for theme in os.listdir(themedir):
+                if theme != 'name':
+                    continue
                 if not path.isfile(path.join(themedir, theme, THEMECONF)):
                     continue
                 cls.themes[theme] = (path.join(themedir, theme), None)
+                return
 
-    def __init__(self, name):
+    def __init__(self, name, warn=None):
         if name not in self.themes:
-            self.load_extra_themes()
+            self.load_extra_theme(name)
             if name not in self.themes:
                 raise ThemeError('no theme named %r found '
                                  '(missing theme.conf?)' % name)
         self.name = name
 
+        if name == 'default' and warn:
+            warn("'default' html theme has been renamed to 'classic'. "
+                 "Please rename it to 'alabaster' new theme or 'classic'.")
+
         tdir, tinfo = self.themes[name]
         if tinfo is None:
             # already a directory, do nothing
@@ -117,7 +137,7 @@ class Theme(object):
             raise ThemeError('no theme named %r found, inherited by %r' %
                              (inherit, name))
         else:
-            self.base = Theme(inherit)
+            self.base = Theme(inherit, warn=warn)
 
     def get_confstr(self, section, name, default=NODEFAULT):
         """Return the value for a theme configuration setting, searching the