rework documentation

Signed-off-by: Matthew Peveler <matt.peveler@gmail.com>

2 files changed, 24 insertions, 169 deletions

diff --git a/INSTALL.adoc b/INSTALL.adoc
deleted file mode 100644
index b43b044..0000000
--- a/INSTALL.adoc
+++ /dev/null
@@ -1,169 +0,0 @@
-AsciiDoc Installation
-=====================
-
-NOTE: The current version of AsciiDoc requires *Python 3.5 or later*
-to run.  If you don't already have an up-to-date version of Python
-installed it can be downloaded from the official Python website
-http://www.python.org/.
-
-
-Prerequisites
--------------
-See the link:README.html[README] page.
-
-
-Installing from the GitHub repository
--------------------------------------
-The AsciiDoc repository is hosted by https://github.com[GitHub].
-To browse the repository go to https://github.com/asciidoc/asciidoc-py3.
-You can install AsciiDoc from the repository if you don't have an up to
-date packaged version, or you want to get the latest version from the master
-branch:
-
-- Make sure you have https://git-scm.com/[Git]
-  installed; you can check with:
-
-  $ git --version
-
-- Go to the directory you want to install AsciiDoc into and download
-  the repository.  This example gets the {revnumber} tagged release:
-
-[subs="attributes"]
-  $ cd ~/bin
-  $ git clone https://github.com/asciidoc/asciidoc-py3 asciidoc-{revnumber}
-  $ git checkout {revnumber}
-
-You now have two choices: you can run asciidoc locally from your
-repository or you can use 'autoconf(1)' and 'make(1)' to perform a
-system-wide install.
-
-Running asciidoc from your local copy
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Create a symlink to the AsciiDoc script in a search `PATH` directory
-so it's easy to execute `asciidoc` from the command line, for example:
-
-[subs="attributes"]
-  $ ln -s ~/bin/asciidoc-{revnumber}/asciidoc.py ~/bin/asciidoc
-  $ ln -s ~/bin/asciidoc-{revnumber}/a2x.py ~/bin/a2x
-
-Use the git `pull` command to update your local AsciiDoc repository.
-
-Installing asciidoc for all users
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Create `configure` using 'autoconf(1)'; use `configure` to create the
-`Makefile`; run 'make(1)'; build the man pages; install:
-
----------------------------------------------
-$ autoconf
-$ ./configure
-$ make
-$ sudo make install
----------------------------------------------
-
-To uninstall:
-
----------------------------------------------
-$ sudo make uninstall
----------------------------------------------
-
-
-[[X1]]
-Distribution tarball installation
----------------------------------
-The distribution source tarballs can be downloaded from GitHub
-releases page https://github.com/asciidoc/asciidoc-py3/releases.
-
-If your flavor of UNIX or Linux does not have a packaged AsciiDoc
-distribution or if you prefer to install the latest AsciiDoc version
-from source, use the `configure` shell script in the tarball root
-directory.
-
-The `autoconf(1)`-generated `configure` script creates a `Makefile`
-that is tailored for your system. To install:
-
-[subs="attributes"]
-  $ tar -xzf asciidoc-{revnumber}.tar.gz
-  $ cd asciidoc-{revnumber}
-  $ ./configure
-  $ sudo make install
-
-To install the documentation:
-
-  $ sudo make docs
-
-To uninstall AsciiDoc:
-
-  $ sudo make uninstall
-
-If Vim is installed on your system the AsciiDoc Vim syntax highlighter
-and filetype detection are already installed as built into the vim runtime.
-
-
-[[X3]]
-Microsoft Windows installation
-------------------------------
-AsciiDoc is developed and tested on Linux but there seem to be quite a
-few people using it on Windows. To install AsciiDoc on Windows unzip
-the distribution zip file contents:
-
-[subs="attributes"]
-  $ unzip asciidoc-{revnumber}.zip
-
-This will create the folder +asciidoc-{revnumber}+ containing the
-`asciidoc.py` and `a2x.py` executables along with configuration files
-and documentation.
-
-To generate DocBook based outputs (e.g. PDFs) you will also need a
-working DocBook toolchain. Installing and configuring a DocBook
-toolchain on Windows can be a challenge -- this blog post explains
-http://blog.rainwebs.net/2010/02/25/how-to-create-handsome-pdf-documents-without-frustration/[How
-to Create Handsome PDF Documents Without Frustration] using
-http://www.cygwin.com/[Cygwin],
-http://dblatex.sourceforge.net/[dblatex] and AsciiDoc.
-
-
-Testing your installation
--------------------------
-Test out asciidoc by changing to the AsciiDoc application directory
-and converting the User Guide document (`./doc/asciidoc.txt`) to XHTML
-(`./doc/asciidoc.html`):
-
-  $ python3 asciidoc.py doc/asciidoc.txt
-
-The link:testasciidoc.html[testasciidoc] tool offers a more extensive set of
-conformance tests. You can run the tests by executing this command:
-
-  $ python3 ./tests/testasciidoc.py run
-
-A full battery of tests can be run from the `Makefile` script in the
-distribution root directory:
-
-  $ make test
-
-
-[[X2]]
-Prepackaged AsciiDoc installation
----------------------------------
-The following platform-specific AsciiDoc packages are available:
-
-*Fedora Linux*::
-  AsciiDoc is included in Fedora Extras, which is available in
-  the default Fedora installation. To install asciidoc, execute the
-  following command:
-
-  $ yum install asciidoc
-
-*Ubuntu / Debian*::
-  AsciiDoc is included in Ubuntu / Debian package manager. To install,
-  execute the following command:
-
-  $ apt install asciidoc
-
-*macOS Homebrew*::
-  AsciiDoc has been packaged in homebrew and is installable using the
-  following command:
-
-  $ brew install asciidoc
-
-See also link:userguide.html#X38[Packager Notes] in the 'AsciiDoc User
-Guide'.
diff --git a/README.md b/README.md
index 8e6d322..a7572cb 100644
--- a/README.md
+++ b/README.md
@@ -28,6 +28,16 @@ AsciiDoc.py is written in Python so you need a Python interpreter
 package manager for your OS or by downloading it from the official Python
 website http://www.python.org.
 
+Additionally, you wil need:
+
+* DocBook XSL Stylesheets 1.76.1
+* xsltproc (libxml 20706, libxslt 10126 and libexslt 815).
+* w3m 0.5.2
+* dblatex 0.3
+* FOP 0.95
+
+to enable the full AsciiDoc.py toolchain.
+
 ## Obtaining AsciiDoc.py
 
 Documentation and installation instructions are on the AsciiDoc.py website
@@ -37,6 +47,20 @@ https://asciidoc.org/. Simply, you should use use pip to install it:
 pip3 install asciidoc
 ```
 
+## Contributing
+
+To contribute and test your changes, you will need to install:
+* flake8
+* pytest
+* pytest-mock
+
+To lint the codebase: `python3 -m flake8`
+
+AsciiDoc.py has the following types of tests:
+1. doctests: `python3 -m asciidoc.asciidoc --doctest`
+1. unit tests: `python3 -m pytest`
+1. integration tests: `python3 tests/testasciidoc.py`
+
 ## LICENSE
 
 Copyright (C) 2002-2013 Stuart Rackham.