API docs for propka

- use autosummary (with custom module template)
- updated module docs for all modules so that they are included
  with sphinx autodocs

docs/source/api.rst

@@ -0,0 +1,78 @@
+.. -*- coding: utf-8 -*-
+
+===============
+ API Reference
+===============
+
+The :program:`propka3` command provides a command-line interface to
+PROPKA 3's functionality. It is built on classes and functions in the
+:mod:`propka` module. The API of :mod:`propka` is documented here for
+developers who might want to directly use the PROPKA 3 code.
+
+.. Note::
+
+   The API is still changing and there is currently no guarantee that
+   it will remain stable between minor releases.
+
+
+
+.. currentmodule:: propka
+
+.. module:: propka		   
+
+
+Data structures
+===============
+
+.. autosummary::
+   :toctree: api
+      
+   atom
+   bonds
+   group   
+   conformation_container
+   molecular_container
+
+   
+I/O
+===
+
+.. autosummary::
+   :toctree: api
+
+   input
+   lib
+   output
+   parameters
+   hybrid36
+   ligand_pka_values
+   run
+   version
+   
+   
+Structure processing
+====================
+
+.. autosummary::
+   :toctree: api
+
+   protonate
+   hydrogens	     
+   ligand
+
+	     
+Calculations
+============
+
+.. autosummary::
+   :toctree: api
+
+   calculations
+   coupled_groups
+   determinant
+   determinants
+   energy
+   iterative
+   vector_algebra
+
+

docs/source/index.rst

@@ -18,6 +18,9 @@ PROPKA 3 predicts the |pKa| values of ionizable groups in proteins
 [Sondergaard2011]_ and protein-ligand complexes based on the 3D
 structure [Olsson2011]_.
 
+This package installs the :program:`propka3` command and the
+:mod:`propka` Python package.
+
    
 License and source code
 =======================
@@ -81,6 +84,7 @@ Indices and tables
 
    installation
    quickstart
+   api
    references
 
   

docs/source/installation.rst

@@ -21,7 +21,7 @@ The easiest way to install a release of PROPKA 3 is from the `PyPI archive`_ wit
 
    
 This installation will install the :mod:`propka` Python module and the
-:command:`propka3` executable script. As always, a virtual environment (e.g., via
+:program:`propka3` executable script. As always, a virtual environment (e.g., via
 `virtualenv`_) is recommended when installing packages.
 
 Source-based installation

docs/source/quickstart.rst

@@ -8,7 +8,7 @@
  Quickstart Guide
 ==================
 
-PROPKA can be used either as a module or via the installed script :command:`propka3`; i.e., either
+PROPKA can be used either as a module or via the installed script :program:`propka3`; i.e., either
 
 .. code-block:: bash
 
@@ -26,9 +26,9 @@ works for invoking PROPKA.
 Predicting protein residue |pKa| values
 =======================================
 
-Most users run PROPKA by invoking the program with a PDB file as its
+Most users run PROPKA by invoking the :program:`propka3` program with
-argument; e.g., for PDB 1HPX_ (HIV-1 protease complexed with the
+a PDB file as its argument; e.g., for PDB 1HPX_ (HIV-1 protease
-inhibitor KNI-272)
+complexed with the inhibitor KNI-272)
 
 .. code-block:: bash
 

propka/__init__.py

@@ -1,6 +1,6 @@
 """PROPKA 3
 
-See https://github.com/jensengroup/propka-3.1 for more information.
+See https://github.com/jensengroup/propka for more information.
 
 Please cite these PROPKA references in publications:
 

propka/atom.py

@@ -1,4 +1,11 @@
-"""Atom class - contains all atom information found in the PDB file"""
+"""
+Atom
+====
+
+The :class:`Atom` class contains all atom information found in the PDB file.
+
+"""
+
 import string
 from propka.lib import make_tidy_atom_label
 from . import hybrid36

propka/bonds.py

@@ -1,4 +1,10 @@
-"""PROPKA representation of bonds."""
+"""
+Bonds
+=====
+
+PROPKA representation of bonds.
+
+"""
 import math
 import json
 import pkg_resources

propka/calculations.py

@@ -1,8 +1,14 @@
-"""PROPKA calculations."""
+"""
+Calculations
+============
+
+Mathematical helper functions.
+"""
+
 import math
 
 
-# Maximum distance used to bound calculations of smallest distance
+#: Maximum distance used to bound calculations of smallest distance
 MAX_DISTANCE = 1e6
 
 

propka/conformation_container.py

@@ -1,4 +1,9 @@
-"""Container for molecular conformations"""
+"""
+Molecular data structures
+=========================
+
+Container data structure for molecular conformations.
+"""
 import functools
 import propka.ligand
 from propka.output import make_interaction_map
@@ -10,11 +15,12 @@ from propka.group import Group, is_group
 from propka.lib import info
 
 
-# A large number that gets multipled with the integer obtained from applying
+#: A large number that gets multipled with the integer obtained from applying
-# ord() to the atom chain ID.  Used in calculating atom keys for sorting.
+#: :func:`ord` to the atom chain ID.  Used in calculating atom keys for sorting.
 UNICODE_MULTIPLIER = 1e7
-# A number that gets mutiplied with an atom's residue number.  Used in
+
-# calculating keys for atom sorting.
+#: A number that gets mutiplied with an atom's residue number.  Used in
+#: calculating keys for atom sorting.
 RESIDUE_MULTIPLIER = 1000
 
 

propka/coupled_groups.py

@@ -1,4 +1,10 @@
-"""Describe coupling between groups."""
+"""
+Coupling between groups
+=======================
+
+Describe and analyze energetic coupling between groups.
+"""
+
 import itertools
 import propka.lib
 from propka.group import Group

propka/determinant.py

@@ -1,7 +1,18 @@
-"""Holds the Determinant class
+"""
+Determinant
+===========
+
+Provides the :class:`Determinant` class.
+
+.. TODO::
+
+   It is confusing to have both `determinant.py` and `determinants.py`.
+   Should these be merged?
+
+.. SeeAlso::
+   - :mod:`propka.determinants`
+   - :mod:`propka.iterative`
 
-TODO - it is confusing to have both `determinant.py` and `determinants.py`.
-Should these be merged?
 """
 
 

propka/determinants.py

@@ -1,7 +1,17 @@
-"""Functions to manipulate Determinant objects.
+"""
+Working with Determinants
+=========================
+
+Functions to manipulate :class:`propka.determinant.Determinant` objects.
+
+.. TODO::
+
+   It is confusing to have both `determinant.py` and `determinants.py`.
+   Should these be merged?
+
+.. SeeAlso::
+   :mod:`propka.determinant`
 
-TODO - it is confusing to have both `determinant.py` and `determinants.py`.
-Should these be merged?
 """
 import math
 import propka.iterative

propka/energy.py

@@ -1,4 +1,10 @@
-"""Energy calculations."""
+"""
+Energy calculations
+===================
+
+Energy calculations.
+
+"""
 import math
 from propka.lib import warning
 from propka.calculations import squared_distance, get_smallest_distance

propka/group.py

@@ -1,4 +1,9 @@
-"""Routines and classes for storing groups important to PROPKA calculations."""
+"""
+Data structures for groups
+==========================
+
+Routines and classes for storing groups important to PROPKA calculations.
+"""
 import math
 import propka.ligand
 import propka.protonate
@@ -10,6 +15,7 @@ from propka.lib import info, warning
 # Constants that start with "UNK_" are a mystery to me
 UNK_PKA_SCALING = -1.36
 PROTONATOR = propka.protonate.Protonate(verbose=False)
+#: acids
 EXPECTED_ATOMS_ACID_INTERACTIONS = {
     'COO': {'O': 2}, 'HIS': {'H': 2, 'N': 2}, 'CYS': {'S': 1}, 'TYR': {'O': 1},
     'LYS': {'N': 1}, 'ARG': {'H': 5, 'N': 3}, 'ROH': {'O': 1},
@@ -21,6 +27,7 @@ EXPECTED_ATOMS_ACID_INTERACTIONS = {
     'C2N': {'H': 4, 'N': 2}, 'OCO': {'O': 2}, 'N30': {'H': 4, 'N': 1},
     'N31': {'H': 3, 'N': 1}, 'N32': {'H': 2, 'N': 1}, 'N33': {'H': 1, 'N': 1},
     'NP1': {'H': 2, 'N': 1}, 'N1': {'N': 1}}
+#: bases
 EXPECTED_ATOMS_BASE_INTERACTIONS = {
     'COO': {'O': 2}, 'HIS': {'N': 2}, 'CYS': {'S': 1}, 'TYR': {'O': 1},
     'LYS': {'N': 1}, 'ARG': {'N': 3}, 'ROH': {'O': 1}, 'AMD': {'O': 1},

propka/hybrid36.py

@@ -1,6 +1,13 @@
-"""Provides alternative PDB format that can encode larger atom numbers.
+"""
+Hybrid36 PDB-like file format
+=============================
+
+`hybrid36`_ is an alternative PDB format that can encode larger atom
+numbers. This module provides the :func:`decode` functon to parse the
+atom numbers in hybrid36 "PDB" files.
+
+.. _hybrid36: http://cci.lbl.gov/hybrid_36/
 
-http://cci.lbl.gov/hybrid_36/
 """
 import string
 

propka/hydrogens.py

@@ -1,4 +1,10 @@
-"""Calculations related to hydrogen placement."""
+"""
+Hydrogens
+=========
+
+Calculations related to hydrogen placement.
+
+"""
 import math
 from propka.lib import info
 from propka.protonate import Protonate

propka/input.py

@@ -1,4 +1,9 @@
-"""Input routines."""
+"""
+Input handling
+==============
+
+Input routines.
+"""
 from pathlib import Path
 from pkg_resources import resource_filename
 from propka.lib import protein_precheck

propka/iterative.py

@@ -1,6 +1,10 @@
-"""Iterative functions for pKa calculations.
+"""
+Working with Determinants
+=========================
+
+Iterative functions for pKa calculations. These appear to mostly
+involve :class:`propka.determinant.Determinant` instances.
 
-These appear to mostly involve determinants.
 """
 from propka.determinant import Determinant
 from propka.lib import info, debug

propka/lib.py

@@ -1,4 +1,10 @@
-"""Implements many of the main functions used to call PROPKA."""
+"""
+Set-up of a PROPKA calculation
+==============================
+
+Implements many of the main functions used to call PROPKA.
+"""
+
 import sys
 import logging
 import argparse

propka/ligand.py

@@ -1,8 +1,17 @@
-"""Ligand classes and functions."""
+"""
+Ligand atom typing
+==================
+
+This module contains the :func:`assign_sybyl_type` function to analyze
+all :class:`propka.atom.Atom` in terms of SYBYL atom types (see
+:data:`ALL_SYBYL_TYPES`).
+
+"""
+
 from propka.calculations import squared_distance
 from propka.vector_algebra import Vector
 
-
+#: SYBYL atom types
 ALL_SYBYL_TYPES = [
     'C.3',   #  carbon sp3
     'H',     #  hydrogen
@@ -58,7 +67,7 @@ ALL_SYBYL_TYPES = [
     'Mo',    #  molybdenum
     'Sn']    #  tin
 
-
+#: PROPKA input types
 PROPKA_INPUT_TYPES = ['1P', '1N', '2P', '2N', 'C3', 'H', 'C2', 'Hsp', 'C1',
                       'Ht3', 'Car', 'LP', 'Cca', 'Du', 'N3', 'DuC', 'N2',
                       'Any', 'N1', 'Hal', 'Nar', 'Het', 'Nam', 'Hev', 'Npl',

propka/ligand_pka_values.py

@@ -1,4 +1,14 @@
-"""Ligand pKa values"""
+"""
+Ligand pKa values from Marvin
+=============================
+
+Ligand pKa values can be obtained from the commercial `Marvin`_
+software (namely, the :program:`cxcalc` and :program:`molconvert`
+programs are required).
+
+.. _Marvin: https://chemaxon.com/products/marvin
+
+"""
 import os
 import subprocess
 import sys

propka/molecular_container.py

@@ -1,4 +1,9 @@
-"""Molecular container for storing all contents of PDB files."""
+"""
+PDB molecular container
+=======================
+
+Molecular container for storing all contents of PDB files.
+"""
 import os
 import propka.version
 from propka.output import write_propka, write_pka, print_header, print_result

propka/output.py

@@ -1,4 +1,9 @@
-"""Output routines."""
+"""
+Output
+======
+
+Output routines.
+"""
 from datetime import date
 from propka.lib import info
 
@@ -408,11 +413,11 @@ Complexes.  Delphine C. Bas, David M. Rogers and Jan H. Jensen.  PROTEINS:
 Structure, Function, and Bioinformatics 73:765-783 (2008)
 
 PROPKA3: Consistent Treatment of Internal and Surface Residues in Empirical
-pKa predictions.  Mats H.M. Olsson, Chresten R. Sondergard, Michal Rostkowski, 
+pKa predictions.  Mats H.M. Olsson, Chresten R. Sondergard, Michal Rostkowski,
-and Jan H. Jensen.  Journal of Chemical Theory and Computation, 7(2):525-537 
+and Jan H. Jensen.  Journal of Chemical Theory and Computation, 7(2):525-537
 (2011)
 
-Improved Treatment of Ligands and Coupling Effects in Empirical Calculation 
+Improved Treatment of Ligands and Coupling Effects in Empirical Calculation
 and Rationalization of pKa Values.  Chresten R. Sondergaard, Mats H.M. Olsson,
 Michal Rostkowski, and Jan H. Jensen.  Journal of Chemical Theory and
 Computation, (2011)
@@ -441,8 +446,8 @@ def get_determinants_header():
     """
     str_ = """
 ---------  -----   ------   ---------------------    --------------    --------------    --------------
-                            DESOLVATION  EFFECTS       SIDECHAIN          BACKBONE        COULOMBIC    
+                            DESOLVATION  EFFECTS       SIDECHAIN          BACKBONE        COULOMBIC
- RESIDUE    pKa    BURIED     REGULAR      RE        HYDROGEN BOND     HYDROGEN BOND      INTERACTION  
+ RESIDUE    pKa    BURIED     REGULAR      RE        HYDROGEN BOND     HYDROGEN BOND      INTERACTION
 ---------  -----   ------   ---------   ---------    --------------    --------------    --------------
 """
     return str_

propka/parameters.py

@@ -1,21 +1,37 @@
-"""Holds parameters and settings."""
+"""
+Configuration file parameters
+=============================
+
+Holds parameters and settings that can be set in :file:`propka.cfg`. The file format consists of lines of  ``keyword value [value ...]``, blank lines, and comment lines (introduced with ``#``).
+
+The module attributes below list the names and types of all key words
+in configuration file.
+
+"""
 from propka.lib import info, warning
 
 
-# names and types of all key words in configuration file
+#: matrices
 MATRICES = ['interaction_matrix']
+#: pari-wise matrices
 PAIR_WISE_MATRICES = ['sidechain_cutoffs']
+#: :class:`dict` containing numbers
 NUMBER_DICTIONARIES = [
     'VanDerWaalsVolume', 'charge', 'model_pkas', 'ions', 'valence_electrons',
     'custom_model_pkas']
+#: :class:`dict` containing lists
 LIST_DICTIONARIES = ['backbone_NH_hydrogen_bond', 'backbone_CO_hydrogen_bond']
+#: :class:`dict` containing strings
 STRING_DICTIONARIES = ['protein_group_mapping']
+#: :class:`list` containing strings
 STRING_LISTS = [
     'ignore_residues', 'angular_dependent_sidechain_interactions',
     'acid_list', 'base_list', 'exclude_sidechain_interactions',
     'backbone_reorganisation_list', 'write_out_order']
+#: distances (:class:`float`)
 DISTANCES = ['desolv_cutoff', 'buried_cutoff', 'coulomb_cutoff1',
              'coulomb_cutoff2']
+#: other parameters
 PARAMETERS = [
     'Nmin', 'Nmax', 'desolvationSurfaceScalingFactor', 'desolvationPrefactor',
     'desolvationAllowance', 'coulomb_diel', 'COO_HIS_exception',
@@ -27,6 +43,7 @@ PARAMETERS = [
     'remove_penalised_group', 'max_intrinsic_pka_diff',
     'min_interaction_energy', 'max_free_energy_diff', 'min_swap_pka_shift',
     'min_pka', 'max_pka', 'sidechain_interaction']
+# :class:`str` parameters
 STRINGS = ['version', 'output_file_tag', 'ligand_typing', 'pH', 'reference']
 
 

propka/protonate.py

@@ -1,4 +1,12 @@
-"""Protonate a structure."""
+"""
+Protonate a structure
+=====================
+
+The :class:`Protonate` processes a
+:class:`propka.molecular_container.MolecularContainer` and adds
+protons.
+
+"""
 import math
 import propka.bonds
 import propka.atom

propka/run.py

@@ -1,4 +1,15 @@
-"""Entry point for PROPKA script."""
+"""
+Script functionality
+====================
+
+The :mod:`run` module provides a high-level interface to PROPKA 3.
+
+The :program:`propka3` script consists of the :func:`main`
+function. If similar functionality is desired from a Python script
+(without having to call the :program:`propka` script itself) then the
+:func:`single` function can be used instead.
+
+"""
 import logging
 from propka.lib import loadOptions
 from propka.input import read_parameter_file, read_molecule_file
@@ -30,11 +41,18 @@ def single(pdbfile, optargs=None):
 
     Commandline options can be passed as a **list** in *optargs*.
 
-    .. rubric:: Example
+    Example
+    -------
+    Given an input file "protein.pdb", run the equivalent of ``propka3
+    --mutation=N25R/N181D -v --pH=7.2 protein.pdb`` as::
+
+       propka.run.single("protein.pdb",
+                         optargs=["--mutation=N25R/N181D", "-v", "--pH=7.2"])
+
+
+    .. todo::
+       Test :func:`single`, not sure if it is correctly processing ``pdbfile``.
 
-    ::
-       single("protein.pdb", optargs=["--mutation=N25R/N181D", "-v",
-              "--pH=7.2"])
     """
     optargs = optargs if optargs is not None else []
     options = loadOptions(*optargs)

propka/vector_algebra.py

@@ -1,4 +1,9 @@
-"""Vector algebra for PROPKA."""
+"""
+Vector calculations
+===================
+
+Vector algebra for PROPKA.
+"""
 import math
 from propka.lib import info, get_sorted_configurations
 

propka/version.py

@@ -1,4 +1,8 @@
-"""Contains version-specific methods and parameters.
+"""
+Version-based configuration
+===========================
+
+Contains version-specific methods and parameters.
 
 TODO - this module unnecessarily confuses the code.  Can we eliminate it?
 """