Merge pull request #33 from tomography/docs

versioning and docs fix

docs/source/api/xdesign.acquisition.rst

@@ -5,14 +5,17 @@
    :members:
    :show-inheritance:
    :undoc-members:
+   :synopsis: Defines objects related to collection and organization of probe data.
 
    .. rubric:: **Functions:**
 
    .. autosummary::
-   
+
       Beam
       Probe
       sinogram
       angleogram
       raster_scan
       angle_scan
+
+.. moduleauthor:: Doga Gursoy <[email protected]>

docs/source/api/xdesign.algorithms.rst

@@ -5,13 +5,16 @@
    :members:
    :show-inheritance:
    :undoc-members:
+   :synopsis: Defines methods for reconstructing data from the :mod:`.acquisition` module.
 
    .. rubric:: **Functions:**
 
    .. autosummary::
-   
+
       reconstruct
       art
       sirt
       mlem
       stream
+
+.. moduleauthor:: Doga Gursoy <[email protected]>

docs/source/api/xdesign.feature.rst

@@ -5,9 +5,12 @@
    :members:
    :show-inheritance:
    :undoc-members:
+   :synopsis: Defines an object for spatial organizing materials properties.
 
    .. rubric:: **Functions:**
 
    .. autosummary::
-   
+
       Feature
+
+.. moduleauthor:: Daniel J Ching <[email protected]>

docs/source/api/xdesign.geometry.rst

@@ -4,17 +4,22 @@
 .. automodule:: xdesign.geometry
    :members:
    :show-inheritance:
+   :inherited-members:
    :undoc-members:
+   :synopsis: Defines geometric objects for the purpose of supporting :class:`.Feature` definition and calculating intersections for the :mod:`.acquisition` module.
 
-   .. rubric:: **Functions:**
+   .. rubric:: **Classes:**
 
    .. autosummary::
-
+      Entity
       Point
-      Superellipse
-      Ellipse
       Circle
       Line
       Triangle
       Rectangle
       Square
+      Polygon
+      Mesh
+
+.. moduleauthor:: Doga Gursoy <[email protected]>
+.. moduleauthor:: Daniel J Ching <[email protected]>

docs/source/api/xdesign.material.rst

@@ -5,11 +5,12 @@
    :members:
    :show-inheritance:
    :undoc-members:
+   :synopsis: Defines objects which auto-generate a parameterized :class:`.Phantom`.
 
    .. rubric:: **Functions:**
 
    .. autosummary::
-   
+
       Material
       HyperbolicConcentric
       DynamicRange
@@ -24,6 +25,5 @@
       SoftBiomaterial
       Electronics
       FiberComposite
-
-
 
+.. moduleauthor:: Daniel J Ching <[email protected]>

docs/source/api/xdesign.metrics.rst

@@ -5,19 +5,21 @@
    :members:
    :show-inheritance:
    :undoc-members:
+   :synopsis: Objects and methods for computing the quality of reconstructions.
 
    .. rubric:: **Functions:**
 
    .. autosummary::
-   
+
       ImageQuality
       probability_mask
       compute_quality
       compute_PCC
       compute_likeness
       compute_background_ttest
       compute_mtf
+      compute_mtf_siemens
       compute_nps
       compute_neq
-      compute_mtf_siemens
-       
+
+.. moduleauthor:: Daniel J Ching <[email protected]>

docs/source/api/xdesign.phantom.rst

@@ -5,9 +5,12 @@
    :members:
    :show-inheritance:
    :undoc-members:
+   :synopsis: Defines an object for organizing :class:`.Feature`.
 
    .. rubric:: **Functions:**
 
    .. autosummary::
-   
+
       Phantom
+
+.. moduleauthor:: Daniel J Ching <[email protected]>

docs/source/api/xdesign.plot.rst

@@ -1,27 +1,26 @@
 :mod:`xdesign.plot`
-===================
+====================
 
 .. automodule:: xdesign.plot
    :members:
    :show-inheritance:
    :undoc-members:
+   :synopsis: Contains functions for visualizing :class:`.Phantom` and :class:`.ImageQuality` metrics.
 
    .. rubric:: **Functions:**
 
    .. autosummary::
-
+
+      sidebyside
+      discrete_phantom
       plot_phantom
       plot_feature
       plot_mesh
       plot_polygon
       plot_curve
-      discrete_phantom
-      sidebyside
-      multiroll
       plot_metrics
       plot_mtf
       plot_nps
       plot_neq
-      plot_histograms
-
-
+
+.. moduleauthor:: Daniel J Ching <[email protected]>

docs/source/conf.py

@@ -306,14 +306,13 @@
 #texinfo_appendices = []
 
 # If false, no module index is generated.
-#texinfo_domain_indices = True
+# texinfo_domain_indices = True
 
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
-#texinfo_show_urls = 'footnote'
+# texinfo_show_urls = 'footnote'
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
-#texinfo_no_detailmenu = False
-
+# texinfo_no_detailmenu = False
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'https://docs.python.org/': None}

docs/source/index.rst

@@ -6,26 +6,26 @@ XDesign
 .. image:: img/xdesign-logo.png
    :width: 320px
    :alt: XDesign
-   
-   
+
+
 **XDesign** is an open-source Python package for generating
-configurable simulation phantoms for benchmarking tomographic 
+configurable simulation phantoms for benchmarking tomographic
 image reconstruction.
 
 .. toctree::
    :maxdepth: 1
 
    api
    examples
-   refs
+   zrefs
 
 Features
 ========
 
 * Configurable analytic 2D phantoms.
 * Various visualization tools for statistics.
 * Analytic projection operators.
-    
+
 Contribute
 ==========
 
@@ -37,7 +37,7 @@ Contribute
 License
 =======
 
-The project is licensed under the 
+The project is licensed under the
 `BSD-3 <https://github.com/tomography/xdesign/blob/master/LICENSE.txt>`_ license.
 
 Indices and tables

docs/source/refs.rst → docs/source/zrefs.rst

@@ -4,4 +4,4 @@ References
 
 .. bibliography:: bibtex/refs.bib
    :style: plain
-   :all:
+   :cited:

setup.py

@@ -47,18 +47,16 @@
 # #########################################################################
 
 import setuptools
-from version_hashtag import append_dev_info
+from version_hashtag import retrieve_version_from_git
 
-version_info = (0, 2, 0)
-version = '.'.join([str(x) for x in version_info])
-version = append_dev_info(version)
+version = retrieve_version_from_git()
 with open('VERSION', 'w') as f:
     f.write(version)
 
 setuptools.setup(
     name='xdesign',
     version=version,
-    author='Doga Gursoy',
+    author='Daniel Ching, Doga Gursoy',
     description='Benchmarking and optimization tools for tomography.',
     packages=setuptools.find_packages(exclude=['docs']),
     include_package_data=True,

version_hashtag.py

@@ -33,82 +33,42 @@
 import os.path
 import subprocess
 
-path_to_hashfile = os.path.join(os.path.dirname(__file__), "commit_hash.txt")
 
-
-def retrieve_git_info():
-    """Prints the commit hash of HEAD to a file called 'commit_hash.txt'.
-    If the git command fails, it prints 'unknown-commit'.
-    If HEAD has tag with prefix "vM" where M is an integer, it prints an empty
-    str. Tags with such names are regarded as version or release tags.
-    Otherwise, it prints the commit hash as str.
+def retrieve_version_from_git():
+    """Returns a string.
+    If the git command fails, it returns 'unknown-commit'.
+    If HEAD has tag with prefix "vM" where M is an integer, it returns the tag.
+    If HEAD has any other tag, it returns "dev-" plus the tag.
     """
     if os.path.exists('.git'):
         # Is Git installed?
         try:
             subprocess.call(['git', '--version'],
                             stdout=subprocess.PIPE)
         except OSError:
-            return None
-        # Decide whether this is a release
+            return "unknown.commit"
+
+        # Get a tag from git.
         p = subprocess.Popen(
-            ['git', 'describe', '--tags', '--candidates=0', 'HEAD'],
+            ['git', 'describe', '--tags', 'HEAD'],
             stdout=subprocess.PIPE,
             stderr=subprocess.STDOUT)
         p.wait()
         if p.returncode == 0:
             tag = p.stdout.read().decode('utf-8')
+            if tag.endswith('\n'):
+                tag = tag[:-1]
             if len(tag) >= 2 and tag.startswith('v'):
+                # It's probably a version number
                 try:
                     int(tag[1])
-                    return 'release'
                 except ValueError:
-                    pass
-        # Otherwise, return commit hash
-        p = subprocess.Popen(
-            ['git', 'log', '-1', '--format=%H'],
-            stdout=subprocess.PIPE)
-        p.wait()
-        sha1 = p.stdout.read().decode('utf-8')
-
-        # Provide commit hash or empty file to indicate release
-        if sha1 is None:
-            sha1 = 'unknown-commit'
-        elif sha1 == 'release':
-            sha1 = ''
-        commit_hash_header = (
-            '# DO NOT EDIT!  '
-            'This file was automatically generated by setup.py')
-        with open(path_to_hashfile, 'w') as f:
-            f.write(commit_hash_header + '\n')
-            f.write(sha1 + '\n')
-
-
-def append_dev_info(version):
-    """Append annotation to version string to indicate development versions. An
-    empty (modulo comments and blank lines) commit_hash.txt is used to indicate
-    a release, in which case nothing is appended to version string as defined
-    above.
-    """
-    retrieve_git_info()
-
-    if os.path.exists(path_to_hashfile):
-        commit_hash = ""
-        with open(path_to_hashfile, "r") as f:
-            for line in f:
-                line = line.strip()
-                if len(line) == 0 or line[0] == '#':
-                    # Ignore blank lines and comments, the latter being
-                    # any line that begins with #.
-                    continue
-
-                # First non-blank line is assumed to be the commit hash
-                commit_hash = line
-                break
-
-        if len(commit_hash) > 0:
-            version += ".dev0+" + commit_hash
-    else:
-        version += ".dev0+unknown.commit"
+                    return 'dev0+' + tag
+                # Get create a PEP440 compliant version number.
+                if tag.find('-') < 0:
+                    return tag[1:]
+                else:
+                    split = tag.find('-')
+                    return tag[1:split] + '+dev' + tag[split+1:].replace('-','.')
 
-    return version
+        return "unknown.commit"