Update documentation config to build on readthedocs.org

README.md

@@ -2,9 +2,10 @@
 
 [TODO]
 
-See **Contributing** for installation instructions
+Learn about the ProteoBench project on [proteobench.github.io](https://proteobench.github.io/).
 
+See **Contributing** for installation instructions
 
-## Documenation
+## Developer-oriented documentation
 
-You find the documentation in docs/_build/html
+You find the Python package documentation on [proteobench.readthedocs.io](https://proteobench.readthedocs.io/).

docs/changelog.rst

@@ -1,5 +1,2 @@
-=================
-Change log
-=================
-
-TODO
+.. include::  ../CHANGELOG.md
+   :parser: myst_parser.sphinx_

docs/conf.py

@@ -1,44 +1,20 @@
-# Configuration file for the Sphinx documentation builder.
-#
-# For the full list of built-in configuration values, see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
-
-import os
-import sys
-
-# -- Project information -----------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
-
 project = "ProteoBench"
 copyright = "2023, EuBIC-MS"
 author = "EuBIC-MS"
 description = "A Python-base platform for benchmarking data analysis in proteomics."
 
-# Add source folder to path for autodoc
-sys.path.insert(0, os.path.abspath(".."))
-
-# Add path for documentation including the main project path
-
-# -- General configuration ---------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
-
-extensions = []
-
-templates_path = ["_templates"]
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
-
-
-# -- Options for HTML output -------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
-
-html_theme = "sphinx_rtd_theme"
-html_static_path = ["_static"]
-
 extensions = [
+    "myst_parser",
     "sphinx.ext.napoleon",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.viewcode",
     "sphinx.ext.todo",
-    "sphinx.ext.githubpages",
 ]
+
+source_suffix = [".rst"]
+master_doc = "index"
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+html_theme = "sphinx_rtd_theme"
+# html_static_path = ["_static"]

docs/index.rst

@@ -8,11 +8,13 @@ Welcome
 
 .. toctree::
     :maxdepth: 1
+    :hidden:
 
-    user_guide/index
-    changelog
+    Home <self>
+    userguide/index
     proteobench/modules
     webinterface/webinterface
+    changelog
 
 Project Overview
 ------------------

docs/user_guide/index.rst → docs/userguide/index.rst

@@ -15,20 +15,20 @@ ProteoBench can be installed as Python package using the usual pip command:
 
     pip install proteobench
 
-or, without pip, by cloning the repository and running the setup script:
+or by cloning the repository and installing in editable mode:
 
 .. code-block:: bash
 
     git clone https://github.com/Proteobench/ProteoBench
     cd proteobench
-    python setup.py install
+    pip install --editable .[dev]
 
 
 ********************************
 Local usage
 ********************************
 
-Start the streamlit GUI from your terminal with the following commands. 
+Start the streamlit GUI from your terminal with the following commands.
 
 .. code-block:: bash
 
@@ -58,18 +58,18 @@ We suggest to understand the following terms as they are crucial components:
 
     **Module**: All code and definitions for creating and comparing benchmarks of a new data type
 
-    **Intermediate data structure** (`DataFrame`): Data structure needed for the calculation of the `datapoint`. It contains 
+    **Intermediate data structure** (`DataFrame`): Data structure needed for the calculation of the `datapoint`. It contains
     the transformed and annotated data of an uploaded data file.
 
-    **Datapoint**: Metadata and benchmarking metrics for a given data set. A `datapoint` is the 
+    **Datapoint**: Metadata and benchmarking metrics for a given data set. A `datapoint` is the
     data needed for the benchmarking and should also be represented by a json object.
 
 -----------------------
 Programmatic structure
 -----------------------
 
-The modules are located in the `proteobench/modules <https://github.com/Proteobench/ProteoBench/tree/main/proteobench/modules>`_ directory. We separated the benchmarking modules into a different steps 
-that allow for a more modular and portable implementation. 
+The modules are located in the `proteobench/modules <https://github.com/Proteobench/ProteoBench/tree/main/proteobench/modules>`_ directory. We separated the benchmarking modules into a different steps
+that allow for a more modular and portable implementation.
 
 **Backend**
 
@@ -84,46 +84,48 @@ Each module implementation should contain the following classes:
 **Web interface**
 
 The web interface is written in Streamlit. Each module gets assigned a specific "page".
-There are only few changes necessary as the main calculations are done in 
+There are only few changes necessary as the main calculations are done in
 
   :func:`~webinterface.pages.TEMPLATE.StreamlitUI` contains the functions to create the web interface for the module.
 
 *Relevant functions:*
 
   :func:`~webinterface.pages.TEMPLATE.StreamlitUI.generate_input_field` creates the input fields for the metadate and the
-  input file format and type. They are given by in the `proteobench/modules/template/io_parse_settings <https://github.com/Proteobench/ProteoBench/tree/main/proteobench/modules/template/io_parse_settings>`_ folder, 
+  input file format and type. They are given by in the `proteobench/modules/template/io_parse_settings <https://github.com/Proteobench/ProteoBench/tree/main/proteobench/modules/template/io_parse_settings>`_ folder,
   same as for the backend of the module.
 
   :func:`webinterface.pages.TEMPLATE.StreamlitUI.generate_results` gathers the data from the backend
   and displays them in several figures. Here you will need to edit and adapt the code
-  to show the respective figures with the right metadata. 
+  to show the respective figures with the right metadata.
 
   :func:`webinterface.pages.TEMPLATE.WebpageTexts` contains the text for the different parts of the web interface.
 
 Change the text and the field names accordingly
 
 **Documentation**
 
-We strongly recommend to keep documenting your code. The documentation is written in Sphinx and 
+We strongly recommend to keep documenting your code. The documentation is written in Sphinx and
 can be found in the `docs <https://github.com/Proteobench/ProteoBench/tree/main/docs>`_ folder.
 
 1.  `docs/proteobench/modules.rst <https://github.com/Proteobench/ProteoBench/tree/main/docs/proteobench/modules.rst>`_ Here you can add a link to your new module
 2.  `docs/proteobench/template.rst <https://github.com/Proteobench/ProteoBench/tree/main/docs/proteobench/template.rst>`_ This template can be used to creat your own documentation file in reStructuredText (rst) format.
 3.  `docs/webinterface/webinterface.rst <https://github.com/Proteobench/ProteoBench/tree/main/docs/webinterface/webinterface.rst>`_ Here you should add a link to the new page in the web interface.
 
 
-You can regenerate the documentation by running the following command in the `docs` folder
+To work on the documentation and get a live preview, install the requirements and run
+``sphinx-autobuild``:
 
-.. code-block:: bash
+.. code-block:: sh
 
-    make clean
-    make html
+    pip install .[docs]
+    sphinx-autobuild  --watch ./ms2rescore ./docs/source/ ./docs/_build/html/
 
+Then browse to http://localhost:8000 to watch the live preview.
 
-**Notes**
 
+.. note::
 
-Ensure to have changes all "template" to the name of your module.
+    Ensure to have changed all occurrences of ``template`` to the name of your new module.
 
 
 -----------------------
@@ -133,7 +135,7 @@ Checklist
 This checklist is meant to help you add a new module to ProteoBench. It is not
 meant to be exhaustive, but it should cover the most important steps.
 
-1. Copy the `template <<https://github.com/Proteobench/ProteoBench/tree/main/proteobench/modules>template>`_ folder in the `proteobench/modules <https://github.com/Proteobench/ProteoBench/tree/main/proteobench/modules>`_ directory to a new folder in the same directory. The name of the new directory should be the name of the module. 
+1. Copy the `template <https://github.com/Proteobench/ProteoBench/tree/main/proteobench/modulestemplate>`_ folder in the `proteobench/modules <https://github.com/Proteobench/ProteoBench/tree/main/proteobench/modules>`_ directory to a new folder in the same directory. The name of the new directory should be the name of the module.
 2. Define the input formats in the toml files of the `proteobench/modules/my_module/io_parse_settings` directory and  `proteobench.modules.my_module.parse_settings.py`.
 3. Modify the upload prodecures in the `proteobench/modules/my_module/parse.py`. This will ensure a standardized data structure for the benchmarking independently from the input file format.
 4. Modify `proteobench/modules/my_module/datapoint.py` to define the requested metadata about the data acquisition and the benchmarking metrics, all to be stored in a datapoint. You might need to add some function(s) for further processing the standardized data structure.
@@ -146,12 +148,12 @@ meant to be exhaustive, but it should cover the most important steps.
 Modifying an existing module
 ================================
 
-We recommend keeping the given structure in a module. 
+We recommend keeping the given structure in a module.
 
 *For adding new input file types*: Use the :func:`~proteobench.modules.template.ParseInputs` class to define the parsing of the input files and a specific toml file for its layout.
 
-*For adding new benchmarking metrics*: Add the new metrics to the `datapoint.py` file and the `plot.py` file for visualization. 
+*For adding new benchmarking metrics*: Add the new metrics to the `datapoint.py` file and the `plot.py` file for visualization.
 
-*Note* that changing the intermediate format and the data point structure might have an impact on the other modules. Therefore we recommend 
+*Note* that changing the intermediate format and the data point structure might have an impact on the other modules. Therefore we recommend
 to define them stringently from the start.
 

pyproject.toml

@@ -1,19 +1,19 @@
 [project]
 name = "proteobench"
-authors = [{name = "Robbin Bouwmeester", email = "[email protected]"}]
+authors = [
+    { name = "Robbin Bouwmeester", email = "[email protected]" },
+] # TODO: Add others
 readme = "README.md"
-license = {file = "LICENSE"}
+license = { file = "LICENSE" }
 classifiers = [
     "Intended Audience :: Science/Research",
     "License :: OSI Approved :: Apache Software License",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
     "Topic :: Scientific/Engineering :: Bio-Informatics",
-    "Development Status :: 4 - Beta"
-]
-keywords=[
-    'proteomics', 'peptides', 'retention time', 'mass spectrometry'
+    "Development Status :: 4 - Beta",
 ]
+keywords = ['proteomics', 'peptides', 'retention time', 'mass spectrometry']
 requires-python = ">=3.7"
 dynamic = ["version", "description"]
 dependencies = [
@@ -24,31 +24,17 @@ dependencies = [
     "streamlit-plotly-events",
     "matplotlib",
     "importlib-metadata; python_version < '3.8'",
-    "toml"
+    "toml",
 ]
 
 [project.optional-dependencies]
-dev = [
-    "black",
-]
-docs = [
-    "numpydoc>=1,<2",
-    "recommonmark",
-    "sphinx",
-    "sphinx-autobuild",
-    "sphinx-autodoc-typehints",
-    "sphinx-mdinclude",
-    "sphinx-rtd-theme",
-]
-web = [
-    "streamlit",
-    "scipy"
-]
+dev = ["black"]
+docs = ["sphinx", "sphinx-rtd-theme", "sphinx-autobuild", "myst-parser"]
+web = ["streamlit", "scipy"]
 
 [project.urls]
-"Home" = "https://github.com/RobbinBouwmeester"
-"Homepage" = "https://github.com/RobbinBouwmeester/"
-"Bug Tracker" = "https://github.com/RobbinBouwmeester/"
+"Homepage" = "https://github.com/ProteoBench"
+"Bug Tracker" = "https://github.com/ProteoBench/ProteoBench/issues/"
 
 [build-system]
 requires = ["flit_core >=3.2,<4"]