Merge pull request #1500: Docs fixes

nextstrain · Jun 28, 2024 · f6ee377 · f6ee377
2 parents 6a8e8b9 + 5b4d696
commit f6ee377
Show file tree

Hide file tree

Showing 4 changed files with 50 additions and 46 deletions.
diff --git a/augur/import_/beast.py b/augur/import_/beast.py
@@ -16,7 +16,7 @@
 
 def register_parser(parent_subparsers):
     """
-    Arguments available to `augur import beast`
+    Arguments available to ``augur import beast``
     """
     beast_parser = parent_subparsers.add_parser('beast', help="Import beast analysis")
     beast_parser.add_argument("--beast", help=SUPPRESS, default=True) # used to disambiguate subcommands
@@ -38,20 +38,19 @@ def parse_beast_tree(data, tipMap, verbose=False):
 
     Parameters
     ----------
-    data : string
+    data : str
         The (really long) line in the NEXUS file beginning with "tree", pruned
         to start at the first "(" character.
     tipMap : dict
-        Mapping of tips (as encoded in `data`) to their names
-    verbose : bool, optional (default: false)
+        Mapping of tips (as encoded in ``data``) to their names
+    verbose : bool
         Should output be printed?
 
     Returns
     -------
-    <class 'Bio.Phylo.Newick.Clade'>
-
-    Author: Gytis Dudas
+    :py:class:`Bio.Phylo.Newick.Clade`
     """
+    # Author: Gytis Dudas
 
     i=0 ## is an adjustable index along the tree string, it is incremented to advance through the string
     stored_i=None ## store the i at the end of the loop, to make sure we haven't gotten stuck somewhere in an infinite loop
@@ -207,12 +206,12 @@ def parse_nexus(tree_path, treestring_regex=r'tree [A-Za-z\_]+([0-9]+)', verbose
 
     Parameters
     ----------
-    tree_path : string or file handle open for reading
+    tree_path
         The nexus tree file
-    treestring_regex : string
+    treestring_regex : str
         The regex to match the tree string in the nexus file (the really long
         string which typically starts with "tree" and looks similar to a newick tree)
-    verbose : bool, optional (default: False)
+    verbose : bool
         Should output be printed?
 
     Raises
@@ -222,11 +221,10 @@ def parse_nexus(tree_path, treestring_regex=r'tree [A-Za-z\_]+([0-9]+)', verbose
 
     Returns
     -------
-    <class 'Bio.Phylo.BaseTree.Tree'>
+    :py:class:`Bio.Phylo.BaseTree.Tree`
         A tree with BEAST attrs set on each node (as applicable)
-
-    Author: Gytis Dudas
     """
+    # Author: Gytis Dudas
 
     tipFlag=False
     tips={}
@@ -283,7 +281,7 @@ def summarise_parsed_traits(tree):
     """
     Parameters
     ----------
-    tree : <class 'Bio.Phylo.BaseTree.Tree'>
+    tree : :py:class:`Bio.Phylo.BaseTree.Tree`
     """
     traits = {}
     for node in tree.find_clades():
@@ -310,11 +308,11 @@ def fake_alignment(T):
 
     Parameters
     -------
-    T : <class 'Bio.Phylo.BaseTree.Tree'>
+    T : :py:class:`Bio.Phylo.BaseTree.Tree`
 
     Returns
     -------
-    <class 'Bio.Align.MultipleSeqAlignment'>
+    :py:class:`Bio.Align.MultipleSeqAlignment`
     """
     from Bio import SeqRecord, Seq, Align
     seqs = []
@@ -343,16 +341,16 @@ def find_most_recent_tip(tree, tip_date_regex, tip_date_format, tip_date_delimet
 
     Parameters
     --------
-    tree : <class 'Bio.Phylo.BaseTree.Tree'>
-    tip_date_regex : string
+    tree : :py:class:`Bio.Phylo.BaseTree.Tree`
+    tip_date_regex : str
         The regex used to extract the date (e.g. isolate collection date
         from each tip in the string.
         default: hyphen delimited numbers at the end of tip name
-    tip_date_format : string
+    tip_date_format : str
         The format of the extracted date.
         (e.g. "%Y-%m-%d" goes with "2012-10-30")
-    tip_date_delimeter : string
-        The delimeter in `tip_date_format`
+    tip_date_delimeter : str
+        The delimeter in ``tip_date_format``
 
     Raises
     ------
@@ -363,9 +361,8 @@ def find_most_recent_tip(tree, tip_date_regex, tip_date_format, tip_date_delimet
     -------
     float
         The date of the most recent tip in the tree in decimal format
-
-    Author: Gytis Dudas
     """
+    # Author: Gytis Dudas
 
     def decimalDate(date, date_fmt, variable=False):
         """ Converts calendar dates in specified format to decimal date. """
@@ -399,14 +396,11 @@ def calc_tree_dates(tree, most_recent_tip_date, tip_date_regex, tip_date_format,
 
     Parameters
     --------
-    tree : <class 'Bio.Phylo.BaseTree.Tree'>
-    # time_units : string
-    # tip_date : null | string
-    # most_recent_tip_data_fmt : string {"regex" | "decimal"}
-    most_recent_tip_date: numeric
-    tip_date_regex: string
-    tip_date_format: string
-    tip_date_delimeter: string
+    tree : :py:class:`Bio.Phylo.BaseTree.Tree`
+    most_recent_tip_date: float
+    tip_date_regex: str
+    tip_date_format: str
+    tip_date_delimeter: str
 
     Returns
     --------
@@ -415,9 +409,8 @@ def calc_tree_dates(tree, most_recent_tip_date, tip_date_regex, tip_date_format,
             The root date offset
         [1] : float
             The date of the most recent tip in the tree
-
-    TODO: Time units are taken as years, but days are also common for BEAST analysis
     """
+    # TODO: Time units are taken as years, but days are also common for BEAST analysis
 
     if most_recent_tip_date:
         most_recent_tip = float(most_recent_tip_date)
@@ -442,7 +435,7 @@ def collect_node_data(tree, root_date_offset, most_recent_tip_date):
 
     Parameters
     --------
-    tree : <class 'Bio.Phylo.BaseTree.Tree'>
+    tree : :py:class:`Bio.Phylo.BaseTree.Tree`
     root_date_offset : float
     most_recent_tip_date : float
 
@@ -497,11 +490,11 @@ def compute_entropies_for_discrete_traits(tree):
 
     Properties
     ----------
-    tree : <class 'Bio.Phylo.BaseTree.Tree'>
+    tree : :py:class:`Bio.Phylo.BaseTree.Tree`
         BEAST traits are set as key-value pairs on node.attrs
-
-    Author: James Hadfield
     """
+    # Author: James Hadfield
+
     alphabets = defaultdict(list) ## store alphabets
     for clade in tree.find_clades(): ## iterate over branches
         for attr in [key for key in clade.attrs if isinstance(clade.attrs[key], dict)]: ## iterate over branch attributes
@@ -521,8 +514,8 @@ def compute_entropies_for_discrete_traits(tree):
 
 def print_what_to_do_next(nodes, mcc_path, tree_path, node_data_path):
     """
-    Print a suggested `auspice_config.json` file, which the user will have to configure
-    and provide to `augur export`. There is not enough information in a MCC tree to do
+    Print a suggested ``auspice_config.json`` file, which the user will have to configure
+    and provide to ``augur export``. There is not enough information in a MCC tree to do
     this automatically.
     """
 

diff --git a/augur/utils.py b/augur/utils.py
@@ -181,7 +181,7 @@ def load_features(reference, feature_names=None):
     Returns
     -------
     features : dict
-        keys: feature names, values: <class 'Bio.SeqFeature.SeqFeature'> Note
+        keys: feature names, values: :py:class:`Bio.SeqFeature.SeqFeature` Note
         that feature names may not equivalent to GenBank feature keys
 
     Raises
@@ -207,13 +207,13 @@ def _read_nuc_annotation_from_gff(record, reference):
     
     Parameters
     ----------
-    record : <class 'Bio.SeqRecord.SeqRecord'>
+    record : :py:class:`Bio.SeqRecord.SeqRecord`
     reference: string
         File path to GFF reference
 
     Returns
     -------
-    <class 'Bio.SeqFeature.SeqFeature'>
+    :py:class:`Bio.SeqFeature.SeqFeature`
 
     Raises
     ------
@@ -279,7 +279,7 @@ def _read_gff(reference, feature_names):
     Returns
     -------
     features : dict
-        keys: feature names, values: <class 'Bio.SeqFeature.SeqFeature'>
+        keys: feature names, values: :py:class:`Bio.SeqFeature.SeqFeature`
         Note that feature names may not equivalent to GenBank feature keys
 
     Raises
@@ -360,11 +360,11 @@ def _read_nuc_annotation_from_genbank(record, reference):
     
     Parameters
     ----------
-    record : <class 'Bio.SeqRecord.SeqRecord'> reference: string
+    record : :py:class:`Bio.SeqRecord.SeqRecord` reference: string
 
     Returns
     -------
-    <class 'Bio.SeqFeature.SeqFeature'>
+    :py:class:`Bio.SeqFeature.SeqFeature`
 
     Raises
     ------
@@ -400,7 +400,7 @@ def _read_genbank(reference, feature_names):
     Returns
     -------
     features : dict
-        keys: feature names, values: <class 'Bio.SeqFeature.SeqFeature'>
+        keys: feature names, values: :py:class:`Bio.SeqFeature.SeqFeature`
         Note that feature names may not equivalent to GenBank feature keys
 
     Raises

diff --git a/docs/api/developer/augur.import.beast.rst b/docs/api/developer/augur.import.beast.rst
@@ -0,0 +1,7 @@
+augur.import.beast
+==================
+
+.. automodule:: augur.import_.beast
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/developer/augur.import.rst b/docs/api/developer/augur.import.rst
@@ -5,3 +5,7 @@ augur.import
    :members:
    :undoc-members:
    :show-inheritance:
+
+.. toctree::
+
+   augur.import.beast