Change documentation to markdown

.gitignore

@@ -9,11 +9,6 @@ token
 .tox/*
 build/*
 dist/*
-doc/gnofract4d-manual/C/commands.xml
-doc/gnofract4d-manual/C/gnofract4d-manual.html
-doc/gnofract4d-manual/C/gnofract4d-manual.pdf
-doc/gnofract4d-manual/C/stdlib.xml
-elephant-valley/*
 experiments/*
 fract4d/c/cmap_name.h
 images/*
@@ -22,3 +17,15 @@ params/*
 
 #autogenerated by compiler
 fract4d_compiler/parser.out
+
+# generated by hugo
+manual/public/categories/*
+manual/public/commands/*
+manual/public/fonts/*
+manual/public/katex/*
+manual/public/tags/*
+manual/public/stdlib/*
+manual/resources/_gen/*
+
+# edit
+.vscode/

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "manual/themes/book"]
+	path = manual/themes/book
+	url = https://github.com/fract4d/hugo-book

.travis.yml

@@ -6,13 +6,16 @@ python:
   - "3.5"
   - "3.6"
   - "3.7"
+jobs:
+  include:
+    - env: TOXENV=pylint
 before_install:
-  sudo apt-get install -y libgirepository1.0-dev gir1.2-gtk-3.0
+  - sudo apt-get install -y libgirepository1.0-dev gir1.2-gtk-3.0 
+  - sudo snap install hugo --channel=extended
 install:
   - python setup.py build
-  - pip install tox-travis pylint
+  - pip install tox-travis
 script:
-  - ./bin/pylint.sh || travis_terminate 1;
   - tox
 notifications:
   email: false

MANIFEST.in

@@ -1,25 +1,5 @@
-include buildtools/*.py
-include COPYING
-include PKG-INFO
-include createdocs.py
-include debian/changelog
-include debian/compat
-include debian/control
-include debian/copyright
-include debian/docs
-include debian/gnofract4d.install
-include debian/gnofract4d.manpages
-include debian/lintian/overrides/gnofract4d
-include debian/menu
-include debian/pycompat
-include debian/rules
-include debian/watch
+include LICENSE
 include doc/gnofract4d.1
-include doc/gnofract4d-manual/C/*.css
-include doc/gnofract4d-manual/C/*.html
-include doc/gnofract4d-manual/C/*.xml
-include doc/gnofract4d-manual/C/*.xsl
-include doc/gnofract4d-manual/C/figures/*.png
 include formulas/fractint-builtin.frm
 include formulas/fractint-g4.frm
 include formulas/fractint.cfrm
@@ -29,24 +9,24 @@ include formulas/gf4d.uxf
 include formulas/standard.ucl
 include formulas/tutorial.frm
 include formulas/sterling2.frm
-include formulas/test.cfrm
-include formulas/test.frm
-include formulas/test_bad_pp.frm
 include fract4d/c/*.h
 include fract4d/c/fract4dc/*.h
 include fract4d/c/model/*.h
 include fract4d/tests/*.py
 include fract4d_compiler/tests/*.py
 include fract4dgui/tests/*.py
 include fract4dgui/ui.xml
+include fract4dgui/gnofract4d.css
 include gnofract4d
 include gnofract4d-mime.xml
 include gnofract4d.desktop
+include manual/public/*.css
+include manual/public/*.html
+include manual/public/*.png
 include maps/*.cs
 include maps/*.map
 include maps/*.ugr
 include pixmaps/*.png
-include pixmaps/*.xpm
 include test.py
 include testdata/animation.fcta
 include testdata/chainsoflight.fct

README.md

@@ -6,9 +6,9 @@ Gnofract 4D is a program for drawing beautiful mathematically-based
 images known as fractals. See the manual for more details.
 
 The most recent version may be obtained from
-http://github.com/fract4d/gnofract4d
+https://github.com/fract4d/gnofract4d
 
-Examples, screenshots etc are at http://fract4d.github.io/gnofract4d
+Examples, screenshots etc are at https://fract4d.github.io/gnofract4d
 
 Basic Installation
 ==================
@@ -17,10 +17,6 @@ Run:
 
  ./setup.py build
 
-If you would like a copy of the manual:
-
-./createdocs.py
-
 You can then run Gnofract4D in the local directory:
 
 ./gnofract4d
@@ -80,14 +76,24 @@ On MacOS you might find an error regarding the number of opened files, you can i
 Linting
 =======
 
-Pylint is being used to detect code that doesn't follow the [PEP8 style](https://www.python.org/dev/peps/pep-0008/) guide and potentially erroneus code in Python.
+Pylint is being used to detect code that doesn't follow the [PEP8 style](https://www.python.org/dev/peps/pep-0008/) guide and potentially erroneous code in Python.
 You can run it in two ways:
- - Directly (firstly you should install pylint throw pip3):
+ - Directly (firstly you should install pylint through pip3):
 ```
 $ sudo pip3 install pylint
 $ ./bin/pylint.sh
 ```
- - Using docker (same enviorment as pipeline):
+ - Using docker (same environment as pipeline):
 ```
 $ ./docker/bin/run_lint.sh
 ```
+
+Generating Documentation
+========================
+
+You can only regenerate the docs if you clone the Gnofract 4D git repo - the source dist packages contain the generated docs but not the input files for the generation process. To regenerate the docs:
+
+1. Make sure you're starting from a git clone not a source .zip - you need the files under manual/content
+1. Install hugo (Ubuntu 18.04 has an older version. Run `snap install hugo` instead of apt-get install hugo)
+1. Run `./createdocs.py`
+

bin/pylint.sh

@@ -1,12 +1,18 @@
 #!/bin/bash
 
-pylint --rcfile pylintrc *.py fract4d fract4d_compiler fract4dgui
+if [ -x "$(command -v pylint3)" ]; then
+  PYLINT=pylint3
+else
+  PYLINT=pylint
+fi
+
+$PYLINT --rcfile pylintrc *.py gnofract4d fract4d fract4d_compiler fract4dgui
 if [[ $? > 0 ]]
 then
   exit 1
 fi
 
-pylint --rcfile pylintrc_new fract4d/fract4d_new
+$PYLINT --rcfile pylintrc_new fract4d/fract4d_new
 if [[ $? > 0 ]]
 then
   exit 1

createdocs.py

@@ -1,35 +1,26 @@
 #!/usr/bin/env python3
 
-# run this to update some tables in the documentation
-
-# making this a separate cmd (not part of setup.py) because importing
-# gtk was causing "setup.py build" to crash - inexplicable...
-
-# also the other python versions don't have gtk as a module,
-# so were reporting errors.
-
-import sys
-import os
-
-def create_stdlib_docs():
-    'Autogenerate docs'
-    try:
-        # create list of stdlib functions
-        from fract4d import createdocs as cd1
-        cd1.main("doc/gnofract4d-manual/C/stdlib.xml")
-
-        # create list of mouse and GUI commands
-        import fract4dgui.createdocs
-        fract4dgui.createdocs.main("doc/gnofract4d-manual/C/commands.xml")  # pylint: disable=no-value-for-parameter
-
-        # create HTML version of docs for them as don't have yelp
-        os.chdir("doc/gnofract4d-manual/C")
-        retval = os.system("xsltproc --nonet --output gnofract4d-manual.html --stringparam html.stylesheet docbook.css gnofract4d.xsl gnofract4d-manual.xml")
-        if retval != 0:
-            raise Exception("error processing xslt")
-    except Exception as err:
-        print("Problem creating docs. Online help will be incomplete.", file=sys.stderr)
-        print(err, file=sys.stderr)
-        sys.exit(1)
-
-create_stdlib_docs()
+# Used to generate the documentation, in 2 phases:
+# 1) run python script to list all the functions in the standard library
+# 2) invoke Hugo static file generator to create HTML docs which are written to manual/public
+
+# This is a separate step from the normal build because not everyone will want to
+# install those tools. The 'sdist' packages (gnofract4d-4.2.zip etc) contain the output from this step
+# but not all the input. To build the docs you need to clone the git repo
+
+import subprocess
+
+# create list of stdlib functions
+from fract4d import createdocs as cd1
+cd1.main("manual/content/stdlib.html")
+
+print("Generating docs")
+result = subprocess.run(
+    ["hugo", "-b", ""],
+    cwd="manual",
+    stdout=subprocess.PIPE,
+    stderr=subprocess.PIPE)
+
+if result.returncode != 0:
+    raise RuntimeError("Error generating docs: %d\nStderr\n%s\nStdout\n%s" %
+        (result.returncode, result.stderr.decode('utf8'), result.stdout.decode('utf8')))