update documentation

7 files changed, 137 insertions, 23 deletions

diff --git a/CHANGES.rst b/CHANGES.rst
index 963708b..37ca951 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -1,4 +1,5 @@
-CHANGES
+=======
+Changes
 =======
 
 Versions without timestamps mean they are future releases.
diff --git a/Makefile b/Makefile
index 2b71af8..ee10fcb 100644
--- a/Makefile
+++ b/Makefile
@@ -15,7 +15,7 @@ VENV_PY3_CMD=virtualenv-python3.2
 
 BUILD_CMD=./setup.py sdist --formats gztar,zip bdist_wininst --plat-name win32
 
-DOC_FILES = docs/conf.py $(wildcard docs/*.rst)
+DOC_FILES = CHANGES.rst docs/conf.py $(wildcard docs/*.rst)
 
 # ============================================================================
 
diff --git a/README.rst b/README.rst
index f656c01..9eb9afe 100644
--- a/README.rst
+++ b/README.rst
@@ -1,7 +1,7 @@
 smartypants
 ===========
 
-smartypants_ is a Python port of SmartyPants__.
+smartypants_ is a Python fork of SmartyPants__.
 
 .. _smartypants: https://bitbucket.org/livibetter/smartypants.py
 __ SmartyPantsPerl_
@@ -44,6 +44,10 @@ Both produce::
 More information
 ----------------
 
-You can read smartypants' documentation_ or visit smartypants_ on Bitbucket.
+* Documentation_
+* `Source code`_
+* PyPI_
 
 .. _documentation: http://pythonhosted.org/smartypants/
+.. _Source code: smartypants_
+.. _PyPI: https://pypi.python.org/pypi/smartypants/
diff --git a/docs/development.rst b/docs/development.rst
new file mode 100644
index 0000000..af82737
--- /dev/null
+++ b/docs/development.rst
@@ -0,0 +1,84 @@
+===========
+Development
+===========
+
+smartypants_ is hosted on Bitbucket, you can clone the repository or file an
+issue report from there.
+
+.. _smartypants: https://bitbucket.org/livibetter/smartypants.py
+
+
+Contributing
+============
+
+You are welcome to contribute whatever you can. Coding, documenting,
+reporting issues, requesting features, even correcting typos.
+
+
+Testing
+=======
+
+If you want to contribute to the source code, be sure that you check your
+modification can pass tests. Normally, if you use Unix-like system, you should
+be able to run all tests with::
+
+  make test
+
+It will test PEP8, pyflakes, unittest, and package installation::
+
+  make test_pep8
+  make test_pyflakes
+  make test_test
+  make install_test
+
+.. note:: They will all be tested with both Python 2 and Python 3. You may need
+          to override ``PY2_CMD`` and/or ``PY3_CMD``.
+
+If ``make`` isn't available, ``setup.py`` can be used::
+
+  python setup.py pep8
+  python setup.py pyflakes
+  python setup.py test
+
+For manual package installation test::
+
+  python setup.py sdist
+  pip install --user --upgrade dist/smartypants-<x.y.z>.tar.gz
+
+
+Building
+========
+
+Package
+-------
+
+You should be able to build the package with either of::
+
+  make
+
+.. note:: ``make`` builds source tarball, zip, and win32 setup.
+
+or::
+
+  python setup.py sdist
+
+
+Documentation
+-------------
+
+You should be able to build the documentation with either of::
+
+  make doc
+
+or::
+
+  python setup.py build_sphinx
+
+
+Reporting
+=========
+
+Please head over to Issues_ and create an issue for a bug report or feature
+request.
+
+.. _Issues: https://bitbucket.org/livibetter/smartypants.py/issues
diff --git a/docs/history.rst b/docs/history.rst
index 82fbeb6..45fc2dd 100644
--- a/docs/history.rst
+++ b/docs/history.rst
@@ -4,33 +4,57 @@ History
 
 For changelog, please see :doc:`changes`.
 
-`John Gruber`_ did all of the hard work of writing this software in Perl for
-`Movable Type`_ and almost all of this useful documentation.  `Chad Miller`_
-ported it to Python to use with Pyblosxom_.
 
-.. _John Gruber: http://daringfireball.net/
-.. _Movable Type: http://www.movabletype.org/
-.. _Chad Miller: http://web.chad.org/
-.. _Pyblosxom: http://pyblosxom.github.io/
+SmartyPants
+===========
+
+**Perl SmartyPants or original SmartyPants.**
 
-Portions of the SmartyPants original work are based on Brad Choate's nifty
-MTRegex plug-in.  `Brad Choate`_ also contributed a few bits of source code to
-this plug-in.  Brad Choate is a fine hacker indeed.
+In 2002, `John Gruber`_  started the SmartyPants for `Movable Type`_, written
+in Perl.
 
-`Jeremy Hedley`_ and `Charles Wiltgen`_ deserve mention for exemplary beta
-testing of the original SmartyPants.
+.. _John Gruber: http://daringfireball.net/
+.. _Movable Type: http://www.movabletype.org/
 
-`Rael Dornfest`_ ported SmartyPants to Blosxom.
+`Rael Dornfest`_ ported SmartyPants to Blosxom. Portions of the SmartyPants are
+based on `Brad Choate`_'s nifty MTRegex plug-in. `Jeremy Hedley`_ and
+`Charles Wiltgen`_ deserve mention for exemplary beta testing of SmartyPants.
 
 .. _Brad Choate: http://bradchoate.com/
 .. _Jeremy Hedley: http://antipixel.com/
 .. _Charles Wiltgen: http://playbacktime.com/
 .. _Rael Dornfest: http://raelity.org/
 
-It was later packaged for PyPI by Hao Lian.
 
-Since August 2013, smartypants.py has been managed by `Yu-Jie Lin`_ after
-contacted Chad Miller and Hao Lian. Lin took the project manager role and the
-package ownership on PyPI. It has also officially supported Python 3.
+smartypants.py
+==============
+
+**smartypants.py, Python [port of] SmartyPants.**
+
+In 2004, `Chad Miller`_ ported it to Python to use with Pyblosxom_.
+
+.. _Chad Miller: http://web.chad.org/
+.. _Pyblosxom: http://pyblosxom.github.io/
+
+Brad Choate also contributed a few bits of source code to the Python port.
+Brad Choate is a fine hacker indeed. It was later packaged for PyPI by
+Hao Lian.
+
+
+smartypants
+===========
+
+**smartypants, Python [fork of] SmartyPants.**
+
+Since August 2013, smartypants has been managed by `Yu-Jie Lin`_ after
+contacted Chad Miller and Hao Lian. Lin took over the project manager role and
+the package ownership on PyPI. It has since then also officially supported
+Python 3.
 
 .. _Yu-Jie Lin: http://yjl.im/
+
+At this point, smartpants is heading towards as a *fork* of SmartyPants. The
+".py" part is dropped from the project name, ".py" or "port" sometimes is still
+used. For instance, to avoid confused with SmartyPants.
+
+Nevertheless, the project name is *smartypants*.
diff --git a/docs/index.rst b/docs/index.rst
index 3ca21d8..f614fe5 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -14,6 +14,7 @@ Contents:
    introduction
    usage
    command-line
+   development
    reference
    history
    changes
diff --git a/docs/introduction.rst b/docs/introduction.rst
index c0fac0f..cfa8c06 100644
--- a/docs/introduction.rst
+++ b/docs/introduction.rst
@@ -2,7 +2,7 @@
 Introduction
 ============
 
-smartypants_ is a Python port of SmartyPants__.
+smartypants_ is a Python fork of SmartyPants__.
 
 .. _smartypants: https://bitbucket.org/livibetter/smartypants.py
 __ SmartyPantsPerl_
@@ -52,6 +52,6 @@ Both produce::
 Installation
 ============
 
-smartypants.py can be installed vi pip::
+smartypants can be installed via ``pip``::
 
   $ pip install smartypants