Sphinx to GitHub
This project is designed to help you get around the github-pages Jekyll behaviour of ignoring top level directories starting with an underscore.
This makes this project largely useless! Thank you to acdha for making me aware of this.
A Python script for preparing the html output of the Sphinx documentation system for github pages.
It renames any top level folders which start with an underscore and edits any references to them within the html files.
GitHub processes the incoming html with Jekyll which believes top level folders starting with an underscore are special and does not let their content be accessible to the server. This is incompatible with Sphinx which uses underscores at the start of folder names for static content.
sphinxtogithub.py script can be run on the command line or used as a
Place the script on the
PYTHONPATH and add
sphinxtogithub to the
extensions list in the
conf.py file in your Sphinx project:
extensions = [ "sphinxtogithub" ]
Additionally there are three config variables you can use to control the
extension. The first enables/disables the extension, the second enables verbose
output and the third determines the encoding which is used to read & write
files. The first two are
True by default and the third is set to
sphinx_to_github = True sphinx_to_github_verbose = True sphinx_to_github_encoding = "utf-8"
Run the script with the path to the
html output directory as the first
argument. There is a
--verbose flag for basic output.
Install from GitHub
It should be possible to install this tool directly from github using pip:
pip install -e git+git://github.com/michaeljones/sphinx-to-github.git#egg=sphinx-to-github
Thanks to winhamwr's work.
The script uses
Unit tests can be run using the setuptools
test target. eg:
$ python setup.py test
Thank you to:
For their contributions, which are beginning to outweigh mine, to Georg Brandl for Sphinx and the github crew for the pages functionality.