docs: begin migration to rtd

.readthedocs.yml

@@ -0,0 +1,5 @@
+formats:
+ - pdf
+requirements_file: docs/requirements.txt
+python:
+   version: 3

CHANGELOG

@@ -5,6 +5,7 @@
    - Add recording date/time tooltip in the analysis tab to avoid
      ambiguities (#223)
  - Automated release to PyPI with appveyor
+ - Begin migration of docs to sphinx/readthedocs.org
 0.8.6
  - Refactoring:
    - Use pathlib instead of os.path for
@@ -131,7 +132,7 @@
  - Define new configuration file path with appdirs
  - Add on-the-fly computation of volume (dclab 0.2.3.dev23)
  - Change: Disable "remove invalid events" in filtering to
-  avoid computation of ancillary columns (performance)
+   avoid computation of ancillary columns (performance)
 0.7.4
  - Add de-/select all buttons to Batch | Statistical analysis
  - Add de-/select all buttons to export all events data (#148)
@@ -211,7 +212,7 @@
  - Bugfixes:
    - Loading of sessions with hierarchy children failed (#99)
    - Reduced a memory leak for new analyses that resulted in frequent
-    memory errors (should be less frequent now)
+     memory errors (should be less frequent now)
 0.6.4
  - Bugfixes:
    - Batch analysis: Individual measurement parameters not preserved (#96)
@@ -225,7 +226,7 @@
    - Regression: Excluded events plotted on top of filtered events (#86)
    - PDF plot export: Scatter inspector event highlighted (#92)
  - Implement differential (w.r.t. reservoir) linear-mixed models
-  analysis with bootstrapping (#88)
+   analysis with bootstrapping (#88)
 0.6.2
  - Add batch filter processing
  - Move statistics computation to dclab (0.1.7.dev12):
@@ -257,7 +258,7 @@
  - Allow logarithmic plot axes (#56)
  - Display fluorescence curve of events (#65)
  - Bugfixes:
-   - OpenCV version 2 vs 3 variable name differences (CV_CAP_...)
+   - OpenCV version 2 vs 3 variable name differences (CV_CAP...)
    - Gray dots in PDF export too large (#69)
 0.5.8
  - dclab add fluorescence channels: peak area, peak position, number of peaks

docs/README.md

@@ -0,0 +1,10 @@
+ShapeOut documentation
+======================
+To install the requirements for building the documentation, run
+
+    pip install -r requirements.txt
+
+To compile the documentation, run
+
+    sphinx-build . _build
+

docs/conf.py

@@ -0,0 +1,219 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# ShapeOut documentation build configuration file, created by
+# sphinx-quickstart on Tue Sep 26 17:55:31 2017.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+# 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.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+# Get version number from shapeout._version file
+import mock
+import os.path as op
+import sys
+# include parent directory
+pdir = op.dirname(op.dirname(op.abspath(__file__)))
+sys.path.insert(0, pdir)
+# include extenstions
+sys.path.append(op.abspath('extensions'))
+
+# Mock all dependencies
+install_requires=["fcswrite",
+                  "imageio",
+                  "nptdms",
+                  "statsmodels",
+                  "statsmodels.nonparametric",
+                  "statsmodels.nonparametric.kernel_density",
+                  "wx", "wxPython",
+                  ]
+
+for mod_name in install_requires:
+    sys.modules[mod_name] = mock.Mock()
+
+# included external libs
+sys.modules["shapeout.features._skimage_measure"] = mock.Mock()
+
+# http://www.sphinx-doc.org/en/stable/ext/autodoc.html#confval-autodoc_member_order
+# Order class attributes and functions in separate blocks
+autodoc_member_order = 'groupwise'
+autodoc_mock_imports = install_requires
+autoclass_content = 'both'
+
+# include source of matplotlib plots
+plot_include_source = True
+
+# Display link to GitHub repo instead of doc on rtfd
+rst_prolog = """
+:github_url: https://github.com/ZELLMECHANIK-DRESDEN/ShapeOut
+"""
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# 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.autosummary',
+              'sphinx.ext.intersphinx',
+              'sphinx.ext.mathjax',
+              'sphinx.ext.viewcode',
+              'sphinx.ext.napoleon',
+              'sphinxcontrib.bibtex',
+              'matplotlib.sphinxext.plot_directive',
+              'IPython.sphinxext.ipython_directive',
+              'IPython.sphinxext.ipython_console_highlighting',
+              'sphinxarg.ext',
+              'fancy_include',
+              'github_changelog',
+              'dclab_defs',
+              ]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = 'ShapeOut'
+github_project = 'ZELLMECHANIK-DRESDEN/' + project
+copyright = '2015, Paul Müller'
+author = 'Paul Müller'
+
+# 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.
+#
+# The short X.Y version.
+# 
+# The full version, including alpha/beta/rc tags.
+# This gets 'version'
+exec(open(op.join(pdir, "shapeout/_version.py")).read())
+release = version #@UndefinedVariable
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'default'
+
+# 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 = {}
+
+# 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 = ['data']
+
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'shapeoutdoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'shapeout.tex', 'ShapeOut Documentation',
+     'Paul Müller', 'manual'),
+]
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'shapeout', 'ShapeOut Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'shapeout', 'ShapeOut Documentation',
+     author, 'shapeout', 'post-measurement analysis of RT-DC data sets',
+     'Scientific'),
+]
+
+
+
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {"python": ('https://docs.python.org/', None),
+                       "numpy": ('http://docs.scipy.org/doc/numpy', None),
+                       "scipy": ('https://docs.scipy.org/doc/scipy/reference/', None),
+                       "dclab": ('http://dclab.readthedocs.io/en/stable', None),
+                       }

docs/extensions/dclab_defs.py

@@ -0,0 +1,112 @@
+"""visualization of dclab definitions
+
+Usage
+-----
+Directives:
+
+List of features with arguments "all", "scalar", or "non-scalar"
+
+   .. dclab_features::
+
+List of configuration keys with arguments "analysis", "metadata", or a
+configuration key section (e.g. "experiment").
+
+   .. dclab_config::
+
+"""
+from docutils.statemachine import ViewList
+from docutils.parsers.rst import Directive
+from sphinx.util.nodes import nested_parse_with_titles
+from docutils import nodes
+
+from dclab import definitions as dfn
+
+
+class Base(Directive):
+    required_arguments = 1
+    optional_arguments = 0
+
+    def generate_rst(self):
+        pass        
+
+    def run(self):
+        rst = self.generate_rst()
+
+        vl = ViewList(rst, "fakefile.rst")
+        # Create a node.
+        node = nodes.section()
+        node.document = self.state.document
+        # Parse the rst.
+        nested_parse_with_titles(self.state, vl, node)
+        return node.children
+
+
+class Config(Base):
+    def generate_rst(self):
+        which = self.arguments[0]
+        rst = []
+
+        if which == "analysis":
+            cfg = dfn.CFG_ANALYSIS
+        elif which == "metadata":
+            cfg = dfn.CFG_METADATA
+        else:
+            cfg = dfn.CFG_ANALYSIS.copy()
+            cfg.update(dfn.CFG_METADATA)
+            cfg = {which: cfg[which]}
+
+        for key in sorted(cfg.keys()):
+            rst.append("")
+            rst.append(".. csv-table::")
+            rst.append("    :header: {}, parsed, description [units]".format(key))
+            rst.append("    :widths: 30, 10, 60")
+            rst.append("    :delim: tab")
+            rst.append("")
+
+
+            for item in sorted(cfg[key]):
+                if item[1] is str:
+                    ref = ":class:`str`"
+                elif item[1] is float:
+                    ref = ":class:`float`"
+                else:
+                    ref = ":func:`{f} <dclab.parse_funcs.{f}>`".format(f=item[1].__name__)
+                rst.append("    {}\t {}\t {}".format(item[0],
+                                                     ref,
+                                                     item[2]))
+
+            rst.append("")
+
+        return rst
+
+
+class Features(Base):
+    def generate_rst(self):
+        which = self.arguments[0]
+        rst = []
+
+        if which == "all":
+            feats = sorted(dfn.FEATURES_SCALAR + dfn.FEATURES_NON_SCALAR)
+        elif which == "scalar":
+            feats = sorted(dfn.FEATURES_SCALAR)
+        elif which == "non-scalar":
+            feats = sorted(dfn.FEATURES_NON_SCALAR)    
+
+        rst.append(".. csv-table::")
+        rst.append("    :header: {} features, description [units]".format(which))
+        rst.append("    :widths: 2, 7")
+        rst.append("    :delim: tab")
+        rst.append("")
+
+        for item in feats:
+            rst.append("    {}\t {}".format(item[0], item[1]))
+
+        rst.append("")
+
+        return rst
+
+
+def setup(app):
+    app.add_directive('dclab_features', Features)
+    app.add_directive('dclab_config', Config)
+    return {'version': '0.1'}   # identifies the version of our extension