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)
This commit is contained in:
Oliver Beckstein
20
docs/Makefile
Normal file
20
docs/Makefile
Normal file
@@ -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)
|
||||
35
docs/make.bat
Normal file
35
docs/make.bat
Normal file
@@ -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
|
||||
69
docs/source/conf.py
Normal file
69
docs/source/conf.py
Normal file
@@ -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']
|
||||
86
docs/source/index.rst
Normal file
86
docs/source/index.rst
Normal file
@@ -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
|
||||
|
||||
|
||||
52
docs/source/installation.rst
Normal file
52
docs/source/installation.rst
Normal file
@@ -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
|
||||
192
docs/source/quickstart.rst
Normal file
192
docs/source/quickstart.rst
Normal file
@@ -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
|
||||
23
docs/source/references.rst
Normal file
23
docs/source/references.rst
Normal file
@@ -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>`_
|
||||
|
||||
Reference in New Issue
Block a user