Auto show return types in docs

Requires us to document a few classes that should be public anyway, as they are returned from public functions.

Author: hyanwong

docs/_config.yml

@@ -31,6 +31,7 @@ sphinx:
     extra_extensions:
     - breathe
     - sphinx.ext.autodoc
+    - sphinx_autodoc_typehints
     - sphinx.ext.autosummary
     - sphinx.ext.todo
     - sphinx.ext.viewcode

docs/python-api.md

@@ -1477,7 +1477,6 @@ section for more details and examples.
 
 #### The {class}`ReferenceSequence` class
 
-
 ```{eval-rst}
 .. todo:: Add a top-level summary section that we can link to from here.
 ```
@@ -1498,6 +1497,13 @@ Also see the {ref}`sec_python_api_metadata` summary.
     :inherited-members:
 ```
 
+#### The {class}`TableMetadataSchemas` class
+
+```{eval-rst}
+.. autoclass:: TableMetadataSchemas
+    :members:
+```
+
 #### The {class}`TopologyCounter` class
 
 ```{eval-rst}
@@ -1511,7 +1517,15 @@ Also see the {ref}`sec_python_api_metadata` summary.
     :members:
 ```
 
+#### The {class}`TableCollectionIndexes` class
+
+```{eval-rst}
+.. autoclass:: TableCollectionIndexes
+    :members:
+```
+
 #### The {class}`SVGString` class
+
 ```{eval-rst}
 .. autoclass:: SVGString
     :members:

python/requirements/CI-docs/requirements.txt

@@ -8,6 +8,7 @@ numpy==1.22.3
 PyGithub==1.55
 sphinx==4.5.0
 sphinx-argparse==0.3.1
+sphinx-autodoc-typehints==1.18.3
 sphinx-issues==3.0.1
 sphinxcontrib-prettyspecialmethods==0.1.0
 svgwrite==1.4.2

python/requirements/development.txt

@@ -27,6 +27,7 @@ pytest-cov
 pytest-xdist
 sphinx==4.5
 sphinx-argparse
+sphinx-autodoc-typehints
 sphinx-issues
 sphinx-jupyterbook-latex
 sphinxcontrib-prettyspecialmethods

python/tskit/genotypes.py

@@ -207,6 +207,7 @@ def decode(self, site_id) -> None:
         """
         Decode the variant at the given site, setting the site ID, genotypes and
         alleles to those of the site and samples of this Variant.
+
         :param int site_id: The ID of the site to decode. This must be a valid site ID.
         """
         self._ll_variant.decode(site_id)
@@ -215,6 +216,7 @@ def copy(self) -> Variant:
         """
         Create a copy of this Variant. Note that calling :meth:`decode` on the
         copy will fail as it does not take a copy of the internal tree.
+
         :return: The copy of this Variant.
         """
         variant_copy = Variant.__new__(Variant)

python/tskit/tables.py

@@ -301,14 +301,21 @@ class ProvenanceTableRow(util.Dataclass):
 
 @dataclass(**dataclass_options)
 class TableCollectionIndexes(util.Dataclass):
+    """
+    A class encapsulating the indexes of a :class:`TableCollection`
+    """
+
     edge_insertion_order: np.ndarray = None
     edge_removal_order: np.ndarray = None
 
     def asdict(self):
         return {k: v for k, v in dataclasses.asdict(self).items() if v is not None}
 
     @property
-    def nbytes(self):
+    def nbytes(self) -> int:
+        """
+        The number of bytes taken by the indexes
+        """
         total = 0
         if self.edge_removal_order is not None:
             total += self.edge_removal_order.nbytes

python/tskit/trees.py

@@ -3800,6 +3800,48 @@ def __getitem__(self, index):
         return self.getter(index)
 
 
+@dataclass(frozen=True)
+class TableMetadataSchemas:
+    """
+    Convenience class for returning the schemas of all the tables in a tree sequence.
+    """
+
+    node: metadata_module.MetadataSchema = None
+    """
+    The metadata schema of the node table.
+    """
+
+    edge: metadata_module.MetadataSchema = None
+    """
+    The metadata schema of the edge table.
+    """
+
+    site: metadata_module.MetadataSchema = None
+    """
+    The metadata schema of the site table.
+    """
+
+    mutation: metadata_module.MetadataSchema = None
+    """
+    The metadata schema of the mutation table.
+    """
+
+    migration: metadata_module.MetadataSchema = None
+    """
+    The metadata schema of the migration table.
+    """
+
+    individual: metadata_module.MetadataSchema = None
+    """
+    The metadata schema of the individual table.
+    """
+
+    population: metadata_module.MetadataSchema = None
+    """
+    The metadata schema of the population table.
+    """
+
+
 class TreeSequence:
     """
     A single tree sequence, as defined by the :ref:`data model <sec_data_model>`.
@@ -3819,33 +3861,17 @@ class TreeSequence:
     the :meth:`.variants` method iterates over all sites and their genotypes.
     """
 
-    @dataclass(frozen=True)
-    class _TableMetadataSchemas:
-        """
-        Convenience class for returning schemas
-        """
-
-        node: metadata_module.MetadataSchema = None
-        edge: metadata_module.MetadataSchema = None
-        site: metadata_module.MetadataSchema = None
-        mutation: metadata_module.MetadataSchema = None
-        migration: metadata_module.MetadataSchema = None
-        individual: metadata_module.MetadataSchema = None
-        population: metadata_module.MetadataSchema = None
-
     def __init__(self, ll_tree_sequence):
         self._ll_tree_sequence = ll_tree_sequence
         metadata_schema_strings = self._ll_tree_sequence.get_table_metadata_schemas()
         metadata_schema_instances = {
             name: metadata_module.parse_metadata_schema(
                 getattr(metadata_schema_strings, name)
             )
-            for name in vars(self._TableMetadataSchemas)
+            for name in vars(TableMetadataSchemas)
             if not name.startswith("_")
         }
-        self._table_metadata_schemas = self._TableMetadataSchemas(
-            **metadata_schema_instances
-        )
+        self._table_metadata_schemas = TableMetadataSchemas(**metadata_schema_instances)
         self._individuals_time = None
         self._individuals_population = None
         self._individuals_location = None
@@ -4134,7 +4160,7 @@ def num_samples(self):
         return self._ll_tree_sequence.get_num_samples()
 
     @property
-    def table_metadata_schemas(self) -> _TableMetadataSchemas:
+    def table_metadata_schemas(self) -> TableMetadataSchemas:
         """
         The set of metadata schemas for the tables in this tree sequence.
         """