Implement basic doc of API

docs/source/_autosummary/localite.api.rst

@@ -0,0 +1,6 @@
+localite.api
+============
+
+.. automodule:: localite.api
+    :members:
+    :undoc-members:

docs/source/_templates/module.rst

@@ -0,0 +1,6 @@
+{{ fullname }}
+{{ underline }}
+
+.. automodule:: {{ fullname }}
+    :members:
+    :undoc-members:

docs/source/conf.py

@@ -13,43 +13,86 @@
 # import os
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
-
+import pkg_resources
+from os import environ
 
 # -- Project information -----------------------------------------------------
 
-project = 'ctrl-localite'
-copyright = '2019, Robert Guggenberger'
-author = 'Robert Guggenberger'
+project = "localite"
+copyright = "2019, Robert Guggenberger"
+author = "Robert Guggenberger"
 
 # The full version, including alpha/beta/rc tags
-release = '0.3.0'
-
+release = pkg_resources.get_distribution(project.lower()).version
 
 # -- General configuration ---------------------------------------------------
+environ[
+    "DOC"
+] = "1"  #  in case we need to change behaviour while constructinjg documentation
+
 
 # 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.coverage",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.ifconfig",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.githubpages",
+    "sphinx_autodoc_typehints",  # : pip install sphinx-autodoc-typehints
+    "sphinx_rtd_theme",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+autosummary_generate = True
+add_module_names = False  # use short names for functions and classes
+
+# napoleon docstring parsing
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = False
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = True
+napoleon_use_admonition_for_examples = False
+napoleon_use_admonition_for_notes = False
+napoleon_use_admonition_for_references = False
+napoleon_use_ivar = False
+napoleon_use_param = True
+napoleon_use_rtype = True
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+source_suffix = [".rst", ".md"]
+
+# The master toctree document.
+master_doc = "index"
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = []
 
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = "sphinx"
+
 
 # -- 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 = 'alabaster'
+html_theme = "alabaster"
 
 # 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"]
+

docs/source/index.rst

@@ -10,7 +10,16 @@ Welcome to ctrl-localite's documentation!
    :maxdepth: 2
    :caption: Contents:
 
+API
+---
 
+The main interface to controlling your TMS coil with localite-flow
+
+.. autosummary::
+   :toctree: _autosummary
+   :template: module.rst
+
+   localite.api
 
 Indices and tables
 ==================

localite/api.py

@@ -1,4 +1,18 @@
-"""API
+"""
+Localite Flow
+-------------
+
+.. automodule:: localite.flow.mitm
+   :members: start, kill
+
+Controlling the Coil
+--------------------
+
+Before you can control the coil and read its parameters, make sure the localite-flow is running, e.g. with :meth:`~localite.flow.mitm.start` or the command-line-interface.
+
+
+.. automodule:: localite.coil
+   :members: Coil
 
 
 """

localite/flow/mitm.py

@@ -16,12 +16,16 @@ def start_threaded(
 
     args
     ----
+
     loc_host: str
         the ip-adress of the localite PC
+
     loc_port: int = 6666
         the port of the localite Server
-    ext: Tuple[str, int] = ("127.0.0.1", 6667)
-        the host:port where the localite-flow server will be setup    
+
+    ext: Tuple[str, int]  ("127.0.0.1", 6667)
+        the host:port where the localite-flow server will be setup 
+    
     """
     queue = Queue()
     locbox = Queue()
@@ -41,7 +45,7 @@ def start_threaded(
 
 
 def kill(ext: Tuple[str, int] = ("127.0.0.1", 6667)):
-    """kill the localite-flow at the given address
+    """ kill the localite-flow at the given address, whether it runs as a subprocess or in a local thread
 
     args
     ----
@@ -54,14 +58,16 @@ def kill(ext: Tuple[str, int] = ("127.0.0.1", 6667)):
 
 
 def start(host: str):
-    """start localite-flow in a subprocess
+    """starts the localite-flow as a subprocess
     
+    You can stop the subprocess gracefully using :meth:`~localite.flow.mitm.kill`
+
+
     args
     ----
     host: str
         the ip adress of the localite PC
 
-    stop the subprocess gracefully using :meth:`~.kill`
 
     """
     from localite.flow.ext import available

test/flow/test_mitm.py

@@ -35,7 +35,7 @@ def test_setup_tear_down(mock, capsys):
 
 
 def test_cli(mock):
-    p = start(loc_host="127.0.0.1")
+    p = start(host="127.0.0.1")
     time.sleep(1)
     o, e = Popen(["localite-flow", "--kill"], stdout=PIPE).communicate()
     assert b"poison-pill" in o