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
+===========
 
-TODO - it is confusing to have both `determinant.py` and `determinants.py`.
+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`
+
 """
 
 

propka/determinants.py

@@ -1,7 +1,17 @@
-"""Functions to manipulate Determinant objects.
+"""
+Working with Determinants
+=========================
 
-TODO - it is confusing to have both `determinant.py` and `determinants.py`.
+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`
+
 """
 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
 

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?
 """