Add Sphinx configuration files to build the project documentation

README.md

@@ -12,6 +12,7 @@
 [![Source](https://img.shields.io/badge/source-GitHub-303030.svg?maxAge=2678400&style=flat-square)](https://github.com/althonos/peptides.py/)
 [![Mirror](https://img.shields.io/badge/mirror-EMBL-009f4d?style=flat-square&maxAge=2678400)](https://git.embl.de/larralde/peptides.py/)
 [![GitHub issues](https://img.shields.io/github/issues/althonos/peptides.py.svg?style=flat-square&maxAge=600)](https://github.com/althonos/peptides.py/issues)
+[![Docs](https://img.shields.io/readthedocs/peptides/latest?style=flat-square&maxAge=600)](https://peptides.readthedocs.io)
 [![Changelog](https://img.shields.io/badge/keep%20a-changelog-8A0707.svg?maxAge=2678400&style=flat-square)](https://github.com/althonos/peptides.py/blob/master/CHANGELOG.md)
 [![Downloads](https://img.shields.io/badge/dynamic/json?style=flat-square&color=303f9f&maxAge=86400&label=downloads&query=%24.total_downloads&url=https%3A%2F%2Fapi.pepy.tech%2Fapi%2Fprojects%2Fpeptides)](https://pepy.tech/project/peptides)
 
@@ -102,7 +103,7 @@ This library is provided under the [GNU General Public License v3.0](https://cho
 The original R `Peptides` package was written by [Daniel Osorio](https://orcid.org/0000-0003-4424-8422),
 [Paola Rondón-Villarreal](https://orcid.org/0000-0001-8209-3885) and
 [Rodrigo Torres](https://orcid.org/0000-0003-1113-3020), and is licensed under
-the terms of the GPLv2.
+the terms of the [GNU General Public License v2.0](https://choosealicense.com/licenses/gpl-2.0/).
 
 *This project is in no way not affiliated, sponsored, or otherwise endorsed
 by the [original `Peptides` authors](https://github.com/dosorio). It was developed

docs/Makefile

+# 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     = .
+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)

docs/_static/css/main.css

+p {
+    text-align: justify;
+}
+
+/* a.reference strong {
+    font-weight: bold;
+    font-size: 90%;
+    color: #c7254e;
+    box-sizing: border-box;
+    font-family: Menlo,Monaco,Consolas,"Courier New",monospace;
+} */
+
+.field-list a.reference {
+    font-weight: bold;
+    font-size: 90%;
+    color: #c7254e;
+    box-sizing: border-box;
+    font-family: Menlo,Monaco,Consolas,"Courier New",monospace;
+}
+
+.class dd {
+    margin-left: 2%
+}
+
+.exception dd {
+    margin-left: 2%
+}

docs/api.rst

+API Reference
+=============
+
+.. autoclass:: peptides.Peptide
+   :special-members: __init__
+   :members:

docs/changes.md

+../CHANGELOG.md
\ No newline at end of file

docs/conf.py

+# 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
+
+# -- Imports -----------------------------------------------------------------
+
+import configparser
+import datetime
+import os
+import sys
+import re
+import shutil
+import semantic_version
+import sphinx_bootstrap_theme
+
+# -- 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.
+
+docssrc_dir = os.path.dirname(os.path.abspath(__file__))
+project_dir = os.path.dirname(docssrc_dir)
+sys.path.insert(0, project_dir)
+
+
+# -- Sphinx Setup ------------------------------------------------------------
+
+def setup(app):
+    # Add custom stylesheet
+    app.add_css_file("css/main.css")
+    # app.add_js_file("js/apitoc.js")
+    # app.add_js_file("js/example-admonition.js")
+
+
+# -- Project information -----------------------------------------------------
+
+import peptides
+
+# extract the project metadata from the module itself
+project = peptides.__name__
+author = re.match('(.*) <.*>', peptides.__author__).group(1)
+year = datetime.date.today().year
+copyright = '{}, {}'.format("2021" if year==2021 else "2021-{}".format(year), author)
+
+# extract the semantic version
+semver = semantic_version.Version.coerce(peptides.__version__)
+version = str(semver.truncate(level="patch"))
+release = str(semver)
+
+# extract the project URLs from ``setup.cfg``
+cfgparser = configparser.ConfigParser()
+cfgparser.read(os.path.join(project_dir, "setup.cfg"))
+project_urls = dict(
+    map(str.strip, line.split(" = ", 1))
+    for line in cfgparser.get("metadata", "project_urls").splitlines()
+    if line.strip()
+)
+
+# patch the docstring of the main module so that we don't show the link to
+# redirect to the docs (we don't want to see it when reading the docs
+# already, duh!)
+doc_lines = peptides.__doc__.splitlines()
+if "See Also:" in doc_lines:
+    see_also = peptides.index("See Also:")
+    peptides.__doc__ = "\n".join(doc_lines[:see_also])
+
+
+# -- 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.autosummary",
+    "sphinx.ext.intersphinx",
+    # "sphinx.ext.imgconverter",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.coverage",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.todo",
+    "sphinx_bootstrap_theme",
+    "recommonmark",
+]
+
+# 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 = ['_build', 'Thumbs.db', '.DS_Store', 'requirements.txt']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = "monokailight"
+
+# The name of the default role for inline references
+default_role = "py:obj"
+
+
+# -- 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 = 'bootstrap'
+
+# Add any paths that contain custom themes here, relative to this directory.
+html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
+
+# 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']
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+html_theme_options = {
+    # Bootswatch (http://bootswatch.com/) theme.
+    "bootswatch_theme": "flatly",
+    # Choose Bootstrap version.
+    "bootstrap_version": "3",
+    # Tab name for entire site. (Default: "Site")
+    "navbar_site_name": "Documentation",
+    # HTML navbar class (Default: "navbar") to attach to <div> element.
+    # For black navbar, do "navbar navbar-inverse"
+    "navbar_class": "navbar",
+    # Render the next and previous page links in navbar. (Default: true)
+    "navbar_sidebarrel": True,
+    # Render the current pages TOC in the navbar. (Default: true)
+    "navbar_pagenav": False,
+    # A list of tuples containing pages or urls to link to.
+    "navbar_links": [
+        ("GitHub", cfgparser.get("metadata", "url").strip(), True)
+    ] + [
+        (k, v, True)
+        for k, v in project_urls.items()
+        if k in {"Zenodo", "PyPI"}
+    ],
+    "admonition_use_panel": True,
+}
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+html_sidebars = {
+    "*": ["localtoc.html"],
+    "api/*": ["localtoc.html"],
+    "examples/*": ["localtoc.html"],
+}
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = peptides.__name__
+
+
+# -- Extension configuration -------------------------------------------------
+
+# -- Options for imgmath extension -------------------------------------------
+
+imgmath_image_format = "svg"
+
+# -- Options for napoleon extension ------------------------------------------
+
+napoleon_include_init_with_doc = True
+napoleon_include_special_with_doc = True
+napoleon_include_private_with_doc = True
+napoleon_use_admonition_for_examples = True
+napoleon_use_admonition_for_notes = True
+napoleon_use_admonition_for_references = True
+napoleon_use_rtype = False
+
+# -- Options for autodoc extension -------------------------------------------
+
+autoclass_content = "class"
+autodoc_member_order = 'groupwise'
+autosummary_generate = []
+
+# -- Options for intersphinx extension ---------------------------------------
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+    "biopython": ("https://biopython.org/docs/latest/api/", None),
+}
+
+# -- Options for recommonmark extension --------------------------------------
+
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.txt': 'markdown',
+    '.md': 'markdown',
+}

docs/contributing.md

+../CONTRIBUTING.md
\ No newline at end of file

docs/index.rst

+.. peptides documentation master file, created by
+   sphinx-quickstart on Sat Oct 23 18:17:35 2021.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+`peptides.py` |stars|
+=====================
+
+.. |Stars| image:: https://img.shields.io/github/stars/althonos/peptides.py.svg?style=social&maxAge=3600&label=Star
+   :target: https://github.com/althonos/peptides.py/stargazers
+
+*Physicochemical properties and indices for amino-acid sequences.*
+
+|Actions| |Coverage| |PyPI| |Wheel| |Versions| |Implementations| |License| |Source| |Mirror| |Issues| |Docs| |Changelog| |Downloads|
+
+.. |Actions| image:: https://img.shields.io/github/workflow/status/althonos/peptides.py/Test/main?logo=github&style=flat-square&maxAge=300
+   :target: https://github.com/althonos/peptides.py/actions
+
+.. |Coverage| image:: https://img.shields.io/codecov/c/gh/althonos/peptides.py?style=flat-square&maxAge=600
+   :target: https://codecov.io/gh/althonos/peptides.py/
+
+.. |PyPI| image:: https://img.shields.io/pypi/v/peptides.svg?style=flat-square&maxAge=3600
+   :target: https://pypi.python.org/pypi/peptides
+
+.. |Wheel| image:: https://img.shields.io/pypi/wheel/peptides?style=flat-square&maxAge=3600
+   :target: https://pypi.org/project/peptides.py/#files
+
+.. |Versions| image:: https://img.shields.io/pypi/pyversions/peptides.svg?style=flat-square&maxAge=3600
+   :target: https://pypi.org/project/peptides.py/#files
+
+.. |Implementations| image:: https://img.shields.io/badge/impl-universal-success.svg?style=flat-square&maxAge=3600&label=impl
+   :target: https://pypi.org/project/peptides.py/#files
+
+.. |License| image:: https://img.shields.io/badge/license-GPLv3-blue.svg?style=flat-square&maxAge=3600
+   :target: https://choosealicense.com/licenses/gpl-3.0/
+
+.. |Source| image:: https://img.shields.io/badge/source-GitHub-303030.svg?maxAge=2678400&style=flat-square
+   :target: https://github.com/althonos/peptides.py/
+
+.. |Mirror| image:: https://img.shields.io/badge/mirror-EMBL-009f4d?style=flat-square&maxAge=2678400
+   :target: https://git.embl.de/larralde/peptides.py/
+
+.. |Issues| image:: https://img.shields.io/github/issues/althonos/peptides.py.svg?style=flat-square&maxAge=600
+   :target: https://github.com/althonos/peptides.py/issues
+
+.. |Docs| image:: https://img.shields.io/readthedocs/peptides?style=flat-square&maxAge=3600
+   :target: http://peptides.readthedocs.io/en/stable/?badge=stable
+
+.. |Changelog| image:: https://img.shields.io/badge/keep%20a-changelog-8A0707.svg?maxAge=2678400&style=flat-square
+   :target: https://github.com/althonos/peptides.py/blob/main/CHANGELOG.md
+
+.. |Downloads| image:: https://img.shields.io/badge/dynamic/json?style=flat-square&color=303f9f&maxAge=86400&label=downloads&query=%24.total_downloads&url=https%3A%2F%2Fapi.pepy.tech%2Fapi%2Fprojects%2Fpeptides
+   :target: https://pepy.tech/project/peptides
+
+
+Overview
+--------
+
+``peptides.py`` is a pure-Python package to compute common descriptors for
+protein sequences. It is a port of `Peptides <https://cran.r-project.org/web/packages/Peptides/index.html>`_,
+the R package written by `Daniel Osorio <https://orcid.org/0000-0003-4424-8422>`_
+for the same purpose. This library has no external dependency and is
+available for all modern Python versions (3.6+).
+
+A non-exhaustive list of available features:
+
+- Amino-acid Statistics:
+
+  - Number of occurrences in the peptide sequence
+  - Frequency in the peptide sequence
+
+- `QSAR <https://en.wikipedia.org/wiki/Quantitative_structure%E2%80%93activity_relationship>`_ descriptors:
+
+  - `BLOSUM indices <https://doi.org/10.1089/cmb.2008.0173>`_
+  - `Cruciani properties <https://doi.org/10.1002/cem.856>`_
+  - `FASGAI vectors <https://doi.org/10.1111/j.1747-0285.2008.00641.x>`_
+  - `Kidera factors <https://doi.org/10.1007/BF01025492>`_
+  - `MS-WHIM scores <https://doi.org/10.1021/ci980211b>`_
+  - `ProtFP descriptors <https://doi.org/10.1186/1758-2946-5-41>`_
+  - `ST-scales <https://doi.org/10.1007/s00726-009-0287-y>`_
+  - `T-scales <https://doi.org/10.1016/j.molstruc.2006.07.004>`_
+  - `VHSE-scales <https://doi.org/10.1002/bip.20296>`_
+  - `Z-scales <https://doi.org/10.1021/jm9700575>`_
+
+- Sequence profiles:
+
+  - Hydrophobicity profile using one of 38 proposed scales.
+  - Hydrophobic moment profile based on `Eisenberg, Weiss and Terwilliger (1984) <https://doi.org/10.1073/pnas.81.1.140>`_.
+  - Membrane position based on `Eisenberg (1984) <https://doi.org/10.1146/annurev.bi.53.070184.003115>`_.
+
+- Physico-chemical properties:
+
+  - Aliphatic index proposed in `Ikai (1980) <https://pubmed.ncbi.nlm.nih.gov/7462208/>`_.
+  - Instability index proposed in `Boman (2003) <https://doi.org/10.1046/j.1365-2796.2003.01228.x>`_.
+  - Theoretical net charge based on the `Henderson-Hasselbach equation <https://en.wikipedia.org/wiki/Henderson%E2%80%93Hasselbalch_equation>`_.
+  - Isoelectric point using one of 8 pKa scales.
+  - Molecular weight, taking into account isotope labelling, using one of 3 average weight tables.
+
+
+Setup
+-----
+
+Run ``pip install peptides`` in a shell to download the latest release, or have
+a look at the :doc:`Installation page <install>` to find other ways to install
+``peptides.py``.
+
+
+Library
+-------
+
+.. toctree::
+  :maxdepth: 2
+
+  Installation <install>
+  Contributing <contributing>
+  API Reference <api>
+  Changelog <changes>
+
+
+License
+-------
+
+This library is provided under the `GNU General Public License v3.0 <https://choosealicense.com/licenses/gpl-3.0/>`_.
+The original R `Peptides` package was written by `Daniel Osorio <https://orcid.org/0000-0003-4424-8422>`_,
+`Paola Rondón-Villarreal <https://orcid.org/0000-0001-8209-3885>`_ and
+`Rodrigo Torres <https://orcid.org/0000-0003-1113-3020>`_, and is licensed under
+the terms of the `GPLv2 <https://choosealicense.com/licenses/gpl-2.0/>`_.
+
+*This project is in no way not affiliated, sponsored, or otherwise endorsed
+by the original* `Peptides`_ *authors. It was developed by*
+`Martin Larralde <https://github.com/althonos>`_ *during his
+PhD project at the* `European Molecular Biology Laboratory <https://www.embl.de/>`_
+*in the* `Zeller team <https://github.com/zellerlab>`_.

docs/install.rst

+Installation
+============
+
+PyPi
+^^^^
+
+``peptides.py`` is hosted on GitHub, but the easiest way to install it is to
+download the latest release from its `PyPi repository <https://pypi.python.org/pypi/pyrodigal>`_.
+
+.. code:: console
+
+	$ pip install --user pyrodigal
+
+.. Conda
+.. ^^^^^
+..
+.. Pronto is also available as a `recipe <https://anaconda.org/bioconda/pyrodigal>`_
+.. in the `bioconda <https://bioconda.github.io/>`_ channel. To install, simply
+.. use the ``conda`` installer:
+..
+.. .. code:: console
+..
+.. 	 $ conda install -c bioconda pyrodigal
+
+
+GitHub + ``pip``
+^^^^^^^^^^^^^^^^
+
+If, for any reason, you prefer to download the library from GitHub, you can clone
+the repository and install the repository by running (with the admin rights):
+
+.. code:: console
+
+  $ git clone --recursive https://github.com/althonos/peptides.py
+	$ pip install --user ./peptides.py
+
+.. caution::
+
+    Keep in mind this will install always try to install the latest commit,
+    which may not even build, so consider using a versioned release instead.
+
+
+GitHub + ``setuptools``
+^^^^^^^^^^^^^^^^^^^^^^^
+
+If you do not want to use ``pip``, you can still clone the repository and
+run the ``setup.py`` file manually, although you will need to install the
+build dependencies (mainly `astor <https://pypi.org/project/astor>`_):
+
+.. code:: console
+
+	$ git clone --recursive https://github.com/althonos/peptides.py
+	$ cd peptides.py
+	# python setup.py build_py install
+
+.. Danger::
+
+    Installing packages without ``pip`` is strongly discouraged, as they can
+    only be uninstalled manually, and may damage your system.

docs/make.bat

+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+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/requirements.txt

+# build dependencies
+setuptools >=46.4
+cython ~=0.29.16
+
+# sphinx documentation dependencies
+semantic_version ~=2.8
+sphinx ~=4.0
+recommonmark ~=0.7
+
+# sphinx-bootstrap-theme ~=0.7 with patched admonition
+https://github.com/althonos/sphinx-bootstrap-theme/archive/master.zip

peptides/__init__.py

+"""Physicochemical properties and indices for amino-acid sequences.
+"""
+
 import array
 import collections
 import math