docs: fix documentation rendering

docs/source/api/diffpy.srreal.rst

@@ -10,21 +10,142 @@
     :undoc-members:
     :show-inheritance:
 
-Subpackages
------------
-
-.. toctree::
-   diffpy.srreal.example_package
-
 Submodules
 ----------
 
-|module|
---------
+diffpy.srreal.atomradiitable module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.srreal.atomradiitable
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+diffpy.srreal.attributes module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.srreal.attributes
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.srreal.bondcalculator module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.srreal.bondcalculator
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.srreal.bvparameterstable module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.srreal.bvparameterstable
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.srreal.bvscalculator module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.srreal.bvscalculator
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.srreal.eventticker module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.srreal.eventticker
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.srreal.overlapcalculator module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.srreal.overlapcalculator
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.srreal.overlapcalculator module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.srreal.overlapcalculator
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.srreal.pairquantity module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.srreal.pairquantity
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.srreal.parallel module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.srreal.parallel
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.srreal.pdfbaseline module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.srreal.pdfbaseline
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.srreal.pdfcalculator module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.srreal.pdfcalculator
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.srreal.pdfenvelope module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.srreal.pdfenvelope
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.srreal.peakprofile module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.srreal.peakprofile
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.srreal.peakwidthmodel module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.srreal.peakwidthmodel
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.srreal.scatteringfactortable module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.srreal.scatteringfactortable
+    :members:
+    :undoc-members:
+    :show-inheritance:
 
-.. |module| replace:: diffpy.srreal.example_submodule module
+diffpy.srreal.sfaverage module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. automodule:: diffpy.srreal.example_submodule
+.. automodule:: diffpy.srreal.sfaverage
     :members:
     :undoc-members:
     :show-inheritance:

docs/source/examples.rst

@@ -1,4 +1,22 @@
-.. _examples:
+.. _developers-guide-examples:
 
+===================
 Examples
-########
+===================
+
+.. This creates the links from the filenames within README to pages.
+.. _compareC60PDFs_objcryst.py: examples/compareC60PDFs_objcryst.html
+.. _compareC60PDFs.py: examples/compareC60PDFs.html
+.. _distanceprinter.py: examples/distanceprinter.html
+.. _parallelPDF.py: examples/parallelPDF.html
+
+
+Files
+-----
+
+.. toctree::
+
+   examples/compareC60PDFs_objcryst.rst
+   examples/compareC60PDFs.rst
+   examples/distanceprinter.rst
+   examples/parallelPDF.rst

docs/source/examples/compareC60PDFs.rst

@@ -0,0 +1,7 @@
+.. _compareC60PDFs.rst:
+
+==========================
+compareC60PDFs.py
+==========================
+
+.. literalinclude:: ../../examples/compareC60PDFs.py

docs/source/examples/compareC60PDFs_objcryst.rst

@@ -0,0 +1,7 @@
+.. _compareC60PDFs_objcryst.py:
+
+==========================
+compareC60PDFs_ObjCryst.py
+==========================
+
+.. literalinclude:: ../../examples/compareC60PDFs_objcryst.py

docs/source/examples/distanceprinter.rst

@@ -0,0 +1,7 @@
+.. _distanceprinter.py:
+
+===========================
+distanceprinter.py
+===========================
+
+.. literalinclude:: ../../examples/distanceprinter.py

docs/source/examples/parallelPDF.rst

@@ -0,0 +1,7 @@
+.. _parallelPDF.py:
+
+===========================
+parallelPDF.py
+===========================
+
+.. literalinclude:: ../../examples/parallelPDF.py

news/fix-docstring.rst

@@ -0,0 +1,23 @@
+**Added:**
+
+* No news added: Fix documentation rendering.
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

src/diffpy/srreal/atomradiitable.py

@@ -35,7 +35,10 @@ class CovalentRadiiTable(AtomRadiiTable):
     def _standardLookup(self, smbl):
         """Return covalent atom radius in Angstroms.
 
-        smbl -- string symbol of an element
+        Attributes
+        ----------
+        smbl
+            string symbol of an element
 
         Return float.  Raise ValueError for unknown element symbol.
         """

src/diffpy/srreal/bondcalculator.py

@@ -58,9 +58,13 @@ def _init_kwargs(self, **kwargs):
 def _call_kwargs(self, structure=None, **kwargs):
     """Return sorted bond distances in the specified structure.
 
-    structure    -- structure to be evaluated, an instance of diffpy Structure
-                    or pyobjcryst Crystal.  Reuse the last structure when None.
-    kwargs       -- optional parameter settings for this calculator
+    Attributes
+    ----------
+    structure
+        structure to be evaluated, an instance of diffpy Structure
+        or pyobjcryst Crystal.  Reuse the last structure when None.
+    kwargs
+        optional parameter settings for this calculator
 
     Return a sorted numpy array.
     """

src/diffpy/srreal/bvscalculator.py

@@ -75,9 +75,13 @@ def _init_kwargs(self, **kwargs):
 def _call_kwargs(self, structure=None, **kwargs):
     """Return bond valence sums at each atom site in the structure.
 
-    structure    -- structure to be evaluated, an instance of diffpy Structure
-                    or pyobjcryst Crystal.  Reuse the last structure when None.
-    kwargs       -- optional parameter settings for this calculator
+    Attributes
+    ----------
+    structure
+        structure to be evaluated, an instance of diffpy Structure
+        or pyobjcryst Crystal.  Reuse the last structure when None.
+    kwargs
+        optional parameter settings for this calculator
 
     Return an array of calculated valence sums.
     See valences for the expected values.

src/diffpy/srreal/devutils/tunePeakPrecision.py

@@ -54,7 +54,10 @@
 def Gpdffit2(qmax):
     """Calculate reference nickel PDF using diffpy.pdffit2.
 
-    qmax    -- vawevector cutoff value in 1/A
+    Attributes
+    ----------
+    qmax
+        vawevector cutoff value in 1/A
 
     Return numpy array of (r, g).
     """
@@ -70,9 +73,13 @@ def Gpdffit2(qmax):
 def Gsrreal(qmax, peakprecision=None):
     """Calculate nickel PDF using PDFCalculator from diffpy.srreal.
 
-    qmax            -- vawevector cutoff value in 1/A
-    peakprecision   -- precision factor affecting peak cutoff,
-                       keep at default value when None.
+    Attributes
+    ----------
+    qmax
+        vawevector cutoff value in 1/A
+    peakprecision
+        precision factor affecting peak cutoff,
+        keep at default value when None.
 
     Return numpy array of (r, g).
     """
@@ -91,19 +98,30 @@ def Gsrreal(qmax, peakprecision=None):
 def comparePDFCalculators(qmax, peakprecision=None):
     """Compare Ni PDF calculations with pdffit2 and PDFCalculator.
 
-    qmax            -- vawevector cutoff value in 1/A
-    peakprecision   -- precision factor affecting peak cutoff,
-                       keep at default value when None.
+    Attributes
+    ----------
+    qmax
+        vawevector cutoff value in 1/A
+    peakprecision
+        precision factor affecting peak cutoff,
+        keep at default value when None.
 
     Return a dictionary of benchmark results with the following keys:
 
-    qmax    -- vawevector cutoff value
-    peakprecision -- actual peak precision used in PDFCalculator
-    r       -- common r-grid for the PDF arrays
-    g0, g1  -- calculated PDF curves from pdffit2 and PDFCalculator
-    gdiff   -- PDF difference equal (g0 - g1)
-    grmsd   -- root mean square value of PDF curves difference
-    t0, t1  -- CPU times used by pdffit2 and PDFCalculator calls
+    Attributes
+    ----------
+    qmax
+        vawevector cutoff value
+    peakprecision
+        actual peak precision used in PDFCalculator
+    r
+        common r-grid for the PDF arrays
+        g0, g1  -- calculated PDF curves from pdffit2 and PDFCalculator
+    gdiff
+        PDF difference equal (g0 - g1)
+    grmsd
+        root mean square value of PDF curves difference
+        t0, t1  -- CPU times used by pdffit2 and PDFCalculator calls
     """
     rv = {}
     rv["qmax"] = qmax
@@ -147,7 +165,10 @@ def processCommandLineArguments():
 def plotComparison(cmpdata):
     """Plot comparison of PDF curves.
 
-    cmpdata -- dictionary returned from comparePDFCalculators
+    Attributes
+    ----------
+    cmpdata
+        dictionary returned from comparePDFCalculators
 
     No return value.
     """