Merge branch 'doc-add-changelog'

* clean up autogenerated API docs
* add release-notes page
* switch to sphinx_py3doc_enhanced_theme
* activate m2r for sphinx/markdown integration
* remove redundant pages
* move license to a separate page

Author: pavoljuhas

CHANGELOG.md

@@ -0,0 +1,18 @@
+# Release notes
+
+## Unreleased - Version 3.0.0
+
+Differences from version 1.2.2.
+
+### Added
+
+- Compatibility with Python 3.7, 3.6, 3.5 in addition to 2.7.
+
+### Changed
+
+- Switch to platform-independent "noarch" Anaconda package.
+
+### Deprecated
+
+- Variable `__gitsha__` in the `version` module which was renamed
+  to `__git_commit__`.

doc/manual/source/api/diffpy.rst

@@ -1,8 +1,10 @@
 diffpy.utils.parsers package
 ============================
 
-Submodules
-----------
+.. automodule:: diffpy.utils.parsers
+    :members:
+    :undoc-members:
+    :show-inheritance:
 
 diffpy.utils.parsers.loaddata module
 ------------------------------------
@@ -19,12 +21,3 @@ diffpy.utils.parsers.resample module
     :members:
     :undoc-members:
     :show-inheritance:
-
-
-Module contents
----------------
-
-.. automodule:: diffpy.utils.parsers
-    :members:
-    :undoc-members:
-    :show-inheritance:

doc/manual/source/api/diffpy.utils.parsers.rst

@@ -1,6 +1,13 @@
+:tocdepth: 2
+
 diffpy.utils package
 ====================
 
+.. automodule:: diffpy.utils
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 Subpackages
 -----------
 
@@ -19,12 +26,3 @@ diffpy.utils.version module
     :members:
     :undoc-members:
     :show-inheritance:
-
-
-Module contents
----------------
-
-.. automodule:: diffpy.utils
-    :members:
-    :undoc-members:
-    :show-inheritance:

doc/manual/source/api/diffpy.utils.rst

@@ -1,22 +1,15 @@
 diffpy.utils.wx package
 =======================
 
-Submodules
-----------
-
-diffpy.utils.wx.gridutils module
---------------------------------
-
-.. automodule:: diffpy.utils.wx.gridutils
+.. automodule:: diffpy.utils.wx
     :members:
     :undoc-members:
     :show-inheritance:
 
+diffpy.utils.wx.gridutils module
+--------------------------------
 
-Module contents
----------------
-
-.. automodule:: diffpy.utils.wx
+.. automodule:: diffpy.utils.wx.gridutils
     :members:
     :undoc-members:
     :show-inheritance:

doc/manual/source/api/diffpy.utils.wx.rst

@@ -38,13 +38,16 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
     'sphinx.ext.viewcode',
+    'm2r',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
-# The suffix of source filenames.
-source_suffix = '.rst'
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+source_suffix = ['.rst', '.md']
 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
@@ -113,13 +116,17 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+#
+html_theme = 'sphinx_py3doc_enhanced_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#html_theme_options = {}
-html_theme_options = {'collapsiblesidebar' : 'true'}
+#
+html_theme_options = {
+    'collapsiblesidebar' : 'true',
+    'navigation_with_keys' : 'true',
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = []
@@ -143,7 +150,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+#html_static_path = ['_static']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied

doc/manual/source/api/modules.rst

@@ -1,58 +1,50 @@
-.. diffpy.utils documentation master file, created by
-   sphinx-quickstart on Thu Jan 30 15:49:41 2014.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-
 ####################################################
-diffpy.utils's documentation!
+diffpy.utils documentation
 ####################################################
 
-Software version |release|.
-
-Last updated |today|.
-
 diffpy.utils - general purpose shared utilities for the diffpy libraries.
 
+| Software version |release|.
+| Last updated |today|.
+
 The diffpy.utils package provides functions for extracting array data from
 variously formatted text files and wx GUI utilities used by the PDFgui
 program.  The package also includes interpolation function based on the
 Whittaker-Shannon formula that can be used to resample a PDF or other profile
 function over a new grid.
 
+=======
+Authors
+=======
 
-===================
-Disclaimer
-===================
-
-.. literalinclude:: ../../../LICENSE.txt
+diffpy.utils is developed by members of the Billinge Group at
+Columbia University and at Brookhaven National Laboratory including
+Pavol Juhás, Timur Davis, Christopher L. Farrow, Simon J.L. Billinge.
 
-================
-Acknowledgments
-================
-
-Developers
------------
-
-diffpy.Structure is developed and maintained by
-
-.. literalinclude:: ../../../AUTHORS.txt
+For a detailed list of contributors see
+https://github.com/diffpy/diffpy.utils/graphs/contributors.
 
 ======================================
 Installation
 ======================================
 
-See the `README.rst <https://github.com/diffpy/diffpy.utils#requirements>`_
+See the `README <https://github.com/diffpy/diffpy.utils#requirements>`_
 file included with the distribution.
 
 ======================================
-API and Index
+Table of contents
 ======================================
 
 .. toctree::
-   :maxdepth: 3
+   :titlesonly:
 
-   api/diffpy.utils.rst
+   license
+   release
+   Package API <api/diffpy.utils>
+
+======================================
+Indices
+======================================
 
 * :ref:`genindex`
 * :ref:`search`

doc/manual/source/conf.py

@@ -1,3 +1,5 @@
+.. index:: license
+
 License
 #######
 

doc/manual/source/index.rst

@@ -0,0 +1,3 @@
+.. index:: release notes
+
+.. mdinclude:: ../../../CHANGELOG.md