Sphinx HTML5 basic theme

Caution

‘html5_sphinxdoc’ will not work until the bug is resolved. ‘html5_basic’ theme and ‘sphinx_html5_translator’ extension go fine.

If you want to use ‘html5_sphinxdoc’, add the path to ‘html_theme’. see ‘doc/conf.py’.

Note

Japanese version of this document is also available, on the site or the doc folder of this package.

Introduction

Currently, May 6, 2015, Sphinx 1.3.1 cannot generate valid HTML5 files1.

This package includes HTML5 and CSS3 versions of the two standard themes, basic and sphinxdoc. And one extension, named 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(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, <python_installed_path>\Scripts\pip.exe install sphinx_html5_basic_theme.

  2. Or when you get zip archive like 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, <python_installed_path>\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 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 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 = ['<path_to_(themes_)folder>',].

Note

As described the top of this document, you should declare html_theme_path anyway, above until the bug is fixed.

2) set the html5 translator extension

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

to use sphinx_html5_translator, you should add the path to the extension to sys.path like below, at the early part of your 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, '<path_to_(extensions_)folder>')

Note that <path_to_(themes_)forder> and <path_to_(extensions_)folder> is same as the case of this package.

Note

If you don’t mind or want to do, you can copy the file sphinx_html5_translator.py to the folder you want, add sys.path.insert(0, '<the_folder_you_copied_the_extension_file>'), and set the valuable extension like above.

Changes against html4 version

  • Uses CSS3, but some modules are not W3C Reccomendation yet.
  • Flexible Box Layouts used
    • relational navigations
    • sidebar box and main contents box
    • input box and go button in quick search
  • Multi-column Layout used
    • 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

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 https://github.com/pypa/pip/pull/2916

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

1W3C Markup Validation Service