Initial working Python API docs drop.

Author: jeromekelleher

docs/Makefile

@@ -9,7 +9,7 @@ BUILDDIR      = _build
 
 DOXYGEN_XML=doxygen/xml
 
-all: ${DOXYGEN_XML}
+all: #${DOXYGEN_XML}
 	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 ${DOXYGEN_XML}: ../c/kastore.h

docs/_static/README

@@ -0,0 +1 @@
+Placeholder file to keep git happy.

docs/c-api.rst

@@ -1,135 +1,6 @@
 .. _sec_c_api:
 
-===================
-C API Documentation
-===================
-
-This is the C API documentation for kastore.
-
-.. todo:: Give a short example program.
-
-
-******************
-General principles
-******************
-
---------------
-Error handling
---------------
-
-Functions return 0 to indicate success or an
-:ref:`error code <sec_c_api_error_codes>` to indicate a failure condition.
-Thus, the return value of all functions must be checked to ensure safety.
-
--------------
-Array lengths
--------------
-
-The length of arrays is specified in terms of the number of elements not bytes.
-
-*********
-Top level
-*********
-
-.. doxygenstruct:: kastore_t
-
-.. doxygenfunction:: kastore_open
-.. doxygenfunction:: kastore_close
-
-.. doxygenfunction:: kas_strerror
-
-.. _sec_c_api_get:
-
-*************
-Get functions
-*************
-
-Get functions provide the interface for querying a store. The most general interface
-is :c:func:`kastore_get`, but it is usually more convenient to use one of the
-:ref:`typed get functions <sec_c_api_typed_get>`.
-
-.. doxygenfunction:: kastore_get
-.. doxygenfunction:: kastore_gets
-
-.. _sec_c_api_typed_get:
-
-----------
-Typed gets
-----------
-
-The functions listed here provide a convenient short-cut for accessing arrays
-where the key is a standard NULL terminated C string and the type of the
-array is known in advance.
-
-.. doxygengroup:: TYPED_GETS_GROUP
-        :content-only:
-
-.. _sec_c_api_put:
-
-*************
-Put functions
-*************
-
-Put functions provide the interface for inserting data into store. The most
-general interface is :c:func:`kastore_put` which allows keys to be arbitrary
-bytes, but it is usually more convenient to use one of the :ref:`typed put
-functions <sec_c_api_typed_put>`.
-
-.. doxygenfunction:: kastore_put
-.. doxygenfunction:: kastore_puts
-
-.. _sec_c_api_typed_put:
-
-----------
-Typed puts
-----------
-
-The functions listed here provide a convenient short-cut for inserting
-key-array pairs where the key is a standard NULL terminated C string and the
-type of the array is known in advance.
-
-.. doxygengroup:: TYPED_PUTS_GROUP
-        :content-only:
-
-
-*********
-Constants
-*********
-
-.. _sec_c_api_error_codes:
-
-------
-Errors
-------
-
-.. doxygengroup:: ERROR_GROUP
-        :content-only:
-
------
-Types
------
-
-.. doxygengroup:: TYPE_GROUP
-        :content-only:
-
--------------------
-Version information
--------------------
-
-.. doxygengroup:: API_VERSION_GROUP
-        :content-only:
-
-.. doxygengroup:: FILE_VERSION_GROUP
-        :content-only:
-
-***********************
-Miscellaneous functions
-***********************
-
-.. doxygenstruct:: kas_version_t
-    :members:
-
-.. doxygenfunction:: kas_version
-
-.. doxygenfunction:: kas_dynamic_api_init
+=====
+C API
+=====
 

docs/conf.py

@@ -24,7 +24,7 @@
 
 # -- Project information -----------------------------------------------------
 
-project = 'kastore'
+project = 'tskit'
 copyright = '2018, Tskit developers'
 author = 'Tskit developers'
 
@@ -33,6 +33,57 @@
 # The full version, including alpha/beta/rc tags
 release = ''
 
+###################################################################
+#
+# Monkey-patching sphinx to workaround really annoying bug in ivar
+# handling. See
+# https://stackoverflow.com/questions/31784830/sphinx-ivar-tag-goes-looking-for-cross-references
+#
+
+from docutils import nodes
+from sphinx.util.docfields import TypedField
+from sphinx import addnodes
+
+def patched_make_field(self, types, domain, items, env):
+    # type: (List, unicode, Tuple) -> nodes.field
+    def handle_item(fieldarg, content):
+        par = nodes.paragraph()
+        par += addnodes.literal_strong('', fieldarg)  # Patch: this line added
+        #par.extend(self.make_xrefs(self.rolename, domain, fieldarg,
+        #                           addnodes.literal_strong))
+        if fieldarg in types:
+            par += nodes.Text(' (')
+            # NOTE: using .pop() here to prevent a single type node to be
+            # inserted twice into the doctree, which leads to
+            # inconsistencies later when references are resolved
+            fieldtype = types.pop(fieldarg)
+            if len(fieldtype) == 1 and isinstance(fieldtype[0], nodes.Text):
+                typename = u''.join(n.astext() for n in fieldtype)
+                par.extend(self.make_xrefs(self.typerolename, domain, typename,
+                                           addnodes.literal_emphasis))
+            else:
+                par += fieldtype
+            par += nodes.Text(')')
+        par += nodes.Text(' -- ')
+        par += content
+        return par
+
+    fieldname = nodes.field_name('', self.label)
+    if len(items) == 1 and self.can_collapse:
+        fieldarg, content = items[0]
+        bodynode = handle_item(fieldarg, content)
+    else:
+        bodynode = self.list_type()
+        for fieldarg, content in items:
+            bodynode += nodes.list_item('', handle_item(fieldarg, content))
+    fieldbody = nodes.field_body('', bodynode)
+    return nodes.field('', fieldname, fieldbody)
+
+TypedField.make_field = patched_make_field
+
+###################################################################
+
+
 
 # -- General configuration ---------------------------------------------------
 
@@ -110,7 +161,7 @@
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'kastoredoc'
+htmlhelp_basename = 'tskitdoc'
 
 
 # -- Options for LaTeX output ------------------------------------------------
@@ -137,7 +188,7 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'kastore.tex', 'kastore Documentation',
+    (master_doc, 'tskit.tex', 'tskit Documentation',
      'Tskit developers', 'manual'),
 ]
 
@@ -147,7 +198,7 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'kastore', 'kastore Documentation',
+    (master_doc, 'tskit', 'tskit Documentation',
      [author], 1)
 ]
 
@@ -158,8 +209,8 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'kastore', 'kastore Documentation',
-     author, 'kastore', 'One line description of project.',
+    (master_doc, 'tskit', 'tskit Documentation',
+     author, 'tskit', 'One line description of project.',
      'Miscellaneous'),
 ]
 
@@ -195,8 +246,8 @@
 todo_include_todos = True
 
 # Breath extension lets us include doxygen C documentation.
-breathe_projects = {"kastore": "doxygen/xml" }
-breathe_default_project = "kastore"
+breathe_projects = {"tskit": "doxygen/xml" }
+breathe_default_project = "tskit"
 breathe_domain_by_extension = {"h": "c"}
 breathe_show_define_initializer = True
 

docs/index.rst

@@ -14,9 +14,11 @@ Welcome to kastore's documentation!
    installation
    python-api
    c-api
-   format
    development
    changelogs
+   interchange
+   provenance
+   tutorial
 
 
 Indices and tables