doc: Convert CHANGES to reStructuredText and add it to HTML docs

CHANGES is preprocessed to convert json_*() function names to Sphinx
:cfunc: cross references. This is to keep CHANGES more readable in
both plain text and HTML.

diff --git a/CHANGES b/CHANGES
index abe0062..0d83a79 100644 (file)
--- a/CHANGES
+++ b/CHANGES
@@ -1,54 +1,108 @@
-Version 1.1.3, released 2009-12-18
+Version 1.2 (in development)
+============================
+
+* New functions:
+
+  - ``json_equal()``: Test whether two JSON values are equal
+  - ``json_copy()`` and ``json_deep_copy()``: Make shallow and deep
+    copies of JSON values
+  - Add a version of all functions taking a string argument that
+    doesn't check for valid UTF-8: ``json_string_nocheck()``,
+    ``json_string_set_nocheck()``, ``json_object_set_nocheck()``,
+    ``json_object_set_new_nocheck()``
+
+* New encoding flags:
+
+  - ``JSON_SORT_KEYS``: Sort objects by key
+  - ``JSON_ENSURE_ASCII``: Escape all non-ASCII Unicode characters
+  - ``JSON_COMPACT``: Use a compact representation with all unneeded
+    whitespace stripped
+
+* Bug fixes:
+
+  - Revise and unify whitespace usage in encoder
+
+* Other changes:
+
+  - Convert ``CHANGES`` (this file) to reStructured text and add it to
+    HTML documentation
+  - Python is no longer required to run the tests
+  - Documentation can now be built by invoking ``make html``
+
+
+Version 1.1.3
+=============
+
+Released 2009-12-18
 
 * Encode reals correctly, so that first encoding and then decoding a
   real always produces the same value
-* Don't export private symbols in libjansson.so
+* Don't export private symbols in ``libjansson.so``
+
 
+Version 1.1.2
+=============
 
-Version 1.1.2, released 2009-11-08
+Released 2009-11-08
 
 * Fix a bug where an error message was not produced if the input file
-  could not be opened in json_load_file()
+  could not be opened in ``json_load_file()``
 * Fix an assertion failure in decoder caused by a minus sign without a
   digit after it
-* Remove an unneeded include for stdint.h in jansson.h
+* Remove an unneeded include of ``stdint.h`` in ``jansson.h``
 
 
-Version 1.1.1, released 2009-10-26
+Version 1.1.1
+=============
+
+Released 2009-10-26
 
 * All documentation files were not distributed with v1.1; build
   documentation in make distcheck to prevent this in the future
-* Fix v1.1 release date in CHANGES
+* Fix v1.1 release date in ``CHANGES``
+
 
+Version 1.1
+===========
 
-Version 1.1, released 2009-10-20
+Released 2009-10-20
 
 * API additions and improvements:
+
   - Extend array and object APIs
   - Add functions to modify integer, real and string values
   - Improve argument validation
-  - Use unsigned int instead of uint32_t for encoding flags
+  - Use unsigned int instead of ``uint32_t`` for encoding flags
+
 * Enhance documentation
+
   - Add getting started guide and tutorial
   - Fix some typos
   - General clarifications and cleanup
+
 * Check for integer and real overflows and underflows in decoder
-* Make singleton values thread-safe (true, false and null)
+* Make singleton values thread-safe (``true``, ``false`` and ``null``)
 * Enhance circular reference handling
-* Don't define -std=c99 in AM_CFLAGS
-* Add C++ guards to jansson.h
+* Don't define ``-std=c99`` in ``AM_CFLAGS``
+* Add C++ guards to ``jansson.h``
 * Minor performance and portability improvements
 * Expand test coverage
 
 
-Version 1.0.4, released 2009-10-11
+Version 1.0.4
+=============
+
+Released 2009-10-11
 
 * Relax Autoconf version requirement to 2.59
-* Make Jansson compile on platforms where plain char is unsigned
+* Make Jansson compile on platforms where plain ``char`` is unsigned
 * Fix API tests for object
 
 
-Version 1.0.3, released 2009-09-14
+Version 1.0.3
+=============
+
+Released 2009-09-14
 
 * Check for integer and real overflows and underflows in decoder
 * Use the Python json module for tests, or simplejson if the json
@@ -56,16 +110,25 @@ Version 1.0.3, released 2009-09-14
 * Distribute changelog (this file)
 
 
-Version 1.0.2, released 2009-09-08
+Version 1.0.2
+=============
+
+Released 2009-09-08
 
 * Handle EOF correctly in decoder
 
 
-Version 1.0.1, released 2009-09-04
+Version 1.0.1
+=============
+
+Released 2009-09-04
+
+* Fixed broken ``json_is_boolean()``
 
-* Fixed broken json_is_boolean()
 
+Version 1.0
+===========
 
-Version 1.0, released 2009-08-25
+Released 2009-08-25
 
 * Initial release

diff --git a/doc/.gitignore b/doc/.gitignore
index 69fa449..3152c88 100644 (file)
--- a/doc/.gitignore
+++ b/doc/.gitignore
@@ -1 +1,2 @@
 _build/
+changes.rst

diff --git a/doc/Makefile.am b/doc/Makefile.am
index cb3723f..e0dbe15 100644 (file)
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -5,7 +5,15 @@ EXTRA_DIST = \
 SPHINXBUILD = sphinx-build
 SPHINXOPTS = -d _build/doctrees -W
 
-html-local:
+# Convert json_*() functions to :cfunc: cross references in
+# ../CHANGES, and add a header from changes.rst.in
+changes.rst: changes.rst.in ../CHANGES
+       set -e; \
+       cat changes.rst.in >$@; \
+       sed -r -e 's/``(json_[a-z_]+\(\))``/:cfunc:`\1`/g' ../CHANGES \
+               >>$@
+
+html-local: changes.rst
        $(SPHINXBUILD) -b html $(SPHINXOPTS) $(srcdir) _build/html
 
 install-html-local: html
@@ -17,4 +25,4 @@ uninstall-local:
 
 clean-local:
        rm -rf _build
-       rm -f ext/refcounting.pyc
+       rm -f ext/refcounting.pyc changes.rst

diff --git a/doc/changes.rst.in b/doc/changes.rst.in
new file mode 100644 (file)
index 0000000..f57d1ed
--- /dev/null
+++ b/doc/changes.rst.in
@@ -0,0 +1,4 @@
+******************
+Changes in Jansson
+******************
+

diff --git a/doc/index.rst b/doc/index.rst
index 1ae9bf3..d6018b9 100644 (file)
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -35,6 +35,7 @@ Contents
    gettingstarted
    tutorial
    apiref
+   changes
 
 
 Indices and Tables