Merge pull request #337 from jeromekelleher/0.2.0-docs

0.2.0 docs

Author: jeromekelleher

c/tskit/tables.h

@@ -1992,7 +1992,7 @@ assumptions, if the tables are not already indexed, we index the tables
 before writing to file to save the cost of building these indexes at 
 load time. This behaviour requires that the tables are sorted. 
 If this automatic indexing is not desired, it can be disabled using 
-the :c:macro:`TSK_NO_BUILD_INDEXES` option.
+the `TSK_NO_BUILD_INDEXES` option.
 
 **Options**
 
@@ -2198,7 +2198,7 @@ int tsk_table_collection_drop_index(tsk_table_collection_t *self, tsk_flags_t op
 
 @rst
 Builds the tree traversal :ref:`indexes <sec_table_indexing>` for this table collection.
-Any existing index is first dropped using :c:func:`tsk_table_collection_drop_indexes`.
+Any existing index is first dropped using :c:func:`tsk_table_collection_drop_index`.
 @endrst
 
 @param self A pointer to a tsk_table_collection_t object.

docs/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    = -W
+SPHINXOPTS    = #-W
 SPHINXBUILD   = python3 -m sphinx
 SOURCEDIR     = .
 BUILDDIR      = _build

docs/conf.py

@@ -279,3 +279,53 @@ def handle_item(fieldarg, content):
 # TODO add an RST epilogue defining the version numbers of the Python
 # and C APIs. Should be simple to do the Python version. Getting C
 # will probably mean parsing the doxygen XML.
+
+nitpicky = True
+nitpick_ignore = [
+    ("c:type", "int32_t"),
+    ("c:type", "uint32_t"),
+    ("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"),
+    ("py:class", "numpy.array"),
+    ("py:class", "array-like"),
+    ("py:class", "np.uint32"),
+    ("py:class", "np.float64"),
+    ("py:class", "np.int32"),
+    ("py:class", "np.int8"),
+    ("py:class", "dtype=np.uint32"),
+    ("py:class", "dtype=np.uint32."),
+    ("py:class", "dtype=np.int32"),
+    ("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

@@ -48,7 +48,6 @@ node
     See :ref:`sec_nodes_or_individuals` for discussion of what a "node" is.
 
 individual
-
     In certain situations we are interested in how nodes (representing
     individual homologous genomes) are grouped together into individuals
     (e.g., two nodes per diploid individual). For example, when we are working
@@ -709,7 +708,7 @@ Schema section (TODO).
 Table transformation methods
 ============================
 
-The following methods operate *in place* on a :class:`TableCollection`,
+The following methods operate *in place* on a :class:`.TableCollection`,
 transforming them while preserving information.
 In some applications, tables may most naturally be produced in a way that is
 logically consistent, but not meeting all the requirements for validity that
@@ -877,7 +876,7 @@ Consider the following example:
 
 In this tree, node 4 is isolated, and therefore for any sites that are
 on this tree, the state that it is assigned is a special value
-``tskit.MISSING_DATA``, or ``-1``. See the :meth:`TreeSequence.variants`
+``tskit.MISSING_DATA``, or ``-1``. See the :meth:`.TreeSequence.variants`
 method and :class:`.Variant` class for more information on how missing
 data is represented.
 

docs/installation.rst

@@ -1,20 +1,69 @@
 .. _sec_installation:
 
-============
+############
 Installation
-============
+############
 
-.. note:: This documentation is incomplete. Once we have a conda package that
-    is installable we'll update the documentation to use that route also. However,
-    as there are no external dependencies, pip should work well for all
-    non-Windows users.
+There are two basic options for installing ``tskit``: either through
+pre-built binary packages using :ref:`sec_installation_conda` or
+by compiling locally using :ref:`sec_installation_pip`. We recommend using ``conda``
+for most users, although ``pip`` can be more convenient in certain cases.
+Tskit is installed to provide succinct tree sequence functionality
+to other software (such as `msprime <https://github.com/tskit-dev/msprime>`_),
+so it may already be installed if you use such software.
 
-The tree sequence toolkit is often installed to provide succinct tree sequence functionality
-to other software (such as `msprime <https://github.com/tskit-dev/msprime>`_). If installing
-as a standalone Python module, users are encouraged to install an official release from PyPI
-using pip::
+.. _sec_installation_requirements:
 
-    $ python -m pip install tskit
+************
+Requirements
+************
+
+Tskit requires Python 3.4+. There are no external C library dependencies. Python
+dependencies are installed automatically by ``pip`` or ``conda``.
+
+.. _sec_installation_conda:
+
+*****
+conda
+*****
+
+Pre-built binary packages for ``tskit`` are available through
+`conda <https://conda.io/docs/>`_, and built using `conda-forge <https://conda-forge.org/>`_.
+Packages for recent version of Python are available for Linux, OSX and Windows. Install
+using::
+
+    $ conda install -c conda-forge tskit
+
+
++++++++++++
+Quick Start
++++++++++++
+
+1. Install ``conda`` using `miniconda <https://conda.io/miniconda.html>`_.
+   Make sure you follow the instructions to fully activate your ``conda``
+   installation!
+2. Set up the `conda-forge channel <https://conda-forge.org/>`_ using
+   ``conda config --add channels conda-forge``.
+3. Install tskit: ``conda install tskit``.
+4. Try it out: ``tskit --version``.
+
+
+There are several different ways to obtain ``conda``. Please see the
+`anaconda installation documentation <https://docs.anaconda.com/anaconda/install/>`_
+for full details.
+
+.. _sec_installation_pip:
+
+***
+pip
+***
+
+Installing using ``pip`` is somewhat more flexible than ``conda`` and
+may result in code that is (slightly) faster on your specific hardware.
+``Pip`` is the recommended method when using the system provided Python
+installations. Installation is straightforward::
+
+    $ python3 -m pip install tskit
 
 For technical reasons it is not possible to install a development version directly using the
 GitHub URL (i.e. ``pip install git+git://...`` will not work)

docs/python-api.rst

@@ -440,12 +440,12 @@ Table functions
 
 .. _sec_stats_api:
 
-**********
-Statistics
-**********
+**********************
+Linkage disequilibrium
+**********************
 
-The ``tskit`` API provides methods for efficiently calculating
-population genetics statistics from a given :class:`.TreeSequence`.
+.. note:: This API will soon be deprecated in favour of multi-site extensions
+    to the :ref:`sec_stats` API.
 
 .. autoclass:: tskit.LdCalculator(tree_sequence)
     :members: