Merge pull request #70 from Becksteinlab/sphinx-docs-skeleton

initial sphinx docs

.gitignore

@@ -5,3 +5,11 @@
 *.egg-info
 # Visual studio code
 .vscode
+
+# editor files
+*~
+
+# generated files
+docs/build
+docs/source/api/*.rst
+build/

docs/Makefile

@@ -0,0 +1,38 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile ghpages
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+# push to this repo's gh-pages (must be named origin and must have a gh-pages branch)
+
+REPONAME = origin
+
+ghpages: html
+	-(ORIGIN_REMOTE_URL=`git config --get remote.$(REPONAME).url`; \
+	rev=`git rev-parse --short HEAD`; \
+        cd $(BUILDDIR)/$^ \
+	&& git init \
+	&& git remote add origin $${ORIGIN_REMOTE_URL} \
+	&& git fetch --depth 50 origin gh-pages \
+	&& git reset origin/gh-pages \
+	&& touch .nojekyll \
+	&& git add -A . \
+        && git diff-index --quiet HEAD -- || git commit -m "updated sphinx docs from $${rev}" \
+	&& git push -q origin HEAD:gh-pages)
+	rm -rf $(BUILDDIR)/$^/.git

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/_templates/autosummary/module.rst

@@ -0,0 +1,61 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+   :members:
+   
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Module Attributes
+
+   .. autosummary::
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

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/command.rst

@@ -0,0 +1,131 @@
+.. -*- coding: utf-8 -*-
+
+.. _propka3-command:
+
+============================
+ :program:`propka3` command
+============================
+
+PROPKA predicts the pKa values of ionizable groups in proteins and
+protein-ligand complexes based in the 3D structure. The
+:program:`propka3` command has the following options::
+	   
+  propka3 [-h] [-f FILENAMES] [-r REFERENCE] [-c CHAINS] [-i TITRATE_ONLY] [-t THERMOPHILES] [-a ALIGNMENT] [-m MUTATIONS]
+         [-v VERSION_LABEL] [-p PARAMETERS] [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [-o PH] [-w WINDOW WINDOW WINDOW]
+         [-g GRID GRID GRID] [--mutator MUTATOR] [--mutator-option MUTATOR_OPTIONS] [-d] [-l] [-k] [-q] [--generate-propka-input]
+         [--protonate-all]
+         input_pdb
+
+
+.. program:: propka3
+	     
+.. option:: input_pdb
+
+            read data from file <input_pdb>
+
+.. option::   -h, --help
+
+	      show this help message and exit
+	      
+.. option::  -f FILENAMES, --file FILENAMES
+	     
+             read data from <filename>, i.e. <filename> is added to
+	     arguments (default: [])
+	     
+.. option::  -r REFERENCE, --reference REFERENCE
+	     
+             setting which reference to use for stability calculations
+	     [neutral/low-pH] (default: neutral)
+	     
+.. option::  -c CHAINS, --chain CHAINS
+	     
+             creating the protein with only a specified chain. Specify
+	     " " for chains without ID [all] (default: None)
+	     
+.. option::  -i TITRATE_ONLY, --titrate_only TITRATE_ONLY
+	     
+             Treat only the specified residues as titratable. Value
+	     should be a comma-separated list of "chain:resnum"
+	     values; for  example: ``-i "A:10,A:11"`` (default: None)
+	     
+.. option::  -t THERMOPHILES, --thermophile THERMOPHILES
+	     
+             defining a thermophile filename; usually used in
+	     'alignment-mutations' (default: None)
+	     
+.. option::  -a ALIGNMENT, --alignment ALIGNMENT
+	     
+             alignment file connecting <filename> and <thermophile>
+	     [<thermophile>.pir] (default: None)
+	     
+.. option::  -m MUTATIONS, --mutation MUTATIONS
+	     
+              specifying mutation labels which is used to modify
+	      <filename> according to, e.g. N25R/N181D (default: None)
+			
+.. option::  -v VERSION_LABEL, --version VERSION_LABEL
+	     
+             specifying the sub-version of propka [Jan15/Dec19]
+	     (default: Jan15)
+	     
+.. option::  -p PARAMETERS, --parameters PARAMETERS
+	     
+             set the parameter file (default:
+	     <installation_directory>/propka/propka/propka.cfg)
+	     
+.. option::  --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
+	     
+             logging level verbosity (default: INFO)
+	     
+.. option::  -o PH, --pH PH
+
+	     setting pH-value used in e.g. stability calculations
+	     (default: 7.0)
+	     
+.. option::  -w WINDOW WINDOW WINDOW, --window WINDOW WINDOW WINDOW
+	     
+             setting the pH-window to show e.g. stability profiles
+	     (default: (0.0, 14.0, 1.0)) 
+
+.. option:: -g GRID GRID GRID, --grid GRID GRID GRID
+	    
+            setting the pH-grid to calculate e.g. stability related
+	    properties (default: (0.0, 14.0, 0.1))
+	    
+.. option::  --mutator MUTATOR
+
+	     setting approach for mutating <filename>
+	     [alignment/scwrl/jackal] (default: None)
+	     
+.. option::  --mutator-option MUTATOR_OPTIONS
+	     
+             setting property for mutator [e.g. type="side-chain"]
+	     (default: None)
+	     
+.. option::  -d, --display-coupled-residues
+	     
+             Displays alternative pKa values due to coupling of
+	     titratable groups (default: False)
+	     
+.. option::  -l, --reuse-ligand-mol2-files
+	     
+             Reuses the ligand mol2 files allowing the user to alter
+	     ligand bond orders (default: False)
+	     
+.. option::  -k, --keep-protons
+
+	     Keep protons in input file (default: False)
+	     
+.. option::  -q, --quiet
+	     
+             suppress non-warning messages (default: None)
+	     
+.. option::  --generate-propka-input
+	     
+             Generate a PROPKA input file (default: False)
+	     
+.. option::  --protonate-all
+
+	     Protonate all atoms (will not influence pKa calculation)
+	     (default: False)
+	     

docs/source/conf.py

@@ -0,0 +1,75 @@
+# -*- coding: utf-8 -*-
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+
+# make sure sphinx always uses the current branch
+sys.path.insert(0, os.path.abspath('../..'))
+
+# https://sphinx-rtd-theme.readthedocs.io/en/stable/
+import sphinx_rtd_theme
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'PROPKA 3'
+copyright = '2020, Jan H. Jensen, Chresten R. Søndergaard, Mats H. M. Olsson, Michał Rostkowski, Nathan A. Baker, Matvey Adzhigirey, Oliver Beckstein, Jimmy Charnley Kromann, Mike Beachy, Toni G, Thomas Holder'
+author = 'Jan H. Jensen, Chresten R. Søndergaard, Mats H. M. Olsson, Michał Rostkowski, Nathan A. Baker, Matvey Adzhigirey, Oliver Beckstein, Jimmy Charnley Kromann, Mike Beachy, Toni G, Thomas Holder'
+
+# The full version, including alpha/beta/rc tags
+release = '3.2.0'
+
+
+# -- General configuration ---------------------------------------------------
+
+# 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', 'sphinx.ext.intersphinx',
+              'sphinx.ext.mathjax', 'sphinx.ext.viewcode',
+              'sphinx.ext.napoleon', 'sphinx.ext.todo',
+              'sphinx.ext.autosummary',
+##              'sphinx_sitemap',
+              'sphinx_rtd_theme']
+
+mathjax_path = 'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML'
+
+# for sitemap with https://github.com/jdillard/sphinx-sitemap
+# change if we put it under a custom domain; for right now, assume RTD
+##site_url = "https://propka.readthedocs.io"
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+# https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html
+# We use a customized _templates/autosummary/module.rst to document members, too.
+autosummary_generate = True
+autosummary_imported_members = False
+autosummary_generate_overwrite = True
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']

docs/source/index.rst

@@ -0,0 +1,91 @@
+.. -*- coding: utf-8 -*-
+.. PROPKA 3 documentation master file, created by
+   sphinx-quickstart on Fri Jun 19 11:12:18 2020.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+.. |pKa| replace:: :math:`\text{p}K_\text{a}`
+
+====================================
+PROPKA 3: Heuristic |pKa| prediction
+====================================
+
+:Release: |release|
+:Date: |today|
+
+
+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 :ref:`propka3 command <propka3-command>` and
+the :mod:`propka` Python package.
+
+   
+License and source code
+=======================
+
+PROPKA 3 is released under the `GNU Lesser General Public License v2.1`_ (see the
+files *LICENSE* in the repository for details).
+
+Source code is available in the public GitHub repository
+https://github.com/jensengroup/propka.
+
+
+   
+Getting help
+============
+
+Please report *bugs and feature requests* for PROPKA through the
+`Issue Tracker`_.
+
+
+
+Contributing
+============
+
+PROPKA welcomes new contributions. To contribute code, submit a *pull
+request* against the master branch in the `propka repository`_.
+
+
+Citation
+========
+
+If you use PROPKA 3 in published work please cite [Sondergaard2011]_ and [Olsson2011]_.
+
+
+   
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+.. links
+
+.. _`GNU Lesser General Public License v2.1`:
+   https://www.gnu.org/licenses/old-licenses/lgpl-2.1.en.html   
+.. _propka repository: https://github.com/jensengroup/propka   
+.. _issue tracker: https://github.com/jensengroup/propka/issues
+   
+
+.. Hide the contents from the front page because they are already in
+.. the side bar in the rtd sphinx style
+
+.. Contents
+.. ========
+
+   
+.. toctree::
+   :maxdepth: 3
+   :numbered:
+   :hidden:      
+
+   installation
+   quickstart
+   command
+   api
+   references
+
+  

docs/source/installation.rst

@@ -0,0 +1,52 @@
+.. -*- coding: utf-8 -*-
+
+==============
+ Installation
+==============
+
+
+PROPKA 3 requires Python 3.6 or higher. Additional requirements are
+specified in the :file:`requirements.txt` file and automatically satisfied
+when installing with pip_.
+
+
+``pip``-based installation
+==========================
+
+The easiest way to install a release of PROPKA 3 is from the `PyPI archive`_ with the command
+
+.. code-block:: bash
+
+   pip install --upgrade propka
+
+   
+This installation will install the :mod:`propka` Python module and the
+:program:`propka3` executable script. As always, a virtual environment (e.g., via
+`virtualenv`_) is recommended when installing packages.
+
+Source-based installation
+=========================
+
+The source code can be installed by cloning the `repository`_ or
+unpacking from a source code archive and running
+
+.. code-block:: bash
+
+   pip install .
+
+in the source directory.
+
+For the purposes of testing or development, you may prefer to install
+PROPKA as an editable module via pip_ by running
+
+.. code-block:: bash
+
+   pip install -e .
+
+in the source directory.
+
+
+.. _pip: https://pip.pypa.io/
+.. _PyPI archive: https://pypi.org/project/PROPKA/
+.. _virtualenv: https://pypi.org/project/virtualenv/
+.. _repository: https://github.com/jensengroup/propka

docs/source/quickstart.rst

@@ -0,0 +1,194 @@
+.. -*- coding: utf-8 -*-
+
+
+
+.. |pKa| replace:: :math:`\text{p}K_\text{a}`
+
+==================
+ Quickstart Guide
+==================
+
+PROPKA can be used either via the installed script :program:`propka3`
+or as a Python module. When using the :ref:`propka3-command`, use
+
+.. code-block:: bash
+
+   propka3  FILENAME
+
+As a module (:mod:`propka`), also provide the input filename
+
+.. code-block:: bash
+		
+   python -m propka FILENAME
+
+In both cases, additional options may be added, as described in more
+detail for the :ref:`propka3-command`.
+
+
+Predicting protein residue |pKa| values
+=======================================
+
+Most users run PROPKA by invoking the :program:`propka3` program with
+a PDB file as its argument; e.g., for PDB 1HPX_ (HIV-1 protease
+complexed with the inhibitor KNI-272)
+
+.. code-block:: bash
+
+   propka3 1hpx.pdb
+
+In this example, |pKa| values of titratable protein residues and
+titratable groups of the inhibitor KNI are calculated.
+   
+The output looks similar to the following (many lines omitted as
+"..."). It is also contained in the output file :file:`1hpx.pka` that
+is automatically written::
+
+
+   propka3.2                                                                                    2020-06-19
+   ...
+   ...
+   Found NAR group:  1530-  N1   900-KNI (B) [   7.907    1.459    5.427] N
+   Found O3  group:  1531-  O1   900-KNI (B) [   5.235    3.791    9.082] O
+   Found O2  group:  1532-  O3   900-KNI (B) [   3.327    4.297   11.852] O
+   Found NAM group:  1533-  N2   900-KNI (B) [   3.955    2.384   10.893] N
+   Found O2  group:  1539-  O6   900-KNI (B) [   3.758   -0.629   12.111] O
+   Found NAM group:  1541-  N3   900-KNI (B) [   4.496    0.982   13.492] N
+   Found O2  group:  1542-  O4   900-KNI (B) [   6.324   -1.234   17.045] O
+   Found OH  group:  1548-  O2   900-KNI (B) [   4.949    0.934   16.427] O
+   Found O2  group:  1559-  O5   900-KNI (B) [   6.746   -3.574   14.588] O
+   Found NAM group:  1560-  N5   900-KNI (B) [   7.637   -4.575   16.403] N
+   -------------------------------------------------------------------------------------------------------
+
+
+   Calculating pKas for Conformation container 1A with 1878 atoms and 480 groups
+   -------------------------------------------------------------------------------------------------------
+
+   ---------  -----   ------   ---------------------    --------------    --------------    --------------
+			       DESOLVATION  EFFECTS       SIDECHAIN          BACKBONE        COULOMBIC    
+    RESIDUE    pKa    BURIED     REGULAR      RE        HYDROGEN BOND     HYDROGEN BOND      INTERACTION  
+   ---------  -----   ------   ---------   ---------    --------------    --------------    --------------
+
+   ASP  25 A   5.07*  100 %    4.30  617   0.19    0   -0.85 KNI  O4 B   -0.63 GLY  27 A    0.07 ASP  29 A
+   ASP  25 A                                           -0.85 KNI  O2 B   -0.09 ALA  28 A    0.00 XXX   0 X
+   ASP  25 A                                           -0.84 ASP  25 B   -0.04 GLY  27 B    0.00 XXX   0 X
+
+   ASP  29 A   3.11    50 %    1.20  420   0.13    0   -0.68 ARG  87 A    0.00 XXX   0 X   -0.04 LYS  45 A
+   ASP  29 A                                           -0.28 ARG   8 B    0.00 XXX   0 X   -0.47 ARG  87 A
+   ASP  29 A                                            0.00 XXX   0 X    0.00 XXX   0 X   -0.54 ARG   8 B
+
+   ASP  30 A   4.62    59 %    1.30  446   0.00    0   -0.11 LYS  45 A    0.00 XXX   0 X   -0.07 ARG  87 A
+   ASP  30 A                                            0.00 XXX   0 X    0.00 XXX   0 X   -0.01 ARG   8 B
+   ASP  30 A                                            0.00 XXX   0 X    0.00 XXX   0 X    0.29 ASP  29 A
+   ASP  30 A                                            0.00 XXX   0 X    0.00 XXX   0 X   -0.57 LYS  45 A
+
+   ASP  60 A   2.55     0 %    0.41  249   0.00    0   -0.40 THR  74 A    0.00 XXX   0 X   -0.02 LYS  45 A
+   ASP  60 A                                           -0.85 LYS  43 A    0.00 XXX   0 X   -0.38 LYS  43 A
+   ...
+   ...
+   ...
+   ARG  87 B  12.28    45 %   -1.40  407   0.00    0    0.77 ASP  29 B    0.00 XXX   0 X    0.10 ASP  30 B
+   ARG  87 B                                            0.00 XXX   0 X    0.00 XXX   0 X   -0.19 ARG   8 A
+   ARG  87 B                                            0.00 XXX   0 X    0.00 XXX   0 X    0.50 ASP  29 B
+
+   N+    1 B   8.96     0 %   -0.39  235   0.00    0    0.85 C-   99 A    0.00 XXX   0 X    0.07 CYS  67 B
+   N+    1 B                                            0.00 XXX   0 X    0.00 XXX   0 X    0.04 CYS  95 B
+   N+    1 B                                            0.00 XXX   0 X    0.00 XXX   0 X    0.38 C-   99 A
+
+   KNI  N1 B   4.60     0 %   -0.36  273   0.00    0    0.00 XXX   0 X    0.00 XXX   0 X   -0.03 ARG   8 A
+
+   Coupled residues (marked *) were detected.Please rerun PropKa with the --display-coupled-residues 
+   or -d option for detailed information.
+
+   --------------------------------------------------------------------------------------------------------
+   SUMMARY OF THIS PREDICTION
+	  Group      pKa  model-pKa   ligand atom-type
+      ASP  25 A     5.07       3.80                      
+      ASP  29 A     3.11       3.80                      
+      ASP  30 A     4.62       3.80                      
+      ASP  60 A     2.55       3.80                      
+      ASP  25 B     9.28       3.80                      
+      ASP  29 B     1.78       3.80                      
+      ASP  30 B     4.91       3.80                      
+      ASP  60 B     2.13       3.80                      
+      GLU  21 A     4.78       4.50                      
+      GLU  34 A     3.93       4.50                      
+      GLU  35 A     3.65       4.50                      
+      GLU  65 A     3.89       4.50                      
+      GLU  21 B     4.73       4.50                      
+      GLU  34 B     3.36       4.50                      
+      GLU  35 B     4.07       4.50                      
+      GLU  65 B     3.70       4.50                      
+      C-   99 A     2.08       3.20                      
+      C-   99 B     2.11       3.20                      
+      HIS  69 A     6.98       6.50                      
+      HIS  69 B     7.11       6.50                      
+      CYS  67 A     9.41       9.00                      
+      CYS  95 A    11.68       9.00                      
+      CYS  67 B     9.82       9.00                      
+      CYS  95 B    11.61       9.00                      
+      TYR  59 A     9.67      10.00                      
+      TYR  59 B     9.54      10.00                      
+      LYS  14 A    10.43      10.50                      
+      LYS  20 A    10.32      10.50                      
+      LYS  43 A    11.41      10.50                      
+      LYS  45 A    10.54      10.50                      
+      LYS  55 A    10.42      10.50                      
+      LYS  70 A    10.92      10.50                      
+      LYS  14 B    10.55      10.50                      
+      LYS  20 B    11.01      10.50                      
+      LYS  43 B    11.43      10.50                      
+      LYS  45 B    10.47      10.50                      
+      LYS  55 B    10.41      10.50                      
+      LYS  70 B    11.07      10.50                      
+      ARG   8 A    13.96      12.50                      
+      ARG  41 A    12.41      12.50                      
+      ARG  57 A    14.40      12.50                      
+      ARG  87 A    12.35      12.50                      
+      ARG   8 B    12.76      12.50                      
+      ARG  41 B    12.42      12.50                      
+      ARG  57 B    13.73      12.50                      
+      ARG  87 B    12.28      12.50                      
+      N+    1 A     8.96       8.00                      
+      N+    1 B     8.96       8.00                      
+      KNI  N1 B     4.60       5.00                NAR   
+
+   Writing 1hpx.pka
+
+
+
+Some of the important contents:
+
+- The section *Calculating pKas for Conformation container 1A with 1878 atoms and
+  480 groups* lists details on the calculations for all ionizable
+  residues. It indicates the considerations that went into a |pKa|
+  estimate such as hydrogen bonds and Coulomb interactions. It also
+  indicates if there is potentially coupling between residues.
+- Values with "XXX" placeholders are not calculated (but appear to
+  maintain the formatting).
+- The section *SUMMARY OF THIS PREDICTION* lists the predicted |pKa|
+  for each residue together with the model |pKa| (the "default"
+  value).
+- Ligand values are labeled with the residue name of the ligand, in
+  this case "KNI".  
+
+
+.. todo::
+
+   More detailed discussion of output.
+  
+
+
+Getting help
+============
+
+A brief list of available options can be obtained by running PROPKA
+with no options. A longer list of options and descriptions is
+available using the :option:`propka3 --help` option:
+
+.. code-block:: bash
+
+   propka3 --help
+
+   
+.. links
+.. _1HPX: https://www.rcsb.org/structure/1HPX   

docs/source/references.rst

@@ -0,0 +1,23 @@
+.. -*- coding: utf-8 -*-
+
+============
+ References
+============
+
+.. [Sondergaard2011] C. R. Søndergaard, M. H. M. Olsson, M. Rostkowski,
+                     and J. H. Jensen. Improved treatment of ligands
+                     and coupling effects in empirical calculation and
+                     rationalization of pKa values. *Journal of
+                     Chemical Theory and Computation*,
+                     7(7):2284–2295, 2011.
+		     doi: `10.1021/ct200133y <https://doi.org/10.1021/ct200133y>`_
+
+
+.. [Olsson2011] M. H. M. Olsson, C. R. Søndergaard, M. Rostkowski,
+                and J. H. Jensen. PROPKA3: Consistent treat- ment of
+                internal and surface residues in empirical pKa
+                predictions. *Journal of Chemical Theory and
+                Computation*, 7(2):525–537, 2011.
+		doi:
+		`10.1021/ct100578z <https://doi.org/10.1021/ct100578z>`_
+		

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
-# ord() to the atom chain ID.  Used in calculating atom keys for sorting.
+#: A large number that gets multipled with the integer obtained from applying
+#: :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
 

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

requirements.txt

@@ -1,2 +1,4 @@
 pytest
 numpy
+sphinx
+sphinx_rtd_theme