Merge pull request #20 from morganwillcock/buildnative

Build without cygwin

.gitignore

@@ -1,126 +1,7 @@
-# Byte-compiled / optimized / DLL files 
-__pycache__/
-*.py[cod]
-*$py.class
-
-# C extensions
-*.so
-
-# I want to ignore the source of sphinx
-source/
-
-# Distribution / packaging
-.Python
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-*.egg-info/
-.installed.cfg
-*.egg
-MANIFEST
-
-# PyInstaller
-#  Usually these files are written by a python script from a template
-#  before PyInstaller builds the exe, so as to inject date/other infos into it.
-*.manifest
-*.spec
-
-# Installer logs
-pip-log.txt
-pip-delete-this-directory.txt
-
-# Unit test / coverage reports
-htmlcov/
-.tox/
-.coverage
-.coverage.*
-.cache
-nosetests.xml
-coverage.xml
-*.cover
-.hypothesis/
-.pytest_cache/
-
-# Translations
-*.mo
-*.pot
-
-# the chmcmd binary and md5
+__pycache__
+build
+source
 chmcmd
 chmcmd.md5
-
-# the resulting chm docs
 *.chm
-
-# Django stuff:
-*.log
-local_settings.py
-db.sqlite3
-
-# Flask stuff:
-instance/
-.webassets-cache
-
-# Scrapy stuff:
-.scrapy
-
-# Sphinx documentation
-docs/_build/
-
-# PyBuilder
-target/
-
-# Jupyter Notebook
-.ipynb_checkpoints
-
-# pyenv
-.python-version
-
-# celery beat schedule file
-celerybeat-schedule
-
-# SageMath parsed files
-*.sage.py
-
-# Environments
-.env
-.venv
-env/
-venv/
-ENV/
-env.bak/
-venv.bak/
-
-# usual things on the venv
-bin/
-lib/
-lib64/
-share/
-
-# this is a pip-delete-this-directory
-src/
-
-# pip on venv
-pip-selfcheck.json
-
-# Spyder project settings
-.spyderproject
-.spyproject
-
-# Rope project settings
-.ropeproject
-
-# mkdocs documentation
-/site
-
-# mypy
-.mypy_cache/
+*.chw

.travis.yml

@@ -12,21 +12,20 @@ before_install:
 install:
 - pip install -r requirements.txt
 script:
-- ./get-help-source.sh
-- make html htmlhelp
-- ./checklinks source/*.md
+- make clone html htmlhelp chm
 - touch build/html/.nojekyll
 before_deploy:
   # run only once, the tasks executed prepares the files to be upload
   # once a github tag is created, ideally using the release button
+  # saves the sources for being able to reproduce builds easily if needed
   - |
     if ! [ "$BEFORE_DEPLOY_RUN" ]; then
       export BEFORE_DEPLOY_RUN=1;  
       zip ags-manual-wiki-md-source.zip  source/*.md source/images/*
       pushd build/htmlhelp/
       zip -r ../../ags-manual-hhp-build.zip *
       popd
-      ./make-chm-from-htmlhelp.sh
+      mv ags-help.chm ags-help-FP.chm
     fi
 
 deploy:
@@ -43,7 +42,7 @@ deploy:
     file: 
       - "ags-manual-wiki-md-source.zip"
       - "ags-manual-hhp-build.zip"
-      - "ags-help.chm"
+      - "ags-help-FP.chm"
     skip_cleanup: true
     on:
       branch: master

Makefile

@@ -1,20 +1,52 @@
-# Minimal makefile for Sphinx documentation
-#
+SOURCEDIR ?= source
+BUILDDIR ?= build
+SPHINXPROJ ?= AGSHelp
+SPHINXOPTS ?= -c .
 
-# You can set these variables from the command line.
-SPHINXOPTS    ?= -c .
-SPHINXBUILD   = sphinx-build
-SPHINXPROJ    = AGSHelp
-SOURCEDIR     = source
-BUILDDIR      = build
+GITURL ?= https://github.com/adventuregamestudio/ags-manual.wiki.git
+GITOPTS ?= --depth=1 --branch=master
+
+.PHONY: help clone html htmlhelp chm clean
 
-# Put it first so that "make" without argument is like "make help".
 help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@awk -F '[: ]' \
+	'/^[^ ][a-z ]+:/ { for (i = 1; i < NF; i ++ ) { if ($$i != "help") print $$i } }' Makefile
+
+clone:
+	@rm -rf "$(SOURCEDIR)"
+	@git clone $(GITOPTS) $(GITURL) $(SOURCEDIR)
+	touch "$(SOURCEDIR)/index.rst"
+
+html htmlhelp:
+	@python -m sphinx -b $@ "$(SOURCEDIR)" "$(BUILDDIR)/$@" $(SPHINXOPTS)
+
+chm:
+	@sed -E -i.bak -n "/^Binary (TOC|Index)=No$$/!p" "$(BUILDDIR)/htmlhelp/AGSHelpdoc.hhp" && \
+	rm "$(BUILDDIR)/htmlhelp/AGSHelpdoc.hhp.bak"
 
-.PHONY: help Makefile
+	@chmcmd=`which chmcmd` ;\
+	if [ $$? != 0 ]; then \
+			if [ "`uname`" = "Linux" ]; then \
+				rm -f chmcmd && wget –quiet https://github.com/ericoporto/freepascal/releases/download/3.0.4/chmcmd ;\
+				echo "af4eea94c843adb20f8ae10884badbc5 chmcmd" > chmcmd.md5 ;\
+				md5sum -c chmcmd.md5 || exit 1 ;\
+				chmod +x chmcmd ;\
+				chmcmd=`pwd`"/chmcmd" ;\
+			else \
+				echo "chmcmd is not present" ;\
+				exit 1;\
+			fi ;\
+	fi ;\
+	echo "Using '$$chmcmd' \
+	$$( \
+		cd "$(BUILDDIR)/htmlhelp" && \
+		rm -f "AGSHelpdoc.chm" && \
+		"$$chmcmd" "AGSHelpdoc.hhp" && \
+		chmod a+r-w-x "AGSHelpdoc.chm" && \
+		mv -fv "AGSHelpdoc.chm" ../../ags-help.chm \
+	)"
 
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-.DEFAULT: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+clean:
+	@while read -r line; do \
+		rm -rf "$$line"; \
+	done < .gitignore

README.md

@@ -4,36 +4,57 @@ Travis (web): [![Build Status](https://travis-ci.org/adventuregamestudio/ags-man
 
 [**Edit the Help in the Wiki**](https://github.com/adventuregamestudio/ags-manual/wiki) | [**Revision History**](https://github.com/adventuregamestudio/ags-manual/wiki/_history)
 
-The help files can be edited on the wiki or cloned locally and pushed. Create issues if something is wrong.
+The help files can be edited on the wiki or cloned locally and pushed. Please open an issue if something is wrong.
 
     git clone https://github.com/adventuregamestudio/ags-manual.wiki.git
 
-## Read the help files
+## Reading the help files
 
-The manual is hosted online on [adventuregamestudio.github.io/ags-manual/](https://adventuregamestudio.github.io/ags-manual) .
+The manual is hosted online on [adventuregamestudio.github.io/ags-manual/](https://adventuregamestudio.github.io/ags-manual).
 
-You can also download it from [latest release](https://github.com/adventuregamestudio/ags-manual/releases/latest) .
+You can also download the [latest release](https://github.com/adventuregamestudio/ags-manual/releases/latest).
 
 ![](ags-manual-readme.png)
 
-## How to generate the help files from the wiki!
+## Building the help files
 
-The help file is generated using [Python 3 Sphinx](http://www.sphinx-doc.org/en/master/)!
+The help files are generated using [Python 3 Sphinx](http://www.sphinx-doc.org/en/master/)!
 
-This documentation assumes you have Sphinx already installed and configured and you have access to a Unix-style *bash* compatible shell.
+**Note that the use of a virtualenv is recommended if your Python installation is system-wide**
 
-To build the help files, clone this repository first!
+Install the requisite pip packages
 
-    git clone [email protected]:adventuregamestudio/ags-manual.git
-    cd agshelp
+    pip install -r requirements.txt
 
-Then you need to get the wiki files
+Install an HTML help compiler
 
-    ./get-help-source.sh
+For Windows, install [HTML Help Workshop](http://go.microsoft.com/fwlink/?LinkId=14188). For macOS, Unix, Linux, etc. install chmcmd from your regular package repository or install [Free Pascal](https://www.freepascal.org/download.var).
 
-Now just use make to create any help version you want! **Example for html files**:
+### Make targets
 
-    make html
+name | function
+--- | ---
+clone | git clone the wiki source
+html | run sphinx-build with the html builder
+htmlhelp | run sphinx-build with the htmlhelp builder
+chm | run the HTML compiler
+clean | delete everything listed in .gitignore
+
+build just the html site
+
+    make clone html
+
+build just the CHM (Windows help) file
+
+    make clone htmlhelp chm
+
+build everything
+
+    make clone html htmlhelp chm
+
+rebuild everything
+
+    make clean clone html htmlhelp chm
 
 ## Indexing
 
@@ -44,21 +65,17 @@ Markdown | Indexed as
 \#\# Heading | Single entry: 'Heading'
 \#\#\# Sub-heading | Paired entry: 'Heading' <-> 'Sub-heading'
 
-Using \#\#\# without a preceeding \#\# on the page will generate a warning and be ignored by Sphinx, so it won't appear in the index. To create an H2 style heading without an index entry, use the alternate H2 markup:
+To create an H2 style heading without an index entry, use the alternate H2 markup:
 
     Heading
     -------
 
-H1 headings are not checked, effectively reserving their use for primary document titles.
+H1 headings are not checked, effectively reserving their use for the primary title on the contents page.
 
 ## Checking wiki links
 
 If making a lot of changes, the included AWK script can validate links within a directory:
 
     ./checklinks path/to/wiki/source/*.md
 
-A checklinks task is run on every Travis-CI build, and the build will fail for any missing link. [Read the logs here to find the missing link](https://travis-ci.org/adventuregamestudio/ags-manual).
-
-Additionally, *sphinx linkchecker* can check if external links are broken.
-
-    make linkcheck
+A checklinks task is run on every Travis-CI build, and the build will fail for any missing link. Read the logs [here](https://travis-ci.org/adventuregamestudio/ags-manual) to find the missing link.

_extensions/h2r.py

@@ -7,6 +7,10 @@
     For when you need indicies and you have none, this extension
     generates some based on H2 and H3 markdown headers
 
+    h2r_toc_from_doc is a path to a markdown page of headings and list
+    items, which will be converted to rst, have toc entries added per
+    section, and overwrite the contents of the master doc
+
     h2r_script_object_from_header is a regular expression that matches
     a script object in match group 1, from the H2 header
 
@@ -18,6 +22,7 @@
 import io
 import sphinx
 import re
+from m2r import parse_from_file
 from sphinx.util import logging
 
 logger = logging.getLogger(__name__)
@@ -42,6 +47,9 @@ def map_page(app, env, docnames):
     script_object = None
 
     for docname in env.found_docs:
+        if docname == app.config.master_doc:
+            continue
+
         with io.open(env.doc2path(docname), encoding='utf-8') as f:
             changes[docname] = []
             offset = 0
@@ -68,7 +76,13 @@ def map_page(app, env, docnames):
 
                 offset += len(line)
 
-def add_indices(app, docname, source):
+def source_transform(app, docname, source):
+    if docname != app.config.master_doc:
+        add_indicies(app, docname, source)
+    elif app.config.h2r_toc_from_doc:
+        add_toc(app, docname, source)
+
+def add_indicies(app, docname, source):
     modified = []
     offset = 0
 
@@ -98,9 +112,21 @@ def add_indices(app, docname, source):
     source[0] = ''.join(modified)
     logger.info('Added %d indicies for document \'%s\'' % (len(changes[docname]), docname))
 
+def add_toc(app, docname, source):
+    # overwrite master doc source with the rst version of the contents page
+    source[0] = parse_from_file(app.config.h2r_toc_from_doc)
+    ## convert lists to toc items
+    source[0] = re.sub(r'\* `([^`]+)`_?', r'   \1', source[0])
+    ## insert toc directives
+    source[0] = re.sub(r'(--+)', r'\1\n\n.. toctree::\n   :maxdepth: 1', source[0])
+    ## add a glob toc to cover remaining docs
+    source[0] += '\n.. toctree::\n   :glob:\n   :hidden:\n\n   *\n'
+    logger.info('TOC page \'%s\' generated as:\n%s' % (app.config.master_doc, source[0]))
+
 def setup(app):
+    app.add_config_value('h2r_toc_from_doc', '', 'html')
     app.add_config_value('h2r_script_object_from_header', r'(.*)', 'html')
     app.add_config_value('h2r_script_object_force_global', {}, 'html')
     app.connect('env-before-read-docs', map_page)
-    app.connect('source-read', add_indices)
+    app.connect('source-read', source_transform)
     return {'version': sphinx.__display_version__, 'parallel_read_safe': True}