[hail][docs] fix a bunch of issues

hail/.gitignore

@@ -41,6 +41,8 @@ python/hail/docs/hail.expr.StructExpression.rst
 python/hail/docs/hail.expr.TupleExpression.rst
 python/hail/docs/linalg/hail.linalg.BlockMatrix.rst
 python/hail/docs/stats/hail.stats.LinearMixedModel.rst
+python/hail/docs/functions/hail.expr.builders.CaseBuilder.rst
+python/hail/docs/functions/hail.expr.builders.SwitchBuilder.rst
 src/main/c/.cxx.vsn
 src/main/c/headers
 src/main/c/lib

hail/python/hail/context.py

@@ -172,17 +172,17 @@ def init(sc=None, app_name='Hail', master=None, local='local[*]',
     ----------
     sc : pyspark.SparkContext, optional
         Spark context. By default, a Spark context will be created.
-    app_name : :obj:`str`
+    app_name : :class:`str`
         Spark application name.
-    master : :obj:`str`, optional
+    master : :class:`str`, optional
         URL identifying the Spark leader (master) node or `local[N]` for local clusters.
-    local : :obj:`str`
+    local : :class:`str`
        Local-mode core limit indicator. Must either be `local[N]` where N is a
        positive integer or `local[*]`. The latter indicates Spark should use all
        cores available. `local[*]` does not respect most containerization CPU
        limits. This option is only used if `master` is unset and `spark.master`
        is not set in the Spark configuration.
-    log : :obj:`str`
+    log : :class:`str`
         Local path for Hail log file. Does not currently support distributed
         file systems like Google Storage, S3, or HDFS.
     quiet : :obj:`bool`
@@ -193,21 +193,21 @@ def init(sc=None, app_name='Hail', master=None, local='local[*]',
         Minimum file block size in MB.
     branching_factor : :obj:`int`
         Branching factor for tree aggregation.
-    tmp_dir : :obj:`str`, optional
+    tmp_dir : :class:`str`, optional
         Networked temporary directory.  Must be a network-visible file
         path.  Defaults to /tmp in the default scheme.
-    default_reference : :obj:`str`
+    default_reference : :class:`str`
         Default reference genome. Either ``'GRCh37'``, ``'GRCh38'``,
         ``'GRCm38'``, or ``'CanFam3'``.
     idempotent : :obj:`bool`
         If ``True``, calling this function is a no-op if Hail has already been initialized.
     global_seed : :obj:`int`, optional
         Global random seed.
-    spark_conf : :obj:`dict[str, str]`, optional
+    spark_conf : :obj:`dict` of :class:`str` to :class`str`, optional
         Spark configuration parameters.
     skip_logging_configuration : :obj:`bool`
         Skip logging configuration in java and python.
-    local_tmpdir : :obj:`str`, optional
+    local_tmpdir : :class:`str`, optional
         Local temporary directory.  Used on driver and executor nodes.
         Must use the file scheme.  Defaults to TMPDIR, or /tmp.
     """
@@ -385,7 +385,7 @@ def default_reference():
     return Env.hc().default_reference
 
 
-def get_reference(name) -> 'hail.ReferenceGenome':
+def get_reference(name):
     """Returns the reference genome corresponding to `name`.
 
     Notes
@@ -404,7 +404,7 @@ def get_reference(name) -> 'hail.ReferenceGenome':
 
     Parameters
     ----------
-    name : :obj:`str`
+    name : :class:`str`
         Name of a previously loaded reference genome or one of Hail's built-in
         references: ``'GRCh37'``, ``'GRCh38'``, ``'GRCm38'``, ``'CanFam3'``, and
         ``'default'``.

hail/python/hail/docs/Makefile

@@ -9,7 +9,7 @@ BUILDDIR      = _build
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -W -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS)  -W --keep-going  .
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 

hail/python/hail/docs/_templates/_autosummary/class2.rst

@@ -4,7 +4,6 @@
 
 .. autoclass:: {{ objname }}()
     :members:
-    :show-inheritance:
     :special-members:
     :inherited-members:
     :no-undoc-members:

hail/python/hail/docs/api.rst

@@ -46,6 +46,8 @@ Top-Level Functions
 ~~~~~~~~~~~~~~~~~~~
 
 .. autofunction:: hail.init
+.. autofunction:: hail.asc
+.. autofunction:: hail.desc
 .. autofunction:: hail.stop
 .. autofunction:: hail.spark_context
 .. autofunction:: hail.default_reference

hail/python/hail/docs/conf.py

@@ -29,6 +29,8 @@
 
 # -- General configuration ------------------------------------------------
 
+nitpicky = True
+
 # If your documentation needs a minimal Sphinx version, state it here.
 #
 needs_sphinx = '1.5.4'
@@ -45,7 +47,8 @@
     'nbsphinx',
     # https://github.com/spatialaudio/nbsphinx/issues/24#issuecomment-187172022 and https://github.com/ContinuumIO/anaconda-issues/issues/1430
     'IPython.sphinxext.ipython_console_highlighting',
-    'sphinx.ext.napoleon'
+    'sphinx.ext.napoleon',
+    'sphinx.ext.intersphinx'
 ]
 
 katex_css_path = \
@@ -87,10 +90,19 @@
                         ]
 # autoclass_content = "both"
 autodoc_default_flags = ['members', 'undoc-members']
+autodoc_typehints = 'none'  # https://github.com/hail-is/hail/pull/9403#issuecomment-703776111
 
 napoleon_use_rtype = False
 napoleon_use_param = False
 
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3.7', None),
+    'PySpark': ('https://spark.apache.org/docs/latest/api/python/', None),
+    'Bokeh': ('https://docs.bokeh.org/en/1.2.0/', None),
+    'numpy': ('https://numpy.org/doc/stable/', None),
+    'scipy': ('https://docs.scipy.org/doc/scipy-1.3.3/reference', None),
+    'pandas': ('https://pandas.pydata.org/docs/', None)}
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates', '_templates/_autosummary']
 

hail/python/hail/docs/datasets/1000_Genomes_autosomes.rst

@@ -5,7 +5,7 @@
 
 *  **Versions:** phase_3
 *  **Reference genome builds:** GRCh37, GRCh38
-*  **Type:** :class:`MatrixTable`
+*  **Type:** :class:`hail.MatrixTable`
 
 Schema (phase_3, GRCh37)
 ~~~~~~~~~~~~~~~~~~~~~~~~

hail/python/hail/docs/datasets/1000_Genomes_chrMT.rst

@@ -5,7 +5,7 @@
 
 *  **Versions:** phase_3
 *  **Reference genome builds:** GRCh37
-*  **Type:** :class:`MatrixTable`
+*  **Type:** :class:`hail.MatrixTable`
 
 Schema (phase_3, GRCh37)
 ~~~~~~~~~~~~~~~~~~~~~~~~

hail/python/hail/docs/datasets/1000_Genomes_chrX.rst

@@ -5,7 +5,7 @@
 
 *  **Versions:** phase_3
 *  **Reference genome builds:** GRCh37, GRCh38
-*  **Type:** :class:`MatrixTable`
+*  **Type:** :class:`hail.MatrixTable`
 
 Schema (phase_3, GRCh37)
 ~~~~~~~~~~~~~~~~~~~~~~~~

hail/python/hail/docs/datasets/1000_Genomes_chrY.rst

@@ -5,7 +5,7 @@
 
 *  **Versions:** phase_3
 *  **Reference genome builds:** GRCh37, GRCh38
-*  **Type:** :class:`MatrixTable`
+*  **Type:** :class:`hail.MatrixTable`
 
 Schema (phase_3, GRCh37)
 ~~~~~~~~~~~~~~~~~~~~~~~~

hail/python/hail/docs/datasets/CADD.rst

@@ -5,7 +5,7 @@ CADD
 
 *  **Versions:** 1.4
 *  **Reference genome builds:** GRCh37, GRCh38
-*  **Type:** :class:`Table`
+*  **Type:** :class:`hail.Table`
 
 Schema (1.4, GRCh37)
 ~~~~~~~~~~~~~~~~~~~~

hail/python/hail/docs/datasets/DANN.rst

@@ -5,7 +5,7 @@ DANN
 
 *  **Versions:** None
 *  **Reference genome builds:** GRCh37, GRCh38
-*  **Type:** :class:`Table`
+*  **Type:** :class:`hail.Table`
 
 Schema (None, GRCh37)
 ~~~~~~~~~~~~~~~~~~~~~

hail/python/hail/docs/datasets/Ensembl_homo_sapiens_low_complexity_regions.rst

@@ -5,7 +5,7 @@ Ensembl_homo_sapiens_low_complexity_regions
 
 *  **Versions:** release_95
 *  **Reference genome builds:** GRCh37, GRCh38
-*  **Type:** :class:`Table`
+*  **Type:** :class:`hail.Table`
 
 Schema (release_95, GRCh37)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

hail/python/hail/docs/datasets/Ensembl_homo_sapiens_reference_genome.rst

@@ -5,7 +5,7 @@ Ensembl_homo_sapiens_reference_genome
 
 *  **Versions:** release_95
 *  **Reference genome builds:** GRCh37, GRCh38
-*  **Type:** :class:`Table`
+*  **Type:** :class:`hail.Table`
 
 Schema (release_95, GRCh37)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

hail/python/hail/docs/datasets/GTEx_RNA_seq_gene_TPMs.rst

@@ -5,7 +5,7 @@ GTEx_RNA_seq_gene_TPMs
 
 *  **Versions:** v7
 *  **Reference genome builds:** GRCh37
-*  **Type:** :class:`MatrixTable`
+*  **Type:** :class:`hail.MatrixTable`
 
 Schema (v7, GRCh37)
 ~~~~~~~~~~~~~~~~~~~

hail/python/hail/docs/datasets/GTEx_RNA_seq_gene_read_counts.rst

@@ -5,7 +5,7 @@ GTEx_RNA_seq_gene_read_counts
 
 *  **Versions:** v7
 *  **Reference genome builds:** GRCh37
-*  **Type:** :class:`MatrixTable`
+*  **Type:** :class:`hail.MatrixTable`
 
 Schema (v7, GRCh37)
 ~~~~~~~~~~~~~~~~~~~

hail/python/hail/docs/datasets/GTEx_RNA_seq_junction_read_counts.rst

@@ -5,7 +5,7 @@ GTEx_RNA_seq_junction_read_counts
 
 *  **Versions:** v7
 *  **Reference genome builds:** GRCh37
-*  **Type:** :class:`MatrixTable`
+*  **Type:** :class:`hail.MatrixTable`
 
 Schema (v7, GRCh37)
 ~~~~~~~~~~~~~~~~~~~

hail/python/hail/docs/datasets/UK_Biobank_Rapid_GWAS_both_sexes.rst

@@ -5,7 +5,7 @@ UK_Biobank_Rapid_GWAS_both_sexes
 
 *  **Versions:** v2
 *  **Reference genome builds:** GRCh37
-*  **Type:** :class:`MatrixTable`
+*  **Type:** :class:`hail.MatrixTable`
 
 Schema (v2, GRCh37)
 ~~~~~~~~~~~~~~~~~~~

hail/python/hail/docs/datasets/UK_Biobank_Rapid_GWAS_female.rst

@@ -5,7 +5,7 @@ UK_Biobank_Rapid_GWAS_female
 
 *  **Versions:** v2
 *  **Reference genome builds:** GRCh37
-*  **Type:** :class:`MatrixTable`
+*  **Type:** :class:`hail.MatrixTable`
 
 Schema (v2, GRCh37)
 ~~~~~~~~~~~~~~~~~~~

hail/python/hail/docs/datasets/UK_Biobank_Rapid_GWAS_male.rst

@@ -5,7 +5,7 @@ UK_Biobank_Rapid_GWAS_male
 
 *  **Versions:** v2
 *  **Reference genome builds:** GRCh37
-*  **Type:** :class:`MatrixTable`
+*  **Type:** :class:`hail.MatrixTable`
 
 Schema (v2, GRCh37)
 ~~~~~~~~~~~~~~~~~~~

hail/python/hail/docs/datasets/clinvar_gene_summary.rst

@@ -5,7 +5,7 @@ clinvar_gene_summary
 
 *  **Versions:** 2019-07
 *  **Reference genome builds:** None
-*  **Type:** :class:`Table`
+*  **Type:** :class:`.Table`
 
 Schema (2019-07, None)
 ~~~~~~~~~~~~~~~~~~~~~~

hail/python/hail/docs/datasets/clinvar_variant_summary.rst

@@ -5,7 +5,7 @@ clinvar_variant_summary
 
 *  **Versions:** 2019-07
 *  **Reference genome builds:** GRCh37, GRCh38
-*  **Type:** :class:`Table`
+*  **Type:** :class:`.Table`
 
 Schema (2019-07, GRCh37)
 ~~~~~~~~~~~~~~~~~~~~~~~~

hail/python/hail/docs/datasets/dbNSFP_genes.rst

@@ -5,7 +5,7 @@ dbNSFP_genes
 
 *  **Versions:** 4.0
 *  **Reference genome builds:** None
-*  **Type:** :class:`Table`
+*  **Type:** :class:`.Table`
 
 Schema (4.0, None)
 ~~~~~~~~~~~~~~~~~~

hail/python/hail/docs/datasets/dbNSFP_variants.rst

@@ -5,7 +5,7 @@ dbNSFP_variants
 
 *  **Versions:** 4.0
 *  **Reference genome builds:** GRCh37, GRCh38
-*  **Type:** :class:`Table`
+*  **Type:** :class:`.Table`
 
 Schema (4.0, GRCh37)
 ~~~~~~~~~~~~~~~~~~~~

hail/python/hail/docs/datasets/gencode.rst

@@ -5,7 +5,7 @@ gencode
 
 *  **Versions:** v19, v31
 *  **Reference genome builds:** GRCh37, GRCh38
-*  **Type:** :class:`Table`
+*  **Type:** :class:`.Table`
 
 Schema (v19, GRCh37)
 ~~~~~~~~~~~~~~~~~~~~

hail/python/hail/docs/datasets/gerp_elements.rst

@@ -5,7 +5,7 @@ gerp_elements
 
 *  **Versions:** hg19
 *  **Reference genome builds:** GRCh37, GRCh38
-*  **Type:** :class:`Table`
+*  **Type:** :class:`.Table`
 
 Schema (hg19, GRCh37)
 ~~~~~~~~~~~~~~~~~~~~~

hail/python/hail/docs/datasets/gerp_scores.rst

@@ -5,7 +5,7 @@ gerp_scores
 
 *  **Versions:** hg19
 *  **Reference genome builds:** GRCh37, GRCh38
-*  **Type:** :class:`Table`
+*  **Type:** :class:`.Table`
 
 Schema (hg19, GRCh37)
 ~~~~~~~~~~~~~~~~~~~~~

hail/python/hail/docs/datasets/gnomad_exome_sites.rst

@@ -5,7 +5,7 @@ gnomad_exome_sites
 
 *  **Versions:** 2.1.1
 *  **Reference genome builds:** GRCh37, GRCh38
-*  **Type:** :class:`Table`
+*  **Type:** :class:`.Table`
 
 Schema (2.1.1, GRCh37)
 ~~~~~~~~~~~~~~~~~~~~~~

hail/python/hail/docs/datasets/gnomad_genome_sites.rst

@@ -5,7 +5,7 @@ gnomad_genome_sites
 
 *  **Versions:** 2.1.1
 *  **Reference genome builds:** GRCh37, GRCh38
-*  **Type:** :class:`Table`
+*  **Type:** :class:`.Table`
 
 Schema (2.1.1, GRCh37)
 ~~~~~~~~~~~~~~~~~~~~~~

hail/python/hail/docs/datasets/gnomad_lof_metrics.rst

@@ -5,7 +5,7 @@ gnomad_lof_metrics
 
 *  **Versions:** 2.1.1
 *  **Reference genome builds:** None
-*  **Type:** :class:`Table`
+*  **Type:** :class:`.Table`
 
 Schema (2.1.1, None)
 ~~~~~~~~~~~~~~~~~~~~

hail/python/hail/docs/datasets/ldsc_baselineLD_annotations.rst

@@ -5,7 +5,7 @@ ldsc_baselineLD_annotations
 
 *  **Versions:** 2.2
 *  **Reference genome builds:** GRCh37
-*  **Type:** :class:`Table`
+*  **Type:** :class:`.Table`
 
 Schema (2.2, GRCh37)
 ~~~~~~~~~~~~~~~~~~~~

hail/python/hail/docs/datasets/ldsc_baselineLD_ldscores.rst

@@ -5,7 +5,7 @@ ldsc_baselineLD_ldscores
 
 *  **Versions:** 2.2
 *  **Reference genome builds:** GRCh37
-*  **Type:** :class:`MatrixTable`
+*  **Type:** :class:`.MatrixTable`
 
 Schema (2.2, GRCh37)
 ~~~~~~~~~~~~~~~~~~~~

hail/python/hail/docs/datasets/ldsc_baseline_ldscores.rst

@@ -5,7 +5,7 @@ ldsc_baseline_ldscores
 
 *  **Versions:** 1.1
 *  **Reference genome builds:** GRCh37
-*  **Type:** :class:`MatrixTable`
+*  **Type:** :class:`.MatrixTable`
 
 Schema (1.1, GRCh37)
 ~~~~~~~~~~~~~~~~~~~~

hail/python/hail/docs/experimental/vcf_combiner.rst

@@ -195,7 +195,7 @@ Functions
 ~~~~~~~~~
 
 There are a number of functions for working with sparse data. Of particular
-importance is :func:`densify`, which transforms a sparse matrix table to a dense
+importance is :func:`~.densify`, which transforms a sparse matrix table to a dense
 project-VCF-like matrix table on the fly. While computationally expensive, this
 operation is necessary for many downstream analyses, and should be thought of as
 roughly costing as much as reading a matrix table created by importing a dense