Sphinx HTML5 basic theme

Introduction

Currently, May 6, 2015, Sphinx 1.3.1 cannot generate valid HTML5 files[1].

This package includes HTML5 and CSS3 versions of the two standard themes, basic and sphinxdoc. And one extension, named :fn_rst:sphinx_html5_translator(.py).

By using them, you can generate HTML files that will pass the validator. Enjoy!

License

BSD, same as the Sphinx project itself. (All files are intend to enable merge or enable overwrite the Sphinx project for the future.)

Installation

You can install or uninstall this package like another Python packages. Also, you can use this package without installing this package on your Python systems, the configuration file of Sphinx(:fn_rst:conf.py) enable you to use.

Requirements

• Sphinx 1.3 compatible
  • docutils 0.12 compatible
  • note that their changes may or may not break the functionality of the code in this packages, as the one in another packages may.
• tested with: 32bit version of Python 2.7.9 and 64bit version of 3.4.3, both on the Microsoft Windows 8.1 Pro 64bit edition
  • but with another versions and on another OSs would be usable

How to install

Again, you can install this package as you will do with another one.

1. Open a console and do pip install sphinx_html5_basic_theme.

   On the MS-Windows, \Scripts\pip.exe install sphinx_html5_basic_theme.

2. Or when you get zip archive like :fn_rst:sphinx_html5_basic_theme-1.0.5(.zip) where '1.0.5' is version number, change current directiory to the folder that has the zip file, and do pip install sphinx_html5_basic_theme-1.0.5.zip.

   On the MS-Windows, \Scripts\pip.exe install sphinx_html5_basic_theme-1.0.5.zip.

3. Or, this way is the Sphinx specific, you can use this package just extracted any folder you want. the :fn_rst:conf.py enables you to use the themes and extensions.

How to use

Do you already know how to switch HTML theme and to use extension ? if not, learn them first.

1) set the html5 theme

At first, you should choice the theme html5_basic or html5_sphinxdoc. The latter refers the former, but you don't have to care about that as the structure of the folders resolves.

On the :fn_rst:conf.py in your project(s), fix html_theme like html_theme = 'html5_sphinxdoc' as you choise.

If you want to use this package just extracted zip and not installed on your python system, you should do more, add html_theme_path = ['',].

2) set the html5 translator extension

Second, you should use the extension :fn_rst:sphinx_html5_translator(.py). Because some invalid tags and attributes are emitted by docutils.

to use :fn_rst:sphinx_html5_translator, you should add the path to the extension to sys.path like below, at the early part of your :fn_rst:conf.py. This part is different whether this package is installed on the Python system or not.

After that, set the extension as extension = ['sphinx_html5_translator', ]. Of course you can add another extensions you want to use.

Add the path for installed this package:

# add 3 lines below
import distutils.sysconfig
site_package_path = distutils.sysconfig.get_python_lib()
sys.path.insert(0, os.path.join(site_package_path, 'sphinx_html5_basic_theme'))

and for not installed this package:

# add just 1 line below
sys.path.insert(0, '')

Note that and is same as the case of this package.

Changes against html4 version

• Uses CSS3, but some modules are not W3C Reccomendation yet.
  • Flexible Box Layout Module Level 1 is last call working draft
  • Multi-column Layout Module is cadidate reccomendation
• Flexible Box Layouts used
  • relational navigations
  • sidebar box and main contents box
  • input box and go button in quick search
• Multi-column Layout used
  • :fn_rst:genindex.html. you can change column count with style sheet.
• sidebarwidth is now accepts unit postfix, like "50em"
• the sidebar is displayed even sphinx_html5_basic
• width defition of the quick search button is deleted. that is too narrow to show the translations of 'Go !'
• table.indextable is replaced with Flexible Box Layout. The new style genindex-multi-columens is added.
• Some brakets and markers are removed, intend to use style sheets.
  • relational navigations (» and |)
  • separators between head characters in index pages(|)
  • brakets with footnote and common named index([ and ])
• {% block searchtip %} is defined, to replace the description of the quick search
• {% block extra_footer %} is defined, to append something at last of the footer
• {% expired_html_link %} is defined and emit nothing. top and up is obsoleted.
• images used with sphinxdoc theme is deleted. altered with style sheet.
• the separator lines designed with sphinxdoc now always touch the top of the footer, even when the main content is too short.

Author

Suzumizaki-Kimitaka, 2015-04-30

Related products

• unicode_ids
  • enable the Sphinx to generate URL with Non-ASCII characters.

History

1.0.5(2015-06-19):

> - add wheel build for install. > - work around added in doc/conf.py until resolve the bug of Sphinx. > - work around against setup.py due to the bug of pip running on > Python 3. see

1.0.4(2015-05-25):

> fix document about the project extension folder.

1.0.3(2015-05-10):

> fix how to use chapter.

1.0.2(2015-05-10):

> Re-upload

1.0.1(2015-05-10):

> Add README.rst to doc folder that lost from the previous version.

1.0.0(2015-05-09):

> First release. All files are copied at first from Sphinx 1.3.1 and > docutils 0.12 with Python 2.7.9 and 3.4.3 on Microsoft Windows 8.1 Pro > 64bit. > > the themes html5_basic and html5_sphinxdoc are released. the > extension sphinx_html5_translator is released.

Footnote

[1] W3C Markup Validation Service