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 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.
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.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
.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>',]
.
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.
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.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
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
Built Distribution
Hashes for sphinx_html5_basic_theme-1.0.5.zip
Algorithm | Hash digest | |
---|---|---|
SHA256 | 713d77f464704daf7111f92f52210b48f842e3e8c218bdce7ec22e7cd1cefb87 |
|
MD5 | e86727a9af8f269d058e85c3707a7973 |
|
BLAKE2b-256 | 5f4d2c73573b360714ffb32da245e13513bc6d9c2d68d6ae5d13eeb61df7761b |
Hashes for sphinx_html5_basic_theme-1.0.5-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ede13a56a7976d9210b71deb70c7915caf3b0d159419be9f8d15da636553fbfe |
|
MD5 | 947ea121180ed7a585cfe03ce45a0280 |
|
BLAKE2b-256 | 1dda3e7ba18c6373ab8bc9124c3997a30c4e41c10d9b348560fb34b172fc18cd |