From 2bf031fd65aebe6e794f3e66232ca292fee111d1 Mon Sep 17 00:00:00 2001 From: Oliver Beckstein Date: Fri, 19 Jun 2020 12:13:53 -0700 Subject: [PATCH] initial sphinx docs starts #69 - basic structure - RTD theme - installation - quickstart (more to do) - references - added start page with license and links to repo and issues - authors in docs: papers and repo contributors (to be discussed) --- docs/Makefile | 20 ++++ docs/make.bat | 35 +++++++ docs/source/conf.py | 69 +++++++++++++ docs/source/index.rst | 86 ++++++++++++++++ docs/source/installation.rst | 52 ++++++++++ docs/source/quickstart.rst | 192 +++++++++++++++++++++++++++++++++++ docs/source/references.rst | 23 +++++ 7 files changed, 477 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst create mode 100644 docs/source/installation.rst create mode 100644 docs/source/quickstart.rst create mode 100644 docs/source/references.rst diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# 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 + +# 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) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..6247f7e --- /dev/null +++ b/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 diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..70c3e06 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,69 @@ +# -*- 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_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 = [] + + +# -- 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'] diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..5000820 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,86 @@ +.. -*- 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]_. + + +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 + references + + diff --git a/docs/source/installation.rst b/docs/source/installation.rst new file mode 100644 index 0000000..dac0ab2 --- /dev/null +++ b/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 +:command:`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 diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst new file mode 100644 index 0000000..709e205 --- /dev/null +++ b/docs/source/quickstart.rst @@ -0,0 +1,192 @@ +.. -*- coding: utf-8 -*- + + + +.. |pKa| replace:: :math:`\text{p}K_\text{a}` + +================== + Quickstart Guide +================== + +PROPKA can be used either as a module or via the installed script :command:`propka3`; i.e., either + +.. code-block:: bash + + propka3 + +or :mod:`propka` + +.. code-block:: bash + + python -m propka + +works for invoking PROPKA. + + +Predicting protein residue |pKa| values +======================================= + +Most users run PROPKA by invoking the 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:`--help` option: + +.. code-block:: bash + + propka3 --help + + +.. links +.. _1HPX: https://www.rcsb.org/structure/1HPX diff --git a/docs/source/references.rst b/docs/source/references.rst new file mode 100644 index 0000000..409795a --- /dev/null +++ b/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 `_ + + +.. [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 `_ +