Restructure list of changes for 1.0 into categories.

1 files changed, 109 insertions, 120 deletions

diff --git a/CHANGES b/CHANGES
index a596f75d..02ca6d98 100644
--- a/CHANGES
+++ b/CHANGES
@@ -1,147 +1,136 @@
 Release 1.0 (in development)
 ============================
 
+Incompatible changes
+--------------------
+
 * Support for domains has been added.  A domain is a collection of
   directives and roles that all describe objects belonging together,
-  e.g. elements of a programming language.  Builtin domains are
-  provided for Python and C objects.
-
-* Added a JavaScript domain.
-
-* Added a reStructuredText domain.
-
-* Added a way for intersphinx to refer to named labels in other
-  projects, and to specify the project you want to link to.
-
-* Support for docutils 0.4 has been removed.
-
-* Added Croatian translation, thanks to Bojan Mihelač.
-
-* Added a manual page builder.
-
-* Added support for source ordering of members in autodoc, with
-  ``autodoc_member_order = 'bysource'``.
-
-* In HTML output, inline roles now get a CSS class with their name,
-  allowing styles to customize their appearance.  Domain-specific
-  roles get two classes, ``domain`` and ``domain-rolename``.
-
-* In HTML output, references now get the class ``internal`` if they
-  are internal to the whole project, as opposed to internal to the
-  current page.
-
-* The ``menuselection`` and ``guilabel`` roles now support ampersand
-  accelerators.
-
-* New more compact doc field syntax is now recognized:
-  ``:param type name: description``.
-
-* Added a "nitpicky" mode that emits warnings for all missing
-  references.  It is activated by the ``-n`` command-line switch
-  or the ``nitpicky`` config value.
-
-* Added the ``viewcode`` extension.
-
-* Added ``html-collect-pages`` event.
-
-* Sphinx now requires Jinja2 version 2.2 or greater.
-
-* Added Turkish translation, thanks to Firat Ozgul.
-
-* Added ``needs_sphinx`` config value and ``Sphinx.require_sphinx``
-  application API function.
-
-* Added single-file HTML builder.
-
-* Added ``autodoc_default_flags`` config value, which can be used
-  to select default flags for all autodoc directives.
+  e.g. elements of a programming language.  A few builtin domains are
+  provided:
 
-* Added ``tab-width`` option to ``literalinclude`` directive.
+  - Python
+  - C
+  - C++
+  - JavaScript
+  - reStructuredText
 
-* Added ``rst_prolog`` config value.
+* The old markup for defining and linking to C directives will not work
+  anymore without activating the ``oldcmarkup`` extension.
 
-* Added ``html_secnumber_suffix`` config value to control section
-  numbering format.
+* Removed support for old dependency versions; requirements are now:
 
-* Added ``html_compact_lists`` config value to control docutils'
-  compact lists feature.
+  - docutils >= 0.5
+  - Jinja2   >= 2.2
 
-* The ``html_sidebars`` config value can now contain patterns as
-  keys, and the values can be lists that explicitly select which
-  sidebar templates should be rendered.  That means that the builtin
-  sidebar contents can be included only selectively.
+* Removed deprecated elements:
 
-* ``html_static_path`` can now contain single file entries.
+  - ``exclude_dirs`` config value
+  - ``sphinx.builder`` module
 
-* The new universal config value ``exclude_patterns`` makes the
-  old ``unused_docs``, ``exclude_trees`` and ``exclude_dirnames``
-  obsolete.
+Features added
+--------------
 
-* Remove the deprecated ``exclude_dirs`` config value.
+* General:
 
-* #129: Wrap toctrees in a div tag with class ``toctree-wrapper``
-  in HTML output.
+  - Added a "nitpicky" mode that emits warnings for all missing
+    references.  It is activated by the ``-n`` command-line switch or
+    the ``nitpicky`` config value.
+  - Added ``latexpdf`` target in quickstart Makefile.
 
-* #280: Autodoc can now document instance attributes assigned in
-  ``__init__`` methods.
-
-* Added ``alt`` option to ``graphviz`` extension directives.
-
-* Added Epub builder.
-
-* #309: The ``graphviz`` extension can now output SVG instead of PNG
-  images, controlled by the ``graphviz_output_format`` config value.
-
-* #284: All docinfo metadata is now put into the document metadata, not
-  just the author.
-
-* Added new HTML theme ``haiku``, inspired by the Haiku OS user guide.
-
-* Added new HTML theme ``nature``.
-
-* Added new HTML theme ``agogo``, created by Andi Albrecht.
-
-* Added new HTML theme ``scrolls``, created by Armin Ronacher.
-
-* The ``toctree()`` callable in templates now has a ``maxdepth``
-  keyword argument to control the depth of the generated tree.
-
-* Added Catalan translation, thanks to Pau Fernández.
-
-* Added ``html_output_encoding`` config value.
-
-* #200: Added ``Sphinx.add_stylesheet()``.
-
-* Added ``titlesonly`` option to ``toctree`` directive.
-
-* Removed the deprecated ``sphinx.builder`` module.
-
-* #193: Added a ``visitedlinkcolor`` theme option to the default
-  theme.
-
-* Added the ``prepend`` and ``append`` options to the
-  ``literalinclude`` directive.
+* Markup:
 
-* Added the ``latex_docclass`` config value and made the "twoside"
-  documentclass option overridable by "oneside".
+  - The ``menuselection`` and ``guilabel`` roles now support ampersand
+    accelerators.
+  - New more compact doc field syntax is now recognized: ``:param type
+    name: description``.
+  - Added ``tab-width`` option to ``literalinclude`` directive.
+  - Added ``titlesonly`` option to ``toctree`` directive.
+  - Added the ``prepend`` and ``append`` options to the
+    ``literalinclude`` directive.
+  - #284: All docinfo metadata is now put into the document metadata, not
+    just the author.
 
-* Added the ``trim_doctest_flags`` config value, which is true by default.
+* Configuration:
 
-* Added the ``extlinks`` extension.
+  - Added ``rst_prolog`` config value.
+  - Added ``html_secnumber_suffix`` config value to control section
+    numbering format.
+  - Added ``html_compact_lists`` config value to control docutils'
+    compact lists feature.
+  - The ``html_sidebars`` config value can now contain patterns as
+    keys, and the values can be lists that explicitly select which
+    sidebar templates should be rendered.  That means that the builtin
+    sidebar contents can be included only selectively.
+  - ``html_static_path`` can now contain single file entries.
+  - The new universal config value ``exclude_patterns`` makes the
+    old ``unused_docs``, ``exclude_trees`` and ``exclude_dirnames``
+    obsolete.
+  - Added ``html_output_encoding`` config value.
+  - Added the ``latex_docclass`` config value and made the "twoside"
+    documentclass option overridable by "oneside".
+  - Added the ``trim_doctest_flags`` config value, which is true by
+    default.
+  - Added ``html_show_copyright`` config value.
+
+* New builders:
+
+  - Added a builder for the Epub format.
+  - Added a builder for manual pages.
+  - Added a single-file HTML builder.
 
-* Allow searching for object names including the module name, like
-  ``sys.argv``.
+* HTML output:
 
-* Many improvements and fixes to the ``autosummary`` extension,
-  thanks to Pauli Virtanen.
+  - Inline roles now get a CSS class with their name, allowing styles to
+    customize their appearance.  Domain-specific roles get two classes,
+    ``domain`` and ``domain-rolename``.
+  - References now get the class ``internal`` if they are internal to
+    the whole project, as opposed to internal to the current page.
+  - #129: Toctrees are now wrapped in a ``div`` tag with class
+    ``toctree-wrapper`` in HTML output.
+  - The ``toctree()`` callable in templates now has a ``maxdepth``
+    keyword argument to control the depth of the generated tree.
+  - Added ``htmltitle`` block in layout template.
+  - In the JavaScript search, allow searching for object names including
+    the module name, like ``sys.argv``.
+  - Added new theme ``haiku``, inspired by the Haiku OS user guide.
+  - Added new theme ``nature``.
+  - Added new theme ``agogo``, created by Andi Albrecht.
+  - Added new theme ``scrolls``, created by Armin Ronacher.
+  - #193: Added a ``visitedlinkcolor`` theme option to the default
+    theme.
 
-* Added ``html_show_copyright`` config value.
+* Extension API:
 
-* Added simplified Chinese locale.
+  - Added ``html-collect-pages`` event.
+  - Added ``needs_sphinx`` config value and ``Sphinx.require_sphinx``
+    application API function.
+  - #200: Added ``Sphinx.add_stylesheet()``.
 
-* Added ``latexpdf`` target in quickstart Makefile.
+* Extensions:
 
-* Added ``htmltitle`` block in layout template.
+  - Added the ``viewcode`` extension.
+  - Added the ``extlinks`` extension.
+  - Added support for source ordering of members in autodoc, with
+    ``autodoc_member_order = 'bysource'``.
+  - Added ``autodoc_default_flags`` config value, which can be used to
+    select default flags for all autodoc directives.
+  - Added a way for intersphinx to refer to named labels in other
+    projects, and to specify the project you want to link to.
+  - #280: Autodoc can now document instance attributes assigned in
+    ``__init__`` methods.
+  - Many improvements and fixes to the ``autosummary`` extension, thanks
+    to Pauli Virtanen.
+  - #309: The ``graphviz`` extension can now output SVG instead of PNG
+    images, controlled by the ``graphviz_output_format`` config value.
+  - Added ``alt`` option to ``graphviz`` extension directives.
+
+* Translations:
+
+  - Added Croatian translation, thanks to Bojan Mihelač.
+  - Added Turkish translation, thanks to Firat Ozgul.
+  - Added Catalan translation, thanks to Pau Fernández.
+  - Added simplified Chinese translation.
 
 
 Release 0.6.6 (in development)