Merge pull request #408 from jeromekelleher/fix-sphinx-nitpicks

Fix sphinx nitpicks.

Author: jeromekelleher

docs/conf.py

@@ -263,7 +263,10 @@ def handle_item(fieldarg, content):
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {
+    'https://docs.python.org/': None,
+    'http://docs.scipy.org/doc/numpy/': None,
+}
 
 # -- Options for todo extension ----------------------------------------------
 
@@ -287,7 +290,6 @@ def handle_item(fieldarg, content):
     ("c:type", "bool"),
     # TODO these have been triaged here to make the docs compile, but we should
     # sort them out properly. https://github.com/tskit-dev/tskit/issues/336
-    ("py:class", "a"),
     ("py:class", "ndarray"),
     ("py:class", "numpy array"),
     ("py:class", "numpy.ndarray"),
@@ -303,29 +305,7 @@ def handle_item(fieldarg, content):
     ("py:class", "dtype=np.int8"),
     ("py:class", "dtype=np.float64"),
     ("py:class", "dtype=np.int64"),
-    ("py:class", "iter"),
-    ("py:class", "iterator"),
-    ("py:class", "map"),
     ("py:class", "array"),
     ("py:class", "array_like"),
-    ("py:class", "File"),
-    ("py:class", "callable"),
-    ("py:class", "stream"),
-    ("py:class", "string"),
     ("py:class", ""),
-    ("py:class", "Provenance"),
-    ("py:class", "ProvenanceValidationError"),
-    ("py:class", "function"),
-    ("py:class", "Table"),
-    ("py:const", "tskit.FORWARD"),
-    ("py:const", "tskit.REVERSE"),
-    ("py:const", "NULL"),
-    ("py:attr", "NULL"),
-    ("py:func", "numpy.round"),
-    ("py:func", "numpy.nonzero"),
-    ("py:func", "pack_bytes"),
-    ("py:func", "unpack_bytes"),
-    ("py:func", "parse_individuals"),
-    ("py:func", "parse_populations"),
-    ("py:meth", "Tree.get_num_tracked_samples"),
 ]

docs/data-model.rst

@@ -1132,6 +1132,7 @@ mutations::
     1      1       A                1
 
 
+.. _sec_population_text_format:
 
 Population text format
 ======================

docs/python-api.rst

@@ -36,19 +36,20 @@ Top level-classes
 Constants
 +++++++++
 
-.. data:: tskit.NULL == -1
+.. autodata:: tskit.NULL
+    :annotation: = -1
 
-    Special reserved value representing a null ID.
+.. autodata:: tskit.NODE_IS_SAMPLE
+    :annotation: = 1
 
-.. data:: tskit.FORWARD == 1
+.. autodata:: tskit.MISSING_DATA
+    :annotation: = -1
 
-    Constant representing the forward direction of travel (i.e.,
-    increasing genomic coordinate values).
+.. autodata:: tskit.FORWARD
+    :annotation: = 1
 
-.. data:: tskit.REVERSE == -1
-
-    Constant representing the reverse direction of travel (i.e.,
-    decreasing genomic coordinate values).
+.. autodata:: tskit.REVERSE
+    :annotation: = -1
 
 
 ++++++++++++++++++++++++
@@ -84,6 +85,9 @@ directly, but are the return types for the various iterators provided by the
 .. autoclass:: tskit.Population()
     :members:
 
+.. autoclass:: tskit.Provenance()
+    :members:
+
 ++++++++++++
 Loading data
 ++++++++++++
@@ -352,7 +356,7 @@ encoded as signed integers. As for :ref:`sec_tables_api_text_columns`,
 the ``metadata_offset`` column encodes the offsets into this array. So, we
 see that the first metadata value is 9 bytes long and the second is 24.
 
-The :func:`pack_bytes` and :func:`unpack_bytes` functions are also useful
+The :func:`.pack_bytes` and :func:`.unpack_bytes` functions are also useful
 for encoding data in these columns.
 
 +++++++++++++
@@ -430,6 +434,10 @@ Table functions
 
 .. autofunction:: tskit.parse_mutations
 
+.. autofunction:: tskit.parse_individuals
+
+.. autofunction:: tskit.parse_populations
+
 .. autofunction:: tskit.pack_strings
 
 .. autofunction:: tskit.unpack_strings

docs/tutorial.rst

@@ -19,7 +19,7 @@ The ``tskit`` Tree implementation differs from most tree libraries by
 using **integer IDs** to refer to nodes rather than objects. Thus, when we wish to
 find the parent of the node with ID '0', we use ``tree.parent(0)``, which
 returns another integer. If '0' does not have a parent in the current tree
-(e.g., if it is a root), then the special value :const:`.NULL`
+(e.g., if it is a root), then the special value :data:`.NULL`
 (:math:`-1`) is returned. The children of a node are found using the
 :meth:`.Tree.children` method. To obtain information about a particular node,
 one may either use ``tree.tree_sequence.node(u)`` to which returns the

python/tskit/__init__.py

@@ -21,10 +21,22 @@
 # SOFTWARE.
 
 import _tskit
+
+#: Special reserved value representing a null ID.
 NULL = _tskit.NULL
+
+#: Special value representing missing data in a genotype array
 MISSING_DATA = _tskit.MISSING_DATA
+
+#: Node flag value indicating that it is a sample.
 NODE_IS_SAMPLE = _tskit.NODE_IS_SAMPLE
+
+#: Constant representing the forward direction of travel (i.e.,
+#: increasing genomic coordinate values).
 FORWARD = _tskit.FORWARD
+
+#: Constant representing the reverse direction of travel (i.e.,
+#: decreasing genomic coordinate values).
 REVERSE = _tskit.REVERSE
 
 from tskit.provenance import __version__  # NOQA

python/tskit/provenance.py

@@ -125,7 +125,7 @@ def validate_provenance(provenance):
 
     :param dict provenance: The dictionary representing a JSON document
         to be validated against the schema.
-    :raises: :class:`.ProvenanceValidationError`
+    :raises: :class:`tskit.ProvenanceValidationError`
     """
     schema = get_schema()
     try:

python/tskit/stats.py

@@ -95,18 +95,18 @@ def r2_array(self, a, direction=1, max_mutations=None, max_distance=None):
         :math:`b` considered, we then insert the value of :math:`r^2` between
         :math:`a` and :math:`b` at the corresponding index in an array, and
         return the entire array. If the returned array is :math:`x` and
-        ``direction`` is :const:`tskit.FORWARD` then :math:`x[0]` is the
+        ``direction`` is :data:`tskit.FORWARD` then :math:`x[0]` is the
         value of the statistic for :math:`a` and :math:`a + 1`, :math:`x[1]`
         the value for :math:`a` and :math:`a + 2`, etc. Similarly, if
-        ``direction`` is :const:`tskit.REVERSE` then :math:`x[0]` is the
+        ``direction`` is :data:`tskit.REVERSE` then :math:`x[0]` is the
         value of the statistic for :math:`a` and :math:`a - 1`, :math:`x[1]`
         the value for :math:`a` and :math:`a - 2`, etc.
 
         :param int a: The index of the focal mutation.
         :param int direction: The direction in which to travel when
             examining other mutations. Must be either
-            :const:`tskit.FORWARD` or :const:`tskit.REVERSE`. Defaults
-            to :const:`tskit.FORWARD`.
+            :data:`tskit.FORWARD` or :data:`tskit.REVERSE`. Defaults
+            to :data:`tskit.FORWARD`.
         :param int max_mutations: The maximum number of mutations to return
             :math:`r^2` values for. Defaults to as many mutations as
             possible.

python/tskit/tables.py

@@ -435,9 +435,9 @@ def add_row(self, flags=0, time=0, population=-1, individual=-1, metadata=None):
         :param int flags: The bitwise flags for the new node.
         :param float time: The birth time for the new node.
         :param int population: The ID of the population in which the new node was born.
-            Defaults to :const:`.NULL`.
+            Defaults to :data:`.NULL`.
         :param int individual: The ID of the individual in which the new node was born.
-            Defaults to :const:`.NULL`.
+            Defaults to :data:`.NULL`.
         :param bytes metadata: The binary-encoded metadata for the new node. If not
             specified or None, a zero-length byte string is stored.
         :return: The ID of the newly added node.
@@ -463,10 +463,10 @@ def set_columns(
         :param time: The time values for each node. Required.
         :type time: numpy.ndarray, dtype=np.float64
         :param population: The population values for each node. If not specified
-            or None, the :const:`.NULL` value is stored for each node.
+            or None, the :data:`.NULL` value is stored for each node.
         :type population: numpy.ndarray, dtype=np.int32
         :param individual: The individual values for each node. If not specified
-            or None, the :const:`.NULL` value is stored for each node.
+            or None, the :data:`.NULL` value is stored for each node.
         :type individual: numpy.ndarray, dtype=np.int32
         :param metadata: The flattened metadata array. Must be specified along
             with ``metadata_offset``. If not specified or None, an empty metadata
@@ -498,10 +498,10 @@ def append_columns(
         :param time: The time values for each node. Required.
         :type time: numpy.ndarray, dtype=np.float64
         :param population: The population values for each node. If not specified
-            or None, the :const:`.NULL` value is stored for each node.
+            or None, the :data:`.NULL` value is stored for each node.
         :type population: numpy.ndarray, dtype=np.int32
         :param individual: The individual values for each node. If not specified
-            or None, the :const:`.NULL` value is stored for each node.
+            or None, the :data:`.NULL` value is stored for each node.
         :type individual: numpy.ndarray, dtype=np.int32
         :param metadata: The flattened metadata array. Must be specified along
             with ``metadata_offset``. If not specified or None, an empty metadata
@@ -1140,10 +1140,43 @@ def __str__(self):
         return ret[:-1]
 
     def set_columns(self, metadata=None, metadata_offset=None):
+        """
+        Sets the values for each column in this :class:`.PopulationTable` using the
+        values in the specified arrays. Overwrites any data currently stored in the
+        table.
+
+        The ``metadata`` and ``metadata_offset`` parameters must be supplied
+        together, and meet the requirements for
+        :ref:`sec_encoding_ragged_columns` (see
+        :ref:`sec_tables_api_binary_columns` for more information).
+
+        :param metadata: The flattened metadata array. Must be specified along
+            with ``metadata_offset``. If not specified or None, an empty metadata
+            value is stored for each node.
+        :type metadata: numpy.ndarray, dtype=np.int8
+        :param metadata_offset: The offsets into the ``metadata`` array.
+        :type metadata_offset: numpy.ndarray, dtype=np.uint32.
+        """
         self.ll_table.set_columns(
             dict(metadata=metadata, metadata_offset=metadata_offset))
 
     def append_columns(self, metadata=None, metadata_offset=None):
+        """
+        Appends the specified arrays to the end of the columns of this
+        :class:`PopulationTable`. This allows many new rows to be added at once.
+
+        The ``metadata`` and ``metadata_offset`` parameters must be supplied
+        together, and meet the requirements for
+        :ref:`sec_encoding_ragged_columns` (see
+        :ref:`sec_tables_api_binary_columns` for more information).
+
+        :param metadata: The flattened metadata array. Must be specified along
+            with ``metadata_offset``. If not specified or None, an empty metadata
+            value is stored for each node.
+        :type metadata: numpy.ndarray, dtype=np.int8
+        :param metadata_offset: The offsets into the ``metadata`` array.
+        :type metadata_offset: numpy.ndarray, dtype=np.uint32.
+        """
         self.ll_table.append_columns(
             dict(metadata=metadata, metadata_offset=metadata_offset))
 
@@ -1201,13 +1234,60 @@ def add_row(self, record, timestamp=None):
     def set_columns(
             self, timestamp=None, timestamp_offset=None,
             record=None, record_offset=None):
+        """
+        Sets the values for each column in this :class:`.ProvenanceTable` using the
+        values in the specified arrays. Overwrites any data currently stored in the
+        table.
+
+        The ``timestamp`` and ``timestamp_offset`` parameters must be supplied
+        together, and meet the requirements for
+        :ref:`sec_encoding_ragged_columns` (see
+        :ref:`sec_tables_api_binary_columns` for more information). Likewise
+        for the ``record`` and ``record_offset`` columns
+
+        :param timestamp: The flattened timestamp array. Must be specified along
+            with ``timestamp_offset``. If not specified or None, an empty timestamp
+            value is stored for each node.
+        :type timestamp: numpy.ndarray, dtype=np.int8
+        :param timestamp_offset: The offsets into the ``timestamp`` array.
+        :type timestamp_offset: numpy.ndarray, dtype=np.uint32.
+        :param record: The flattened record array. Must be specified along
+            with ``record_offset``. If not specified or None, an empty record
+            value is stored for each node.
+        :type record: numpy.ndarray, dtype=np.int8
+        :param record_offset: The offsets into the ``record`` array.
+        :type record_offset: numpy.ndarray, dtype=np.uint32.
+        """
         self.ll_table.set_columns(dict(
             timestamp=timestamp, timestamp_offset=timestamp_offset,
             record=record, record_offset=record_offset))
 
     def append_columns(
             self, timestamp=None, timestamp_offset=None,
             record=None, record_offset=None):
+        """
+        Appends the specified arrays to the end of the columns of this
+        :class:`ProvenanceTable`. This allows many new rows to be added at once.
+
+        The ``timestamp`` and ``timestamp_offset`` parameters must be supplied
+        together, and meet the requirements for
+        :ref:`sec_encoding_ragged_columns` (see
+        :ref:`sec_tables_api_binary_columns` for more information). Likewise
+        for the ``record`` and ``record_offset`` columns
+
+        :param timestamp: The flattened timestamp array. Must be specified along
+            with ``timestamp_offset``. If not specified or None, an empty timestamp
+            value is stored for each node.
+        :type timestamp: numpy.ndarray, dtype=np.int8
+        :param timestamp_offset: The offsets into the ``timestamp`` array.
+        :type timestamp_offset: numpy.ndarray, dtype=np.uint32.
+        :param record: The flattened record array. Must be specified along
+            with ``record_offset``. If not specified or None, an empty record
+            value is stored for each node.
+        :type record: numpy.ndarray, dtype=np.int8
+        :param record_offset: The offsets into the ``record`` array.
+        :type record_offset: numpy.ndarray, dtype=np.uint32.
+        """
         self.ll_table.append_columns(dict(
             timestamp=timestamp, timestamp_offset=timestamp_offset,
             record=record, record_offset=record_offset))