Merge pull request #154 from n8willis/sphinx

Merging in static-HTML-output support.

To build the HTML doc set locally, see the BUILD.md file. You will need Sphinx and a handful of common Sphinx extensions.

Further work is going to target HTML as the primary format, with the on-GitHub-site-repo-view rendering as secondary.

Note also that the HTML output, when built, carries with it several software licenses (for Sphinx and some of its dependencies. There is a full list within the _build/ directory itself. If I left anything off, please feel free to point it out or just submit a patch.

.gitignore

@@ -1,2 +1,3 @@
 # Ignore Unicode PDFs & misc resources
 reference/
+_build/

BUILD.md

@@ -0,0 +1,102 @@
+# Building a local copy of these documents #
+
+A local, static-HTML version of these documents can be built with the
+[Sphinx](https://www.sphinx-doc.org/) generator.
+
+The Sphinx-related files in the repository are:
+```
+config.py
+index.rst
+make.bat
+Makefile
+```
+
+plus the directories
+```
+_build/
+_static/
+_templates/
+```
+
+## Sphinx ##
+
+Sphinx is a Python-based utility that you will need to install on your
+local machine. The official [installation
+guide](https://www.sphinx-doc.org/en/master/usage/quickstart.html)
+covers what is necessary for a variety of OSes and
+environments. Perhaps the easiest approach is to install Sphinx in a
+Python [virtual
+enviornment](https://www.sphinx-doc.org/en/master/usage/installation.html#using-virtual-environments). 
+
+After installing Sphinx itself, you will also need to install the
+[MyST-Parser](https://myst-parser.readthedocs.io/en/latest/) package,
+which enables Sphinx to process Markdown files. Using the
+virtual-environment installation method, you can keep both of these
+packages contained for this project.
+
+At the moment there are two other dependencies involved, both of which
+are Sphinx-extension packages:
+
+1. [sphinx-multitoc-numbering](https://sphinx-multitoc-numbering.readthedocs.io/),
+   which is required to make Sphinx use a continuous numbering scheme
+   across the files
+
+2. [sphinx_external_toc](https://sphinx-external-toc.readthedocs.io/),
+   which is required to define the navigation sidebar declaratively
+   (see the [TOCtrees](#toctrees) subsection below for more info)
+
+but a full `build-requirements.txt` file is included in the repository
+that lists the packages in the author's virtual environment. You
+shouldn't _need_ to utilize it, since just installing Sphinx,
+MyST-Parser, and the extensions ought to suffice, but it is there if
+required.
+
+
+## Building HTML documents ##
+
+With the Sphinx and MyST-Parser packages installed, go to the
+top-level directory of this repository in a shell or
+terminal. Building the HTML documents should only take two steps:
+
+1. Run `make clean` to clear out all temporary files from previous
+   run. Do this every time.
+
+2. Run `make html` to regenerate the HTML files. The output files will
+   be written to the `_build/html/` subdirectory.
+
+
+## Editing and bugfixing ##
+
+The static-HTML version of the docs are a work-in-progress at the
+moment, so please do poke around for problems and report any bugs.
+
+Basic Sphinx configuration is done in the `config.py` file.
+
+The HTML output documents are currently using the "Alabaster" theme,
+which comes preinstalled. The Alabaster theme accepts several
+configuration options which are also kept in `config.py`. Output
+customization for the theme is also tweaked in the `custom.css` file
+in the `_static/` subdirectory (just be sure you edit the one in
+`_static/` itself; whenever the docs are rebuilt with `make`, that
+file also gets copied into `_build/html/_static/`, so don't edit that
+copy of the file since it gets overwritten).
+
+
+### TOCtrees ###
+
+Sphinx, by default, is hardcoded in a way that requires all documents
+to be referenced in a separate, Sphinx-specific `toctree` structure,
+after which the navigation sidebars (and other elements) are generated
+on-the-fly at build-time by Sphinx itself.
+
+The current documents are using a third-party extension that defines
+the "TOCtree" in a declarative YAML file instead, to work around some
+undesirable outputs -- mainly in the GitHub repository views -- that
+Sphinx triggers with its on-the-fly `toctree` process.
+
+But this approach isn't (yet?) perfect. Some files (namely this one,
+`BUILD.md`, and the image-generation-log files) are manually excluded
+from the build process so that they do not generate a flurry of
+warning messages. That's deliberate, because the build instructions
+and log files are metadata and aren't part of the final documentation
+set itself.

Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

README.md

@@ -17,7 +17,7 @@ _<aside>Thanks also to the developers of HarfBuzz and AllSorts, plus many other
 
 At present, we are seeking comments and bugfixes on the Indic-script,
 Arabic-like, Hangul, Hebrew, Thai/Lao, Tibetan, Khmer, Myanmar,
-default, and USE documents. Interested readers and contributors can
+default, and <abbr>USE</abbr> documents. Interested readers and contributors can
 begin at the
 
   - [Indic General](opentype-shaping-indic-general.md) 
@@ -31,7 +31,7 @@ begin at the
   - [Thai and Lao](opentype-shaping-thai-lao.md)
   - [Tibetan](opentype-shaping-tibetan.md)
   - [Myanmar](opentype-shaping-myanmar.md)
-  - [Universal Shaping Engine (USE)](opentype-shaping-use.md)
+  - [Universal Shaping Engine (<abbr>USE</abbr>)](opentype-shaping-use.md)
     - All complex scripts that are not handled by a dedicated
       script-specific shaping model
   - [Default](opentype-shaping-default.md)
@@ -42,7 +42,7 @@ begin at the
       Opentype mechanisms and should not be overlooked
 
 shaping documents and are encouraged to submit their feedback
-on the text or images of any of the linked scripts.  The documents are
+on the text or images of any of the linked scripts. The documents are
 organized by script; where there are multiple shaping models for a
 particular script (including deprecated models), the various models are
 all addressed in the same script-specific document.
@@ -56,7 +56,7 @@ Various [notes](notes/README.md) about the document set and the details
 of its scope, limitations, and quirks are also provided.
 
 Some [errata](errata.md) about the "upstream" specifications and
-reference documents are noted separately.
+reference documents are noted separately. 
 
 In its final form, this repository will hold documentation describing
 the shaping behavior used for layout of OpenType text. In particular,