Merge branch 'doc-add-changelog'

* improve docstrings to class-registry functions
* resolve py:obj sphinx links in docstrings
* clean up autogenerated API docs
* add release-notes page
* move license to a separate page
* fix documentation project name
* activate intersphinx extension
* switch to sphinx_py3doc_enhanced_theme

Author: pavoljuhas

CHANGELOG.md

@@ -0,0 +1,41 @@
+# Release notes
+
+## Unreleased - Version 1.3.0
+
+Main differences from version 1.2.
+
+### Added
+
+- Support for Python 3.7, 3.6, 3.5 in addition to 2.7.
+- Validation of compiler options from `python-config`.
+- Make scons scripts compatible with Python 3 and Python 2.
+- `ConstantPeakWidth` attributes `uisowidth`, `bisowidth` to ease
+  PDF simulation with uniform isotropic atom displacements.
+
+### Changed
+
+- Require libdiffpy 1.4 or later.
+- Build Anaconda package with Anaconda C++ compiler.
+- Allow language standard c++11.
+- Pickle format for `PDFCalculator`, `DebyePDFCalculator`,
+  `OverlapCalculator`, `PeakWidthModel`, `PeakProfile`, `PDFEnvelope`,
+  `PDFBaseline`, and `ScatteringFactorTable` objects.
+
+### Deprecated
+
+- Variable `__gitsha__` in the `version` module renamed to `__git_commit__`.
+- `libdiffpy_version_info` attribute `git_sha` renamed to `git_commit`.
+
+### Removed
+
+- Unused method `BVParam.__hash__`.
+- Disable pickling of `BasePairQuantity` as it is in effect abstract.
+- Pickling of Python-added attributes to exported C++ classes.
+- Function `get_libdiffpy_version_info` from the `version` module.
+
+### Fixed
+
+- Return value conversion of `CrystalStructureAdapter` methods
+  `expandLatticeAtom` and `getEquivalentAtoms` methods.
+  Make them return a `list` of `Atom` objects.
+- Name suffix resolution of `boost_python` shared library.

doc/manual/source/api/diffpy.rst

@@ -1,6 +1,15 @@
+:tocdepth: 2
+
+.. default-role:: py:obj
+
 diffpy.srreal package
 =====================
 
+.. automodule:: diffpy.srreal
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 Submodules
 ----------
 
@@ -141,13 +150,7 @@ diffpy.srreal.structureadapter module
     :undoc-members:
     :show-inheritance:
 
-diffpy.srreal.structureconverters module
-----------------------------------------
-
-.. automodule:: diffpy.srreal.structureconverters
-    :members:
-    :undoc-members:
-    :show-inheritance:
+.. skip internal module diffpy.srreal.structureconverters
 
 diffpy.srreal.version module
 ----------------------------
@@ -157,19 +160,4 @@ diffpy.srreal.version module
     :undoc-members:
     :show-inheritance:
 
-diffpy.srreal.wraputils module
-------------------------------
-
-.. automodule:: diffpy.srreal.wraputils
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-
-Module contents
----------------
-
-.. automodule:: diffpy.srreal
-    :members:
-    :undoc-members:
-    :show-inheritance:
+.. skip internal module diffpy.srreal.wraputils

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

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 #
-# diffpy.SrReal documentation build configuration file, created by
+# diffpy.srreal documentation build configuration file, created by
 # sphinx-quickstart on Tue Oct 22 12:02:48 2013.
 #
 # This file is execfile()d with the current directory set to its containing dir.
@@ -12,17 +12,18 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
+import sys
+import os
 import time
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-# sys.path.insert(0, os.path.abspath('.'))
-# sys.path.insert(0, os.path.abspath('../../..'))
+#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('../../..'))
 
 # abbreviations
-ab_authors = 'Pavol Juhás, Christopher L. Farrow, Simon J.L. Billinge group'
+ab_authors = u'Pavol Juhás, Christopher L. Farrow, Simon J.L. Billinge group'
 
 # -- General configuration -----------------------------------------------------
 
@@ -31,14 +32,21 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest',
-              'sphinx.ext.coverage', 'sphinx.ext.napoleon']
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.coverage',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.intersphinx',
+    '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'
@@ -47,16 +55,14 @@
 master_doc = 'index'
 
 # General information about the project.
-project = 'SrReal'
+project = 'diffpy.srreal'
 copyright = '%Y, Brookhaven National Laboratory'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
-sys.path.insert(0, os.path.abspath('../../..'))
 from setup import versiondata
 fullversion = versiondata.get('DEFAULT', 'version')
-sys.path.remove(os.path.abspath('../../..'))
 # The short X.Y version.
 version = ''.join(fullversion.split('.post')[:1])
 # The full version, including alpha/beta/rc tags.
@@ -108,13 +114,15 @@
 
 # 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 = []
@@ -182,7 +190,7 @@
 # html_file_suffix = None
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'SrRealdoc'
+htmlhelp_basename = 'srrealdoc'
 
 
 # -- Options for LaTeX output --------------------------------------------------
@@ -201,7 +209,7 @@
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-    ('index', 'SrReal_manual.tex', 'SrReal Documentation',
+    ('index', 'diffpy.srreal.tex', 'diffpy.srreal Documentation',
      ab_authors, 'manual'),
 ]
 
@@ -231,7 +239,7 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'srreal', 'SrReal Documentation',
+    ('index', 'diffpy.srreal', 'diffpy.srreal Documentation',
      ab_authors, 1)
 ]
 
@@ -245,8 +253,8 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    ('index', 'SrReal', 'SrReal Documentation',
-     ab_authors, 'SrReal', 'One line description of project.',
+    ('index', 'diffpy.srreal', 'diffpy.srreal Documentation',
+     ab_authors, 'diffpy.srreal', 'One line description of project.',
      'Miscellaneous'),
 ]
 
@@ -261,4 +269,7 @@
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-# intersphinx_mapping = {'http://docs.python.org/': None}
+intersphinx_mapping = {
+    'numpy': ('https://docs.scipy.org/doc/numpy', None),
+    'python' : ('https://docs.python.org/3.7', None),
+}

doc/manual/source/api/modules.rst

@@ -1,18 +1,11 @@
-.. SrReal documentation master file, created by
-   sphinx-quickstart on Tue Oct 22 12:02:48 2013.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 ####################################################
 diffpy.srreal documentation
 ####################################################
 
-Software version |release|.
-
-Last updated |today|.
-
-diffpy.srreal - calculators for PDF, bond valence sum and other pair quantities
+diffpy.srreal - calculators for PDF, bond valence sum and other pair quantities.
 
+| Software version |release|.
+| Last updated |today|.
 
 The diffpy.srreal package provides calculators for atomic pair distribution
 function (PDF), bond valence sums (BVS), atom overlaps for a hard-sphere
@@ -44,41 +37,39 @@ calculate PDF with a user-defined profile function.  A new calculator class
 can be also defined for any quantity that is obtained by iteration over atom
 pairs, by defining only the function that processes atom-pair contributions.
 
-===================
-Disclaimer
-===================
-
-.. literalinclude:: ../../../LICENSE.txt
-
-================
-Acknowledgments
-================
-
-Developers
------------
-
-diffpy.srreal is developed and maintained by
+========================================
+Authors
+========================================
 
-.. literalinclude:: ../../../AUTHORS.txt
+diffpy.srreal is developed by members of the Billinge Group at
+Columbia University and at Brookhaven National Laboratory including
+Pavol Juhás, Christopher L. Farrow, Simon J.L. Billinge.
 
+For a detailed list of contributors see
+https://github.com/diffpy/diffpy.srreal/graphs/contributors.
 
 ======================================
 Installation
 ======================================
 
-See the `README.rst <https://github.com/diffpy/diffpy.srreal#requirements>`_
+See the `README <https://github.com/diffpy/diffpy.srreal#requirements>`_
 file included with the distribution.
 
-
 ======================================
-API and Index
+Table of contents
 ======================================
 
 .. toctree::
-   :maxdepth: 2
-   
-   api/diffpy.srreal.rst
-   
+   :titlesonly:
+
+   license
+   release
+   Package API <api/diffpy.srreal>
+
+======================================
+Indices
+======================================
+
 * :ref:`genindex`
 * :ref:`modindex`
 * :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