Merge pull request #412 from hyanwong/sphinx-attr-warnings

Use Sphinx currentmodule to rationalise & allow :attr: refs

Author: jeromekelleher

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/data-model.rst

@@ -1,3 +1,4 @@
+.. currentmodule:: tskit
 .. _sec_data_model:
 
 ##########
@@ -21,6 +22,8 @@ store tree sequences on disk in the `Tree sequence file format`_ section.
 
 .. _sec_data_model_definitions:
 
+
+
 ***********
 Definitions
 ***********
@@ -50,17 +53,17 @@ node
 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
+    (e.g. two nodes per diploid individual). For example, when we are working
     with polyploid samples it is useful to associate metadata with a specific
     individual rather than duplicate this information on the constituent nodes.
     See :ref:`sec_nodes_or_individuals` for more discussion on this point.
 
 sample
     The focal nodes of a tree sequence, usually thought of as those that we
     have obtained data from. The specification of these affects various
-    methods: (1) :meth:`.TreeSequence.variants` and
-    :meth:`.TreeSequence.haplotypes` will output the genotypes of the samples,
-    and :attr:`.Tree.roots` only return roots ancestral to at least one
+    methods: (1) :meth:`TreeSequence.variants` and 
+    :meth:`TreeSequence.haplotypes` will output the genotypes of the samples,
+    and :attr:`Tree.roots` only return roots ancestral to at least one
     sample. (See the :ref:`node table definitions <sec_node_table_definition>`
     for information on how the sample
     status a node is encoded in the ``flags`` column.)
@@ -214,7 +217,7 @@ is composed of 32 bitwise boolean values. Currently, the only flag defined
 is ``IS_SAMPLE = 1``, which defines the *sample* status of nodes. Marking
 a particular node as a "sample" means, for example, that the mutational state
 of the node will be included in the genotypes produced by
-:meth:`.TreeSequence.variants`.
+:meth:`TreeSequence.variants`.
 
 Bits 0-15 (inclusive) of the ``flags`` column are reserved for internal use by
 ``tskit`` and should not be used by applications for anything other
@@ -511,14 +514,14 @@ Valid tree sequence requirements
 ================================
 
 Arbitrary data can be stored in tables using the classes in the
-:ref:`sec_tables_api`. However, only a :class:`.TableCollection`
+:ref:`sec_tables_api`. However, only a :class:`TableCollection`
 that fulfils a set of requirements represents
-a valid :class:`.TreeSequence` object which can be obtained
-using the :meth:`.TableCollection.tree_sequence` method. In this
+a valid :class:`TreeSequence` object which can be obtained
+using the :meth:`TableCollection.tree_sequence` method. In this
 section we list these requirements, and explain their rationale.
 Violations of most of these requirements are detected when the
-user attempts to load a tree sequence via :func:`.load` or
-:meth:`.TableCollection.tree_sequence`, raising an informative
+user attempts to load a tree sequence via :func:`tskit.load` or
+:meth:`TableCollection.tree_sequence`, raising an informative
 error message. Some more complex requirements may not be detectable at load-time,
 and errors may not occur until certain operations are attempted.
 These are documented below.
@@ -536,7 +539,7 @@ respect to any other tables. Therefore, there are no requirements on
 individuals.
 
 There are no requirements regarding the ordering of individuals.
-Sorting a set of tables using :meth:`.TableCollection.sort` has
+Sorting a set of tables using :meth:`TableCollection.sort` has
 no effect on the individuals.
 
 .. _sec_node_requirements:
@@ -558,7 +561,7 @@ There are no requirements regarding the ordering of nodes with respect to time.
 For simplicity and algorithmic efficiency, all nodes referring to the same
 (non-null) individual must be contiguous.
 
-Sorting a set of tables using :meth:`.TableCollection.sort`
+Sorting a set of tables using :meth:`TableCollection.sort`
 has no effect on nodes.
 
 .. _sec_edge_requirements:
@@ -587,7 +590,7 @@ where a node ``a`` is a child of both ``b`` and ``c``), and ensures that
 at each point on the sequence we have a well-formed forest of trees.
 Because this is a more complex semantic requirement, it is **not** detected
 at load time. This error is detected during tree traversal, via, e.g.,
-the :meth:`.TreeSequence.trees` iterator.
+the :meth:`TreeSequence.trees` iterator.
 
 In the interest of algorithmic efficiency, edges must have the following
 sortedness properties:
@@ -598,7 +601,7 @@ sortedness properties:
   first by ``child`` ID and then by ``left`` coordinate.
 
 Violations of these requirements are detected at load time.
-The :meth:`.TableCollection.sort` method will ensure that these sortedness
+The :meth:`TableCollection.sort` method will ensure that these sortedness
 properties are fulfilled.
 
 .. _sec_site_requirements:
@@ -617,7 +620,7 @@ For simplicity and algorithmic efficiency, sites must also:
 - Be sorted in increasing order of ``position``.
 
 Violations of these requirements are detected at load time.
-The :meth:`.TableCollection.sort` method ensures that sites are sorted
+The :meth:`TableCollection.sort` method ensures that sites are sorted
 according to these criteria.
 
 .. _sec_mutation_requirements:
@@ -646,7 +649,7 @@ For simplicity and algorithmic efficiency, mutations must also:
   ``parent`` with ID :math:`y`, then we must have :math:`y < x`).
 
 Violations of these sorting requirements are detected at load time.
-The :meth:`.TableCollection.sort` method ensures that mutations are sorted
+The :meth:`TableCollection.sort` method ensures that mutations are sorted
 according site ID, but does not at present enforce that mutations occur
 after their parent mutations.
 
@@ -655,7 +658,7 @@ change of state. For example, if we have a site with ancestral state
 of "A" and a single mutation with derived state "A", then this
 mutation does not result in any change of state. This error is
 raised at run-time when we reconstruct sample genotypes, for example
-in the :meth:`.TreeSequence.variants` iterator.
+in the :meth:`TreeSequence.variants` iterator.
 
 .. _sec_migration_requirements:
 
@@ -708,7 +711,7 @@ Schema section (TODO).
 Table transformation methods
 ============================
 
-In general, table methods operate *in place* on a :class:`.TableCollection`,
+In general, table methods operate *in place* on a :class:`TableCollection`,
 directly altering the data stored within its constituent tables.
 
 In some applications, tables may most naturally be produced in a way that is
@@ -718,8 +721,8 @@ below (while also having other uses), can be used to make such a set of tables
 valid, and thus ready to be loaded into a tree sequence.
 
 Some of the other methods described in this section also have an equivalant
-:class:`.TreeSequence` version: an important distinction is that unlike the
-methods here, :class:`.TreeSequence` methods do *not* operate in place, but
+:class:`TreeSequence` version: an important distinction is that unlike the
+methods here, :class:`TreeSequence` methods do *not* operate in place, but
 rather act in a functional way, returning a new tree sequence while leaving
 the original one unchanged.
 
@@ -732,8 +735,8 @@ Simplification
 --------------
 
 Simplification of a tree sequence is in fact a transformation method applied
-to the underlying tables: the method :meth:`.TreeSequence.simplify` calls
-:meth:`.TableCollection.simplify` on the tables, and loads a new tree sequence.
+to the underlying tables: the method :meth:`TreeSequence.simplify` calls
+:meth:`TableCollection.simplify` on the tables, and loads a new tree sequence.
 The main purpose of this method is to remove redundant information,
 only retaining the minimal tree sequence necessary to describe the genealogical
 history of the ``samples`` provided.
@@ -743,7 +746,7 @@ Furthermore, ``simplify`` is guaranteed to:
 - preserve relative ordering of any rows in the Site and Mutation tables
   that are not discarded.
 
-The :meth:`.TableCollection.simplify` method can be applied to a collection of
+The :meth:`TableCollection.simplify` method can be applied to a collection of
 tables that does not have the ``mutations.parent`` entries filled in, as long
 as all other validity requirements are satisfied.
 
@@ -754,7 +757,7 @@ Sorting
 
 The validity requirements for a set of tables to be loaded into a tree sequence
 listed in :ref:`sec_table_definitions` are of two sorts: logical consistency,
-and sortedness. The :meth:`.TableCollection.sort` method can be used to make
+and sortedness. The :meth:`TableCollection.sort` method can be used to make
 completely valid a set of tables that satisfies all requirements other than
 sortedness.
 
@@ -765,7 +768,7 @@ be sorted. The method has two additional properties:
 - it preserves relative ordering between sites at the same position, and
 - it preserves relative ordering between mutations at the same site.
 
-:meth:`.TableCollection.sort` does not check the validity of the `parent`
+:meth:`TableCollection.sort` does not check the validity of the `parent`
 property of the mutation table. However, because the method preserves mutation
 order among mutations at the same site, if mutations are already sorted so that
 each mutation comes after its parent (e.g., if they are ordered by time of
@@ -786,7 +789,7 @@ the tables must be indexed.
 Removing duplicate sites
 ------------------------
 
-The :meth:`.TableCollection.deduplicate_sites` method can be used to save a tree
+The :meth:`TableCollection.deduplicate_sites` method can be used to save a tree
 sequence recording method the bother of checking to see if a given site already
 exists in the site table. If there is more than one site with the same
 position, all but the first is removed, and all mutations referring to the
@@ -802,7 +805,7 @@ of the mutation table would be easily inferred from the tree at that mutation's
 site. If mutations are entered into the mutation table ordered by time of
 appearance, then this sortedness allows us to infer the parent of each mutation
 even for mutations occurring on the same branch. The
-:meth:`.TableCollection.compute_mutation_parents` method will take advantage
+:meth:`TableCollection.compute_mutation_parents` method will take advantage
 of this fact to compute the ``parent`` column of a mutation table, if all
 other information is valid.
 
@@ -982,8 +985,8 @@ 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`
-method and :class:`.Variant` class for more information on how missing
+``tskit.MISSING_DATA``, or ``-1``. See the :meth:`TreeSequence.variants`
+method and :class:`Variant` class for more information on how missing
 data is represented.
 
 .. _sec_text_file_format:

docs/python-api.rst

@@ -1,3 +1,4 @@
+.. currentmodule:: tskit
 .. _sec_python_api:
 
 ==========
@@ -10,14 +11,14 @@ This page provides detailed documentation for the ``tskit`` Python API.
 Trees and tree sequences
 ************************
 
-The :class:`.TreeSequence` class represents a sequence of correlated trees
-output by a simulation. The :class:`.Tree` class represents a single
+The :class:`TreeSequence` class represents a sequence of correlated trees
+output by a simulation. The :class:`Tree` class represents a single
 tree in this sequence.
 These classes are the interfaces used to interact with the trees
 and mutational information stored in a tree sequence returned from a simulation.
 There are also methods for loading data into these objects, either from the native
 format using :func:`tskit.load`, or from another sources
-using :func:`tskit.load_text` or :meth:`.TableCollection.tree_sequence`.
+using :func:`tskit.load_text` or :meth:`TableCollection.tree_sequence`.
 
 
 +++++++++++++++++
@@ -28,7 +29,7 @@ Top level-classes
 .. autoclass:: tskit.TreeSequence()
     :members:
 
-.. autoclass:: tskit.Tree
+.. autoclass:: tskit.Tree()
     :members:
 
 
@@ -59,7 +60,7 @@ Simple container classes
 These classes are simple shallow containers representing the entities defined
 in the :ref:`sec_data_model_definitions`. These classes are not intended to be instantiated
 directly, but are the return types for the various iterators provided by the
-:class:`.TreeSequence` and :class:`.Tree` classes.
+:class:`TreeSequence` and :class:`Tree` classes.
 
 .. autoclass:: tskit.Individual()
     :members:
@@ -92,13 +93,13 @@ directly, but are the return types for the various iterators provided by the
 Loading data
 ++++++++++++
 
-There are several methods for loading data into a :class:`.TreeSequence`
+There are several methods for loading data into a :class:`TreeSequence`
 instance. The simplest and most convenient is the use the :func:`tskit.load`
 function to load a :ref:`tree sequence file <sec_tree_sequence_file_format>`. For small
 scale data and debugging, it is often convenient to use the
 :func:`tskit.load_text` to read data in the :ref:`text file format
-<sec_text_file_format>`. The :meth:`.TableCollection.tree_sequence` function
-efficiently creates a :class:`.TreeSequence` object from a set of tables
+<sec_text_file_format>`. The :meth:`TableCollection.tree_sequence` function
+efficiently creates a :class:`TreeSequence` object from a set of tables
 using the :ref:`Tables API <sec_tables_api>`.
 
 
@@ -115,7 +116,7 @@ Tables
 
 The :ref:`tables API <sec_binary_interchange>` provides an efficient way of working
 with and interchanging :ref:`tree sequence data <sec_data_model>`. Each table
-class (e.g, :class:`.NodeTable`, :class:`.EdgeTable`) has a specific set of
+class (e.g, :class:`NodeTable`, :class:`EdgeTable`) has a specific set of
 columns with fixed types, and a set of methods for setting and getting the data
 in these columns. The number of rows in the table ``t`` is given by ``len(t)``.
 Each table supports accessing the data either by row or column. To access the
@@ -214,7 +215,7 @@ Consider the following example::
     >>> t[3]
     SiteTableRow(position=3.0, ancestral_state='CCC', metadata=b'')
 
-Here we create a :class:`.SiteTable` and add four rows, each with a different
+Here we create a :class:`SiteTable` and add four rows, each with a different
 ``ancestral_state``. We can then access this information from each
 row in a straightforward manner. Working with the data in the columns
 is a little trickier, however::
@@ -228,9 +229,9 @@ is a little trickier, however::
 
 Here, the ``ancestral_state`` array is the UTF8 encoded bytes of the flattened
 strings, and the ``ancestral_state_offset`` is the offset into this array
-for each row. The :func:`.unpack_strings` function, however, is a convient
+for each row. The :func:`tskit.unpack_strings` function, however, is a convient
 way to recover the original strings from this encoding. We can also use the
-:func:`.pack_strings` to insert data using this approach::
+:func:`tskit.pack_strings` to insert data using this approach::
 
     >>> a, off = tskit.pack_strings(["0", "12", ""])
     >>> t.set_columns(position=[0, 1, 2], ancestral_state=a, ancestral_state_offset=off)
@@ -243,7 +244,7 @@ way to recover the original strings from this encoding. We can also use the
 When inserting many rows with standard infinite sites mutations (i.e.,
 ancestral state is "0"), it is more efficient to construct the
 numpy arrays directly than to create a list of strings and use
-:func:`.pack_strings`. When doing this, it is important to note that
+:func:`pack_strings`. When doing this, it is important to note that
 it is the **encoded** byte values that are stored; by default, we
 use UTF8 (which corresponds to ASCII for simple printable characters).::
 
@@ -332,7 +333,7 @@ decoding is done on the data. Consider the following example::
     array([ 0,  9, 33], dtype=uint32)
 
 
-Here we add two rows to a :class:`.NodeTable`, with different
+Here we add two rows to a :class:`NodeTable`, with different
 :ref:`metadata <sec_metadata_definition>`. The first row contains a simple
 byte string, and the second contains a Python dictionary serialised using
 :mod:`pickle`. We then show several different (and seemingly incompatible!)
@@ -356,8 +357,8 @@ 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
-for encoding data in these columns.
+The :func:`tskit.pack_bytes` and :func:`tskit.unpack_bytes` functions are
+also useful for encoding data in these columns.
 
 +++++++++++++
 Table classes
@@ -410,7 +411,7 @@ Each of the table classes defines a different aspect of the structure of
 a tree sequence. It is convenient to be able to refer to a set of these
 tables which together define a tree sequence. We
 refer to this grouping of related tables as a ``TableCollection``.
-The :class:`.TableCollection` and :class:`.TreeSequence` classes are
+The :class:`TableCollection` and :class:`TreeSequence` classes are
 deeply related. A ``TreeSequence`` instance is based on the information
 encoded in a ``TableCollection``. Tree sequences are **immutable**, and
 provide methods for obtaining trees from the sequence. A ``TableCollection``