More work on biothings_client docs

biothings_client/mixins/gene.py

@@ -2,6 +2,7 @@ class MyGeneClientMixin:
     def findgenes(self, id_li, **kwargs):
         '''.. deprecated:: 2.0.0
         Use :py:meth:`querymany` instead. It's kept here as an alias of :py:meth:`querymany` method.
+
         '''
         import warnings
         warnings.warn('Deprecated! Currently an alias of "querymany" method. Use "querymany" method directly.', DeprecationWarning)

biothings_client/mixins/variant.py

@@ -4,15 +4,17 @@
 class MyVariantClientMixin:
     '''Adding some utility methods specific to MyVariant.info API.'''
     def get_hgvs_from_vcf(self, input_vcf):
-        '''From the input VCF file (filename or file handle), return a generator
-           of genomic based HGVS ids.
-           :param input_vcf: input VCF file, can be a filename or a file handle
-           :returns: a generator of genomic based HGVS ids. To get back a list
-                     instead, using *list(get_hgvs_from_vcf("your_vcf_file"))*
-           .. NOTE:: This is a lightweight VCF parser to return valid genomic-based
-                     HGVS ids from the *input_vcf* file. For more sophisticated VCF
-                     parser, consider using `PyVCF <https://pypi.python.org/pypi/PyVCF>`_
-                     module.
+        '''
+            From the input VCF file (filename or file handle), return a generator
+            of genomic based HGVS ids.
+            :param input_vcf: input VCF file, can be a filename or a file handle
+            :returns: a generator of genomic based HGVS ids. To get back a list
+                      instead, using *list(get_hgvs_from_vcf("your_vcf_file"))*
+            .. NOTE:: This is a lightweight VCF parser to return valid genomic-based
+                      HGVS ids from the *input_vcf* file. For more sophisticated VCF
+                      parser, consider using `PyVCF <https://pypi.python.org/pypi/PyVCF>`_
+                      module.
+
         '''
         if isinstance(input_vcf, str_types):
             # if input_vcf is a string, open it as a file

docs/conf.py

@@ -21,6 +21,11 @@
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
+import sys, os
+sys.path.insert(0, '..')
+from biothings_client import __version__
+
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 
 # -- General configuration ------------------------------------------------
 
@@ -31,7 +36,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.autodoc']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -55,9 +60,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = ''
+version = 'v' + __version__
 # The full version, including alpha/beta/rc tags.
-release = ''
+release = version
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -83,7 +88,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'default'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -154,4 +159,10 @@
 ]
 
 
+if not on_rtd:
+    import sphinx_rtd_theme
+    html_theme = 'sphinx_rtd_theme'
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
+autoclass_content = 'both'
+autodoc_member_order = 'bysource'

docs/doc/API.rst

@@ -0,0 +1,39 @@
+API Documentation
+=================
+
+Detailed documentation of the biothings_client package can be found on this page.
+
+get_client
+++++++++++
+.. py:module:: biothings_client
+.. autofunction:: get_client
+
+MyGeneInfo
+++++++++++
+.. autoclass:: MyGeneInfo
+    :members:
+    :inherited-members:
+
+MyVariantInfo
++++++++++++++
+.. autoclass:: MyVariantInfo
+    :members:
+    :inherited-members:
+
+MyChemInfo
+++++++++++
+.. autoclass:: MyChemInfo
+    :members:
+    :inherited-members:
+
+MyDiseaseInfo
++++++++++++++
+.. autoclass:: MyDiseaseInfo
+    :members:
+    :inherited-members:
+
+MyTaxonInfo
++++++++++++
+.. autoclass:: MyTaxonInfo
+    :members:
+    :inherited-members:

docs/doc/Custom-API.rst

@@ -0,0 +1,23 @@
+Instantiating a Client for a Custom BioThings API
+=================================================
+
+The Quick Start tutorial shows how to get clients for all publicly available BioThings APIs.  What if you create your own custom BioThings API?  
+
+With biothings_client, you can generate client settings for any future APIs created with BioThings API.  The `BioThings API Single source tutorial <https://biothingsapi.readthedocs.io/en/latest/doc/single_source_tutorial.html>`_ explains how to set up a simple BioThings API from PharmGKB gene data.  The following code snippet shows an example of how to setup biothings_client to access that custom API:
+
+.. code-block:: python
+
+    In [1]: from biothings_client import get_client
+
+    In [2]: pharmgkb_client = get_client('gene', url='http://35.164.95.182:8000/v1')
+
+    In [3]: pharmgkb_client.query('ncbi_gene_id:1017', fields='pharmgkb_accession_id')
+    Out[3]:
+    {'hits': [{'_id': 'cOydWmcBViFqgJfo4gdM',
+       '_score': 7.495912,
+       'pharmgkb_accession_id': 'PA101'}],
+     'max_score': 7.495912,
+     'took': 10,
+     'total': 1}
+
+The **url** parameter to **get_client** specifies where the BioThings API endpoint is located (the address above is temporary and is no longer serviced by us).  The entity parameter is still 'gene' (as the entity type of PharmGKB gene is gene).