As I've announced a few times in the past, I want to add proper
theming support to Sphinx 0.6.
I've written a proposal outlining my intended implementation, below.
I'm glad about every comment and criticism.
Thanks,
Georg
============================
Sphinx HTML theming proposal
============================
:author: Georg Brandl
:date: 20 December 2008
* Themes are an important issue: if theming is easy, more themes will be
developed and shared
* Theming must be easy, but not limited
Definition: Theme
-----------------
* Collection of:
- HTML templates
- Stylesheet(s)
- Other static files, like graphics and JavaScript files
- Highlighting style
* Not project-specific (shouldn't need to contain e.g. logo)
* Supports all possible configurations
Current state of affairs
------------------------
* Some themes distributed with Sphinx: default, sphinxdoc, traditional,
rightsidebar, stickysidebar
* ... but not marked as themes, neither clearly documented how to use different
theme
* Settings (distantly) related to theme support:
- ``templates_path``
- ``template_bridge``
- ``html_static_path``
- ``html_style``
- ``pygments_style``
(most others are project-specific)
* Custom theme not clearly separated from project-specific customization (logo,
favicon etc.)
Goals
-----
* For projects using default theme, no change in conf.py required
* For projects using custom themes with current possibilities, no breakage
occurs
* Creating themes is easy
* Distributing themes is easy
Proposal, part 1: Theme format
------------------------------
* Theme: Directory or zip file
* Contains ``theme.cfg``, with this format::
[theme]
inherit = base theme
stylesheet = main CSS name
pygments_style = stylename or custom
[templating]
variable = default value
...
[pygments]
tokentype = stylespec
...
* Contains templates at root, static files in ``static/``
* Base theme is used to locate missing templates
* Templates can use ``{% extends "themename/template.html" %}`` to extend a
specific template
Proposal, part 2: Sphinx distribution
-------------------------------------
* Switch to Jinja 2 as templating engine
* Remove ``sphinx/templates`` and ``sphinx/static``
* Create ``sphinx/themes``, and a subdirectory for each theme -- those mentioned
above, plus a very simple one: "basic"
* Move stylesheets and templates into right place
* Write theming support code into new Jinja 2 template bridge
Proposal, part 3: Custom themes
-------------------------------
* New config values: ``html_theme``, ``html_theme_path``
* ``html_theme`` selects theme by name (builtin or custom)
* ``html_theme_path`` adds directories containing themes, relative to root dir
Backwards compatibility
-----------------------
* Template inheritance via ``!base.html`` refers to template in base theme
* Default theme and default base theme is "default"
* ``template_bridge`` still works (other template bridge will completely ignore
theme support)
* ``templates_path`` still works and has precedence over theme paths
* ``html_style`` still works and has precendece over theme setting
* ``html_static_path`` still works and is copied over after theme static files
* Jinja1-only syntax may require minor adjustments to custom templates
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"sphinx-dev" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to
[email protected]
For more options, visit this group at
http://groups.google.com/group/sphinx-dev?hl=en
-~----------~----~----~----~------~----~------~--~---
