Revamp documentation

.gitignore

@@ -10,3 +10,6 @@ afl-gotcpu
 afl-showmap
 afl-tmin
 as
+
+# Built documentation
+docs/_build/

.travis.yml

@@ -1,11 +1,19 @@
 language: c
 
-env:
-  - AFL_I_DONT_CARE_ABOUT_MISSING_CRASHES=1 AFL_NO_UI=1
+matrix:
+  include:
+  - env:
+      - AFL_I_DONT_CARE_ABOUT_MISSING_CRASHES=1 AFL_NO_UI=1
+    script:
+      - make
+      - ./afl-gcc ./test-instr.c -o test-instr
+      - mkdir seeds; mkdir out
+      - echo "" > seeds/nil_seed
+      - timeout --preserve-status 5s ./afl-fuzz -i seeds -o out/ -- ./test-instr
 
-script:
-  - make
-  - ./afl-gcc ./test-instr.c -o test-instr
-  - mkdir seeds; mkdir out
-  - echo "" > seeds/nil_seed
-  - timeout --preserve-status 5s ./afl-fuzz -i seeds -o out/ -- ./test-instr
+  - language: python
+    env:
+      - DOCS_BUILD=1
+    script:
+      - pip install sphinx
+      - cd docs && make html

docs/ChangeLog

@@ -1,4 +1,3 @@
-=========
 ChangeLog
 =========
 
@@ -1342,7 +1341,7 @@ Version 1.35b:
 --------------
 
   - Cleaned up regular expressions in some of the scripts to avoid errors
-    on *BSD systems. Spotted by Jonathan Gray.
+    on \*BSD systems. Spotted by Jonathan Gray.
 
 --------------
 Version 1.34b:
@@ -2284,7 +2283,7 @@ Version 0.52b:
     too. Note that this breaks the ability to properly resume older sessions 
     - sorry about that.
 
-    (To fix this, simply move <out_dir>/.state/* from an older run
+    (To fix this, simply move "<out_dir>/.state/*" from an older run
     to <out_dir>/.state/deterministic_done/*.)
 
 --------------

docs/INSTALL → docs/INSTALL.rst

@@ -1,48 +1,60 @@
+.. _install:
+
 =========================
 Installation instructions
 =========================
 
   This document provides basic installation instructions and discusses known
-  issues for a variety of platforms. See README for the general instruction
-  manual.
+  issues for a variety of platforms.
 
-1) Linux on x86
----------------
+Platforms
+=========
+
+Linux on x86
+------------
 
 This platform is expected to work well. Compile the program with:
 
-$ make
+.. code-block:: console
+
+  $ make
 
 You can start using the fuzzer without installation, but it is also possible to
 install it with:
 
-# make install
+.. code-block:: console
+
+  # make install
 
 There are no special dependencies to speak of; you will need GNU make and a
 working compiler (gcc or clang). Some of the optional scripts bundled with the
 program may depend on bash, gdb, and similar basic tools.
 
-If you are using clang, please review llvm_mode/README.llvm; the LLVM
+If you are using clang, please review `llvm_mode/README.llvm`; the LLVM
 integration mode can offer substantial performance gains compared to the
 traditional approach.
 
 You may have to change several settings to get optimal results (most notably,
 disable crash reporting utilities and switch to a different CPU governor), but
 afl-fuzz will guide you through that if necessary.
 
-2) OpenBSD, FreeBSD, NetBSD on x86
-----------------------------------
+OpenBSD, FreeBSD, NetBSD on x86
+-------------------------------
 
 Similarly to Linux, these platforms are expected to work well and are
 regularly tested. Compile everything with GNU make:
 
-$ gmake
+.. code-block:: console
+
+  $ gmake
 
 Note that BSD make will *not* work; if you do not have gmake on your system,
 please install it first. As on Linux, you can use the fuzzer itself without
 installation, or install it with:
 
-# gmake install
+.. code-block:: console
+
+  # gmake install
 
 Keep in mind that if you are using csh as your shell, the syntax of some of the
 shell commands given in the README and other docs will be different.
@@ -58,8 +70,8 @@ The QEMU mode is currently supported only on Linux. I think it's just a QEMU
 problem, I couldn't get a vanilla copy of user-mode emulation support working
 correctly on BSD at all.
 
-3) MacOS X on x86
------------------
+MacOS X on x86
+--------------
 
 MacOS X should work, but there are some gotchas due to the idiosyncrasies of
 the platform. On top of this, I have limited release testing capabilities
@@ -98,8 +110,8 @@ The llvm_mode requires a fully-operational installation of clang. The one that
 comes with Xcode is missing some of the essential headers and helper tools.
 See llvm_mode/README.llvm for advice on how to build the compiler from scratch.
 
-4) Linux or *BSD on non-x86 systems
------------------------------------
+Linux or \*BSD on non-x86 systems
+---------------------------------
 
 Standard build will fail on non-x86 systems, but you should be able to
 leverage two other options:
@@ -114,13 +126,15 @@ leverage two other options:
 
 If you're not sure what you need, you need the LLVM mode. To get it, try:
 
-$ AFL_NO_X86=1 gmake && gmake -C llvm_mode
+.. code-block:: console
+
+  $ AFL_NO_X86=1 gmake && gmake -C llvm_mode
 
 ...and compile your target program with afl-clang-fast or afl-clang-fast++
 instead of the traditional afl-gcc or afl-clang wrappers.
 
-5) Solaris on x86
------------------
+Solaris on x86
+--------------
 
 The fuzzer reportedly works on Solaris, but I have not tested this first-hand,
 and the user base is fairly small, so I don't have a lot of feedback.
@@ -132,27 +146,31 @@ ignoring the -B parameter or $PATH).
 
 To fix this, you may want to build stock GCC from the source, like so:
 
-$ ./configure --prefix=$HOME/gcc --with-gnu-as --with-gnu-ld \
-  --with-gmp-include=/usr/include/gmp --with-mpfr-include=/usr/include/mpfr
-$ make
-$ sudo make install
+.. code-block:: console
+
+  $ ./configure --prefix=$HOME/gcc --with-gnu-as --with-gnu-ld \
+    --with-gmp-include=/usr/include/gmp --with-mpfr-include=/usr/include/mpfr
+  $ make
+  $ sudo make install
 
-Do *not* specify --with-as=/usr/gnu/bin/as - this will produce a GCC binary that
-ignores the -B flag and you will be back to square one.
+Do *not* specify `--with-as=/usr/gnu/bin/as` - this will produce a GCC binary
+that ignores the `-B` flag and you will be back to square one.
 
 Note that Solaris reportedly comes with crash reporting enabled, which causes
 problems with crashes being misinterpreted as hangs, similarly to the gotchas
 for Linux and MacOS X. AFL does not auto-detect crash reporting on this
 particular platform, but you may need to run the following command:
 
-$ coreadm -d global -d global-setid -d process -d proc-setid \
-  -d kzone -d log
+.. code-block:: console
+
+  $ coreadm -d global -d global-setid -d process -d proc-setid \
+    -d kzone -d log
 
 User emulation mode of QEMU is not available on Solaris, so black-box
-instrumentation mode (-Q) will not work.
+instrumentation mode (`-Q`) will not work.
 
-6) Everything else
-------------------
+Everything else
+---------------
 
 You're on your own. On POSIX-compliant systems, you may be able to compile and
 run the fuzzer; and the LLVM mode may offer a way to instrument non-x86 code.
@@ -174,10 +192,12 @@ Joshua J. Drake notes that the Android linker adds a shim that automatically
 intercepts SIGSEGV and related signals. To fix this issue and be able to see
 crashes, you need to put this at the beginning of the fuzzed program:
 
+.. code-block:: C
+
   signal(SIGILL, SIG_DFL);
   signal(SIGABRT, SIG_DFL);
   signal(SIGBUS, SIG_DFL);
   signal(SIGFPE, SIG_DFL);
   signal(SIGSEGV, SIG_DFL);
 
-You may need to #include <signal.h> first.
+You may need to :code:`#include <signal.h>` first.

docs/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+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)

docs/README.md

@@ -0,0 +1,13 @@
+# AFL Documentation
+
+This folder contains AFL's documentation. It is currently built using
+[Sphinx](http://www.sphinx-doc.org/en/master/).
+
+To build it locally, install sphinx and use `make html`.
+
+Please strive to keep the documentation readable in plaintext form to facilitate
+people reading without tooling just as AFL has done in the past with its
+`.txt` files.
+
+If you're reading this in plaintext, start from `index.rst` and work your way
+down the table-of-contents.