Add documentation to project

.githooks/compress_files.sh

@@ -13,6 +13,9 @@ COREDIR=prospr/core/src
 DATADIR=prospr/data
 
 
+# Move into the git root.
+cd $(git rev-parse --show-toplevel)
+
 # Create .zip core archive.
 zip -jqr prospr_core.zip "${COREDIR}/"
 mv prospr_core.zip "${ARCHIVEDIR}/prospr_core.zip"

.pre-commit-config.yaml

@@ -10,6 +10,7 @@ repos:
     rev: v3.2.0
     hooks:
       - id: trailing-whitespace
+        exclude: README.md
       - id: end-of-file-fixer
       - id: check-yaml
       - id: check-added-large-files
@@ -22,6 +23,7 @@ repos:
     rev: v0.812
     hooks:
         - id: mypy
+          exclude: ^docs/
   - repo: https://github.com/psf/black
     rev: 20.8b1
     hooks:

README.md

@@ -1,23 +1,45 @@
 ## Prospr: The Protein Structure Prediction Toolbox
+<p align="center">
+    <img src="docs/source/_static/prospr_logo.png" alt="Prospr's logo" width="496" height="308">  
+</p>
+
 ![GitHub](https://img.shields.io/github/license/OkkeVanEck/prospr)
 ![GitHub release (latest by date including pre-releases)](https://img.shields.io/github/v/release/OkkeVanEck/prospr?include_prereleases)
 ![GitHub Workflow Status (branch)](https://img.shields.io/github/workflow/status/OkkeVanEck/prospr/CI-CD/master)
+[![Documentation Status](https://readthedocs.org/projects/prospr/badge/?version=latest)](https://prospr.readthedocs.io/en/latest/?badge=latest)
 [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)  
 **Creator:** Okke van Eck
 
-This project is a universal toolbox for protein structure prediction within the HP-model.
-It will contain a datastructure for creating own algorithms, pre-created algorithms, datasets and visualization functions.
-Besides folding proteins, this package will also make it possible to determine the relative hardness of a protein for an algorithm.
-This allows for a fair comparison across the different algorithms.
+Prospr is a universal toolbox for protein structure prediction within the
+HP-model.
+At the core, Prospr offers an easy-to-use Protein data structure, which can be
+used to simulate protein folding.
+It also offers algorithms, datasets and visualization functions.
+The Protein data structure tracks many properties when folding the protein.
+This includes tracking the number of conformation changes, which makes it
+possible to determine the relative hardness of a protein for a specific 
+algorithm.
+This allows for a fair comparison between different algorithms.
 
 So far, only square lattices are supported in n-dimensions.
-The amino acids can only be placed in the corners of the squares and have to be one unit away from the previously placed amino acid.
+The amino acids can only be placed in the corners of the squares and have to be
+one unit distance away from the previously placed amino acid.
+
+The Python package is based on a C++ core, which gives Prospr its high
+performance.
+The C++ core is made available as a separate zip file to facilitate
+high-performance computing applications.
+See the C++ core section below for direct links to the core.
 
-## Installation guide
+## Installation and documentation
 This package can simply be installed via pip by running:
 ```bash
 pip install prospr
 ```
+A quickstart and reference documentation can be found at
+[prospr.readthedocs.io](https://prospr.readthedocs.io).
+The PDF version of the complete documentation can be found
+[here](https://prospr.readthedocs.io/_/downloads/en/latest/pdf/).
 
 ## Archives
 All the C++ core files and datasets are also available as compressed archives.
@@ -33,15 +55,11 @@ The complete collection of datasets is available as a compressed archive in the
 `archives` folder. It is available as a [.zip](archives/prospr_data.zip) and a
 [.tar.tz](archives/prospr_data.tar.gz) archive.
 
-## Example usage
-*Work in progress*
-
 ## Future work
-This toolbox could be used for other protein folding problems within discrete models.
-It would be a great extension to support different models by creating a modular amino acid.
-
-## Changelog
-*Work in progress*
+This toolbox could be used for other protein folding problems within discrete
+models.
+It would be a great extension to support different models by creating a modular
+amino acid.
 
 ## License
 The used license is the GNU LESSER GENERAL PUBLIC LICENSE.

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)

docs/gen_logo.py

@@ -0,0 +1,100 @@
+import seaborn as sns
+import pandas as pd
+from prospr import Protein
+from prospr.helpers import get_ordered_positions, get_scoring_pairs
+from matplotlib import pyplot as plt
+from matplotlib.path import Path
+import matplotlib.patches as patches
+
+
+if __name__ == "__main__":
+    protein = Protein("HPPHP")
+    protein.set_hash([1, -2, -1, -2])
+
+    fig = plt.figure(figsize=(8, 5))
+    sns.set_style("whitegrid")
+    ax = fig.gca()
+
+    df = pd.DataFrame(
+        get_ordered_positions(protein), columns=["x", "y", "Type"]
+    )
+    df = df.astype({"x": "int32", "y": "int32"})
+
+    # Plot straight lines and add last amino acid.
+    line_width = 8
+    alpha_val = 0.85
+    ax.plot(
+        df["x"],
+        df["y"],
+        color="black",
+        alpha=alpha_val,
+        zorder=1,
+        lw=line_width,
+    )
+    last_amino = {"x": 3.5, "y": -0.75, "Type": "H"}
+    df = df.append(last_amino, ignore_index=True)
+
+    # Plot curvy line.
+    verts = [
+        (df.iloc[-2]["x"], df.iloc[-2]["y"]),
+        (1.375, -0.5),
+        (last_amino["x"], last_amino["y"]),
+    ]
+    codes = [
+        Path.MOVETO,
+        Path.CURVE3,
+        Path.CURVE3,
+    ]
+    path = Path(verts, codes)
+    patch = patches.PathPatch(
+        path,
+        facecolor="none",
+        edgecolor="black",
+        lw=line_width,
+        alpha=alpha_val,
+        zorder=1,
+    )
+    ax.add_patch(patch)
+
+    # Add amino acids.
+    sns.scatterplot(
+        x="x",
+        y="y",
+        data=df,
+        hue="Type",
+        hue_order=["H", "P"],
+        style="Type",
+        markers={"H": "o", "P": "s"},
+        palette={"H": "royalblue", "P": "orange"},
+        s=280,
+        linewidth=0,
+        zorder=2,
+        ax=ax,
+    )
+
+    # Plot dotted lines between the aminos that increase the stability.
+    pairs = get_scoring_pairs(protein)
+
+    for pos1, pos2 in pairs:
+        ax.plot(
+            [pos1[0], pos2[0]],
+            [pos1[1], pos2[1]],
+            linestyle="dashed",
+            color="indianred",
+            alpha=1,
+            zorder=1,
+            lw=line_width,
+        )
+
+    # Plot text.
+    ax.text(0.73, -1.88, "rospr", fontsize=121, fontstyle="italic")
+
+    # Remove axis and legend.
+    ax.get_xaxis().set_visible(False)
+    ax.get_yaxis().set_visible(False)
+    ax.get_legend().remove()
+
+    fig.savefig(
+        "source/_static/gen_logo.png", bbox_inches="tight", pad_inches=0
+    )
+    plt.show()

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