improve code docstrings and Sphinx documentation

Former-commit-id: afcd004395586bedc7b56193c0a63167346bd2f5

ippisite/docs/source/conf.py

@@ -190,3 +190,22 @@ epub_exclude_files = ['search.html']
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'https://docs.python.org/': None}
+
+# -- Extension configuration -------------------------------------------------i
+
+autoclass_content = "both"  # include both class docstring and __init__
+autodoc_default_flags = [
+        # Make sure that any autodoc declarations show the right members
+        "members",
+        "inherited-members",
+        "private-members",
+        "show-inheritance",
+]
+autosummary_generate = True  # Make _autosummary files and include them
+napoleon_numpy_docstring = False  # Force consistency, leave only Google
+napoleon_use_rtype = False  # More legible
+
+# The suffix of source filenames.
+autosummary_generate = True
+
+exclude_patterns = ['_build']

ippisite/ippidb/__init__.py

@@ -2,19 +2,19 @@
 This is the main ippidb module
 
 .. autosummary::
-   :toctree: _autosummary
+    :toctree: _autosummary
 
-   admin
-   apps
-   forms
-   gx
-   models
-   tests
-   urls
-   utils
-   views
-   ws
-   management
-   migrations
-   templatetags
+    admin
+    apps
+    forms
+    gx
+    models
+    tests
+    urls
+    utils
+    views
+    ws
+    management
+    migrations
+    templatetags
 """

ippisite/ippidb/admin.py

+"""
+iPPI-DB django admin module 
+"""
+
 from django.contrib import admin
 from .models import *
 from django.apps import apps
@@ -64,4 +68,4 @@ admin.site.site_title = admin.site.site_header
 
 admin.site.index_header = 'iPPI-DB administration'
 
-admin.site.index_title = admin.site.index_header
\ No newline at end of file
+admin.site.index_title = admin.site.index_header

ippisite/ippidb/apps.py

+"""
+iPPI-DB Django app config file
+"""
+
 from django.apps import AppConfig
 
 

ippisite/ippidb/forms.py

+"""
+iPPI-DB django forms
+"""
+
 from django.forms import ModelForm, modelformset_factory, modelform_factory, formset_factory, BaseFormSet, BaseModelFormSet
 from django import forms
 from django.db import models

ippisite/ippidb/gx.py

+"""
+iPPI-DB-Galaxy communication module
+"""
 from bioblend.galaxy import GalaxyInstance
 from bioblend.galaxy.tools.inputs import inputs
 

ippisite/ippidb/management/__init__.py

+"""
+iPPI-DB management package
+"""

ippisite/ippidb/migrations/__init__.py

+"""
+iPPI-DB django migrations package
+"""

ippisite/ippidb/models.py

+"""
+Models used in iPPI-DB
+"""
+
 from __future__ import unicode_literals
 import operator
 
@@ -762,4 +766,4 @@ class DrugbankCompoundTanimoto(models.Model):
     compound = models.ForeignKey(Compound, models.CASCADE)
     drugbank_compound = models.ForeignKey(DrugBankCompound, models.CASCADE)
     tanimoto = models.DecimalField(
-        'Tanimoto value', max_digits=5, decimal_places=4)
\ No newline at end of file
+        'Tanimoto value', max_digits=5, decimal_places=4)

ippisite/ippidb/templatetags/__init__.py

+"""
+iPPI-DB template tags package
+"""

ippisite/ippidb/tests.py

+"""
+iPPI-DB unit tests
+"""
+
 import re
 
 from django.test import TestCase

ippisite/ippidb/urls.py

+"""
+iPPI-DB URLs routing module
+"""
+
 from django.conf.urls import include, url
 from . import views
 from ippidb.forms import *

ippisite/ippidb/utils.py

+"""
+iPPI-DB chemoinformatics utility functions
+"""
+
 #FIXME: to work, this currently needs awkward PYTHONPATH tweaks, like:
 #$export PYTHONPATH=/home/hmenager/openbabellocal/lib/python3.6/site-packages/:$PYTHONPATH
 import pybel
@@ -65,4 +69,4 @@ class FingerPrinter(object):
     def tanimoto_smiles(self, query_smiles, smiles_dict):
         "perform a tanimoto similarity search using a smiles query on a dict of {compound id: SMILES}"
         fp_dict = self.fp_dict(smiles_dict)
-        return self.tanimoto_fps(query_smiles, fp_dict)
\ No newline at end of file
+        return self.tanimoto_fps(query_smiles, fp_dict)

ippisite/ippidb/views.py

+"""
+iPPI-DB django views module
+"""
+
 import json
 import math
 from collections import OrderedDict

ippisite/ippidb/ws.py

+"""
+iPPI-DB web-service client utility functions
+"""
+
 from bioservices.eutils import EUtils
 from bioservices.uniprot import UniProt
 import xml.etree.ElementTree as ET
@@ -5,6 +9,14 @@ import requests
 from bs4 import BeautifulSoup
 
 def get_pubmed_info(pmid):
+    """
+    Retrieve information about a publication from  NCBI PubMed
+
+    :param pmid: PubMed ID
+    :type pmid: str
+    :return: publication metadata (title, journal name, publication year, authors list).
+    :rtype: dict
+    """
     eu = EUtils()
     r = eu.EFetch('pubmed', pmid, retmode='dict', rettype='abstract')
     article = r['PubmedArticleSet'][
@@ -26,7 +38,16 @@ def get_pubmed_info(pmid):
 
 
 def get_epo_info(patent_number):
-    """ warning: this is not to be used anymore, the 3.1 version of the EPO service is now offline """ 
+    """
+    Retrieve information about a patent using the EPO website
+
+    WARNING: this is not to be used anymore, the 3.1 version of the EPO service is now offline
+
+    :param patent_number: patent number
+    :type patent_number: str
+    :return: patent metadata (title, journal name, publication year, authors list).
+    :rtype: dict
+    """
     resp = requests.get(
         'http://ops.epo.org/3.1/rest-services/published-data/publication/docdb/{}/biblio.json'.format(patent_number))
     data = resp.json()
@@ -46,7 +67,16 @@ def get_epo_info(patent_number):
             'authors_list': authors}
 
 def get_google_patent_info_ris(patent_number):
-    """ warning: now offline """ 
+    """
+    Retrieve information about a patent using the Google RIS web service
+
+    WARNING: this is not to be used anymore, this Google Web service is now offline
+
+    :param patent_number: patent number
+    :type patent_number: str
+    :return: patent metadata (title, journal name, publication year, authors list).
+    :rtype: dict
+    """
     url = 'https://encrypted.google.com/patents/{}.ris'.format(patent_number)
     resp = requests.get(url)
     title = None
@@ -66,6 +96,14 @@ def get_google_patent_info_ris(patent_number):
             'authors_list': authors}
 
 def get_google_patent_info(patent_number):
+    """
+    Retrieve information about a patent parsing Dublin Core info in the Google HTML
+
+    :param patent_number: patent number
+    :type patent_number: str
+    :return: patent metadata (title, journal name, publication year, authors list).
+    :rtype: dict
+    """
     url = 'https://encrypted.google.com/patents/{}'.format(patent_number)
     resp = requests.get(url)
     soup = BeautifulSoup(resp.text, 'html.parser')
@@ -81,6 +119,14 @@ def get_google_patent_info(patent_number):
             'authors_list': authors}
 
 def get_uniprot_info(uniprot_id):
+    """
+    Retrieve information about a protein from the Uniprot database
+
+    :param uniprot_id: Uniprot ID
+    :type uniprot_id: str
+    :return: protein metadata (recommended name, organism, gene, entry name, short name, molecular functions).
+    :rtype: dict
+    """
     uniprot_client = UniProt()
     ns = {'u': 'http://uniprot.org/uniprot'}
     resp = uniprot_client.retrieve(uniprot_id)
@@ -111,6 +157,14 @@ def get_uniprot_info(uniprot_id):
 
 
 def get_go_info(go_id):
+    """
+    Retrieve information about a GO term using the EBI OLS web service
+
+    :param go_id: Gene Ontology id
+    :type go_id: str
+    :return: GO metadata (label).
+    :rtype: dict
+    """
     resp = requests.get(
         'https://www.ebi.ac.uk/ols/api/ontologies/go/terms/http%253A%252F%252Fpurl.obolibrary.org%252Fobo%252F{}'.format(go_id))
     data = resp.json()
@@ -119,6 +173,14 @@ def get_go_info(go_id):
 
 
 def get_taxonomy_info(taxonomy_id):
+    """
+    Retrieve information about a taxon using the NCBI Entrez web services
+
+    :param taxonomy_id: Taxonomy ID
+    :type taxonomy_id: str
+    :return: Taxon metadata (scientific name).
+    :rtype: dict
+    """
     eu = EUtils()
     r = eu.EFetch('taxonomy', taxonomy_id, retmode='dict')
     scientific_name = r['TaxaSet']['Taxon']['ScientificName']
@@ -126,6 +188,14 @@ def get_taxonomy_info(taxonomy_id):
 
 
 def get_pfam_info(pfam_acc):
+    """
+    Retrieve information about a protein family using the PFAM web service
+
+    :param pfam_acc: PFAM accession number
+    :type pfam_acc: str
+    :return: Protein family metadata (id, description).
+    :rtype: dict
+    """
     resp = requests.get(
         'http://pfam.xfam.org/family/{}?output=xml'.format(pfam_acc))
     root = ET.fromstring(resp.text)
@@ -139,6 +209,14 @@ def get_pfam_info(pfam_acc):
 
 
 def get_pdb_uniprot_mapping(pdb_id):
+    """
+    Retrieve PDB to uniprot mappings using the PDBe web service
+
+    :param pdb_id: PDB ID
+    :type pdb_id: str
+    :return: Uniprot IDs
+    :rtype: list
+    """
     pdb_id = pdb_id.lower()
     resp = requests.get(
         'https://www.ebi.ac.uk/pdbe/api/mappings/uniprot/{}'.format(pdb_id.lower()))
@@ -147,11 +225,18 @@ def get_pdb_uniprot_mapping(pdb_id):
 
 
 def pdb_entry_exists(pdb_id):
-    """ test if a PDB entry exists using EBI web services """
+    """
+    Test if a PDB entry exists using EBI web services 
+
+    :param pdb_id: PDB ID
+    :type pdb_id: str
+    :return: True/False wether the PDB entry exists
+    :rtype: bool
+    """
+    """ """
     resp = requests.get(
         'https://www.ebi.ac.uk/pdbe/api/pdb/entry/summary/{}'.format(pdb_id.lower()))
     # EBI sends back either a 404 or an empty json if the PDB does not exist
-    print("PDB id:", pdb_id)
     if not(resp.ok):
         return False
     else: