Humdrum Documentation Website

This repository contains documentation for the humdrum tools. The main web interface to the documentation is http://www.humdrum.org , with the low-level address being http://humdrum-tools.github.io .

Downloading

This repository which contains the compiled HTML files and the ReStructured Text source files can be downloaded with this command:

	git clone https://github.com/humdrum-tools/humdrum-tools.github.io

If you have installed the humdrum-tools repository, then you can go into the humdrum-tools directory and type the command:

	make doc

Which will download this repository and store in in the directory humdrum-tools/doc.

Files/directories in the base directory

Filename	Description
.git	Management directory for git.
.gitignore	Files/directories which git should ignore.
.nojekyll	Marker file for GitHub to not use jekyll.
CNAME	Computer name for website access.
Humdrum/	Original HTML files for the Humdrum documentation.
Makefile	Makefile for doing stuff, such as "make doc" to create HTML pages.
README.md	This file.
TODO.txt	List of things to do.
bin/	Support programs/scripts.
html/	Output directory for HTML content generated by Sphinx.
source/	ReStructured Text files used to create HTML documentation.

Additionally, several symbolic links are found in the base directory which link to the compiled HTML content stored in "html" that are created from the source files in "source":

Filename	Description
.buildinfo@
_images@	Directory for storing website's image files
_sources@	Copy of the source ReStructured Text files for viewing on the web.
_static@	Storage directory for RtD theme CSS file.
cookbook@	Humdrum Cookbook HTML documentation.
doctrees@
extras@	Humdrum Extras HTML documentation.
genindex@
guide@	Humdrum Users Guide HTML documentation.
index.html@	Main website HTML index file.
installationguide@	Humdrum tools installation guide.
objects.inv@
referencemanual@	Humdrum Reference manual HTML documentation.
search@
searchindex.js@
userguideIntro@

Compiling website

To compile the website, type the following command:

	make doc

This will process the files in the "source" directory and update the HTML files in the "html" directory. If there is an error compiling the HTML files, you probably need to install Sphinx first, so follow the instructions in the section below.

Installing Sphinx

In order to compile the source files, you need to have Sphinx. How to do this will depend on your OS and local configuration. The basic installation process should be something like this:

• Install sphinx with pip:

	sudo pip install sphinx

• If you have problems installing, try installing pip:

	sudo easy_install pip

• Check to see if sphinx was installed successfully:

	which sphinx-build

which should reply something like this:

	/usr/local/bin/sphinx-build

After Sphinx has been installed, you will also have to install the RtD theme for Sphinx which the documentation uses as a style theme. The RtD theme is available on GitHub from https://github.com/snide/sphinx_rtd_theme .

	sudo pip install sphinx_rtd_theme

Pygments is needed in order to add syntax highlighting:

	sudo pip install pygments

Pandoc is useful for converting content files into RST format used in Sphinx:

	brew install pandoc     # with Homebrew in OS X
	yum install pandoc	# in linux
	apt-get install pandoc  # alternate method in linux

Example conversions, where -f means from and -t means to:

	# Covert HTML files into rst files:
	pandoc -f html -t rst file.html > file.rst

	# Covert Wikipedia wiki files into rst files:
	pandoc -f mediawiki -t rst file.wiki > file.rst