Enable Sphinx to generate HTML5 valid files
Project description
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 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 overwrite the Sphinx project.
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.
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
.Or when you get zip archive like sphinx_html5_basic_theme-1.0.0(.zip) where ‘1.0.0’ is version number, change current directiory to the folder that has the zip file, and do
setup.py sphinx_html5_basic_theme-1.0.0.zip
.On the MS-Windows,
<python_installed_path>\Scripts\pip.exe install sphinx_html5_basic_theme-1.0.0.zip
.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.
If you install this package using one of easy_install
, pip
or
setup.py
, just fix html_theme
and extensions
on
your conf.py. If not, you should do more, add
sys.path.insert(0, '<path_to_(extensions_)folder>')
and
html_theme_path = ['<path_to_(themes_)forder>',]
. Note that both
folders are same for this package.
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.
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 append the code into the early part of your conf.py:
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 add to the extension like extension = ['sphinx_html5_translator', ]
.
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
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 stylegenindex-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
andup
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.
History
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
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Hashes for sphinx_html5_basic_theme-1.0.1.zip
Algorithm | Hash digest | |
---|---|---|
SHA256 | 466bb5359d4139713258ba983342ffa7bbad31235d2826101fa0bb61d0ab4de5 |
|
MD5 | 859c46b4bcc8c2c9b69c012a3d1e82e8 |
|
BLAKE2b-256 | 759f6db972244ae3179dfa10620f6697beb48830c7363bc47b0edce0de812254 |