zavolanlab · balajtimate · Nov 20, 2024 · Sep 19, 2024 · Sep 19, 2024 · Oct 21, 2024
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -8,7 +8,7 @@ build:
   tools:
     python: "mambaforge-4.10"
 sphinx:
-   configuration: docs/api/conf.py
+   configuration: docs/conf.py
 formats:
    - pdf
    - epub

diff --git a/Dockerfile b/Dockerfile
@@ -5,7 +5,7 @@ FROM continuumio/miniconda3:4.12.0
 LABEL base_image="continuumio/miniconda3:4.12.0"
 LABEL version="1.0"
 LABEL software="HTSinfer"
-LABEL software.version="v0.9.0"
+LABEL software.version="v1.0.0"
 LABEL about.summary="HTSinfer infers metadata from Illumina high-throughput sequencing (HTS) data"
 LABEL about.home="https://github.com/zavolanlab/htsinfer"
 LABEL about.documentation="https://htsinfer.readthedocs.io/"

diff --git a/README.md b/README.md
@@ -6,18 +6,64 @@
 [![release_docker][badge-release-docker]][badge-url-release-docker]
 [![ci][badge-ci]][badge-url-ci]
 [![coverage][badge-coverage]][badge-url-coverage]
+[![DOI:zenodo][badge-doi-zenodo]][badge-url-doi-zenodo]
 
 HTSinfer infers metadata from Illumina high-throughput sequencing (HTS) data.
 
-## Examples
+## Quick start
 
-**Single-ended library***
+For a more in-depth guide please refer to the [HTSinfer documentation][docs-documentation].
+
+### Installation
+
+In order to use the HTSinfer, clone the repository and install the
+dependencies via [Conda][conda] or [Mamba][mamba]:
+
+```sh
+git clone https://github.com/zavolanlab/htsinfer
+cd htsinfer
+conda env create --file environment.yml
+```
+
+Then, activate the `htsinfer` Conda environment with:
+
+```sh
+conda activate htsinfer
+```
+
+### General usage
+
+```sh
+htsinfer [--output-directory PATH]
+         [--temporary-directory PATH]
+         [--cleanup-regime {DEFAULT,KEEP_ALL,KEEP_NONE,KEEP_RESULTS}]
+         [--records INT]
+         [--threads INT]
+         [--transcripts FASTA]
+         [--read-layout-adapters PATH]
+         [--read-layout-min-match-percentage FLOAT]
+         [--read-layout-min-frequency-ratio FLOAT]
+         [--library-source-min-match-percentage FLOAT]
+         [--library-source-min-frequency-ratio FLOAT]
+         [--library-type-max-distance INT]
+         [--library-type-mates-cutoff FLOAT]
+         [--read-orientation-min-mapped-reads INT]
+         [--read-orientation-min-fraction FLOAT]
+         [--tax-id INT]
+         [--verbosity {DEBUG,INFO,WARN,ERROR,CRITICAL}]
+         [-h] [--version]
+         PATH [PATH]
+```
+
+### Examples
+
+**Single-ended library**
 
 ```sh
 htsinfer tests/files/adapter_single.fastq
 ```
 
-**Paired-ended library***
+**Paired-ended library**
 
 ```sh
 htsinfer tests/files/adapter_1.fastq tests/files/adapter_2.fastq
@@ -86,103 +132,45 @@ example library:
 ```
 
 To better understand the output, please refer to the [`Results`
-model][docs-api-results] in the [API documentation][badge-url-docs]. Note that
-`Results` model has several nested child models, such as enumerators of
-possible outcomes. Simply follow the references in each parent model for
-detailed descriptions of each child model's attributes.
-
-## General usage
-
-```sh
-htsinfer [--output-directory PATH]
-         [--temporary-directory PATH]
-         [--cleanup-regime {DEFAULT,KEEP_ALL,KEEP_NONE,KEEP_RESULTS}]
-         [--records INT]
-         [--threads INT]
-         [--transcripts FASTA]
-         [--read-layout-adapters PATH]
-         [--read-layout-min-match-percentage FLOAT]
-         [--read-layout-min-frequency-ratio FLOAT]
-         [--library-source-min-match-percentage FLOAT]
-         [--library-source-min-frequency-ratio FLOAT]
-         [--library-type-max-distance INT]
-         [--library-type-mates-cutoff FLOAT]
-         [--read-orientation-min-mapped-reads INT]
-         [--read-orientation-min-fraction FLOAT]
-         [--tax-id INT]
-         [--verbosity {DEBUG,INFO,WARN,ERROR,CRITICAL}]
-         [-h] [--version]
-         PATH [PATH]
-```
-
-## Installation
-
-In order to use the HTSinfer, clone the repository and install the
-dependencies via [Conda][conda]:
-
-```sh
-git clone https://github.com/zavolanlab/htsinfer
-cd htsinfer
-conda env create --file environment.yml
-# Alternatively, to install with development dependencies,
-# run the following instead
-conda env create --file environment-dev.yml
-```
-
-> Note that creating the environment takes non-trivial time and it is strongly
-> recommended that you install [Mamba][mamba] and replace `conda` with `mamba`
-> in the previous command.
-
-Then, activate the `htsinfer` Conda environment with:
-
-```sh
-conda activate htsinfer
-```
-
-If you have installed the development/testing dependencies, you may first want
-to verify that HTSinfer was installed correctly by executing the tests shipped
-with the package:
-
-```sh
-python -m pytest
-```
-
-Otherwise just go ahead and try one of the [examples](#Examples).
+model][docs-api-results] in the [API documentation][badge-url-docs].
 
-## API documentation
+### API documentation
 
 Auto-built API documentation is hosted on [ReadTheDocs][badge-url-docs].
 
-## Contributing
+### Contributing
 
 This project lives off your contributions, be it in the form of bug reports,
 feature requests, discussions, or fixes and other code changes. Please refer
 to the [contributing guidelines](CONTRIBUTING.md) if you are interested to
 contribute. Please mind the [code of conduct](CODE_OF_CONDUCT.md) for all
 interactions with the community.
 
-## Contact
+### Contact
 
 For questions or suggestions regarding the code, please use the
 [issue tracker][issue-tracker]. For any other inquiries, please contact us
 by email: <zavolab-biozentrum@unibas.ch>
 
 (c) 2020 [Zavolan lab, Biozentrum, University of Basel][contact]
 
-[badge-ci]: <https://travis-ci.com/zavolanlab/htsinfer.svg?branch=master>
+[badge-ci]: <https://github.com/zavolanlab/htsinfer/workflows/ci/badge.svg?branch=dev>
 [badge-coverage]: <https://codecov.io/gh/zavolanlab/htsinfer/branch/dev/graph/badge.svg?token=KYGJ9MUPHT>
 [badge-docs]: <https://readthedocs.org/projects/htsinfer/badge/?version=latest>
 [badge-license]: <https://img.shields.io/badge/license-Apache%202.0-blue.svg>
 [badge-release-docker]: <https://img.shields.io/docker/image-size/zavolab/htsinfer?color=C39BD3&label=docker>
 [badge-release-gh]: <https://img.shields.io/github/v/tag/zavolanlab/htsinfer?color=C39BD3>
-[badge-url-ci]: <https://travis-ci.com/zavolanlab/htsinfer>
+[badge-doi-zenodo]: <https://zenodo.org/badge/265279928.svg>
+[badge-url-ci]: <https://github.com/zavolanlab/htsinfer/actions?query=workflow%3Aci>
 [badge-url-coverage]: <https://codecov.io/gh/zavolanlab/htsinfer>
 [badge-url-docs]: <https://htsinfer.readthedocs.io/en/latest/?badge=latest>
 [badge-url-license]: <http://www.apache.org/licenses/LICENSE-2.0>
 [badge-url-release-docker]: <https://hub.docker.com/repository/docker/zavolab/htsinfer>
 [badge-url-release-gh]: <https://github.com/zavolanlab/htsinfer/releases>
+[badge-url-doi-zenodo]: <https://doi.org/10.5281/zenodo.13985958>
 [conda]: <https://docs.conda.io/en/latest/miniconda.html>
 [contact]: <https://zavolan.biozentrum.unibas.ch/>
+[docs-documentation]: <https://htsinfer.readthedocs.io/>
 [docs-api-results]: <https://htsinfer.readthedocs.io/en/latest/modules/htsinfer.html#htsinfer.models.Results>
 [issue-tracker]: <https://github.com/zavolanlab/htsinfer/issues>
 [mamba]: <https://mamba.readthedocs.io/en/latest/installation.html>
diff --git a/docs/_static/custom.css b/docs/_static/custom.css
@@ -0,0 +1,4 @@
+/* Increase font size for toctree elements */
+.toctree-l1 {
+    font-size: 18px;  /* Adjust the size as needed */
+}
diff --git a/docs/api/index.rst b/docs/api/index.rst
diff --git a/docs/api/conf.py → docs/conf.py b/docs/api/conf.py → docs/conf.py
@@ -17,7 +17,7 @@
 
 from sphinx.ext import apidoc
 
-sys.path.insert(0, os.path.abspath('../..'))
+sys.path.insert(0, os.path.abspath('../htsinfer'))
 
 
 # -- Project information -----------------------------------------------------
@@ -46,7 +46,14 @@
 # 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', 'api/yourpackage.rst']
+exclude_patterns = [
+    '_build',
+    'api/yourpackage.rst',
+    'setup.py',
+    'Thumbs.db',
+    '.DS_Store',
+    '.eggs'
+]
 
 # Default doc to search for
 master_doc = 'index'
@@ -61,7 +68,7 @@
 # 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 = []
+html_static_path = ['_static']
 
 
 # -- Automation -------------------------------------------------------------
@@ -74,10 +81,11 @@ def run_apidoc(_):
         "--force",
         "--module-first",
         "-o", "./modules",
-        "../../htsinfer"
+        "../htsinfer"
     ] + ignore_paths
     apidoc.main(argv)
 
 
 def setup(app):
     app.connect('builder-inited', run_apidoc)
+    app.add_css_file('custom.css')
diff --git a/docs/guides/examples.rst b/docs/guides/examples.rst
@@ -0,0 +1,87 @@
+Examples
+========
+
+`HTSinfer` provides easy-to-use commands for analyzing single- and paired-ended RNA-Seq libraries.
+
+
+Single-ended Library Example
+----------------------------
+
+To run `HTSinfer` on a single-ended RNA-Seq library, use the following command:
+
+.. code-block:: bash
+
+   htsinfer tests/files/adapter_single.fastq
+
+Paired-ended Library Example
+----------------------------
+
+To run `HTSinfer` on a paired-ended RNA-Seq library, use the following command:
+
+.. code-block:: bash
+
+   htsinfer tests/files/adapter_1.fastq tests/files/adapter_2.fastq
+
+Both commands will output the results in JSON format to :code:`STDOUT` and the log to :code:`STDERR`.
+
+Example Output
+--------------
+
+Here is a sample output for the paired-ended library:
+
+.. code-block:: json
+
+   {
+      "library_stats": {
+         "file_1": {
+            "read_length": {
+               "min": 75,
+               "max": 75,
+               "mean": 75.0,
+               "median": 75,
+               "mode": 75
+            }
+         },
+         "file_2": {
+            "read_length": {
+               "min": 75,
+               "max": 75,
+               "mean": 75.0,
+               "median": 75,
+               "mode": 75
+            }
+         }
+      },
+      "library_source": {
+         "file_1": {
+            "short_name": "hsapiens",
+            "taxon_id": "9606"
+         },
+         "file_2": {
+            "short_name": "hsapiens",
+            "taxon_id": "9606"
+         }
+      },
+      "library_type": {
+         "file_1": "first_mate",
+         "file_2": "second_mate",
+         "relationship": "split_mates"
+      },
+      "read_orientation": {
+         "file_1": "SF",
+         "file_2": "SR",
+         "relationship": "ISF"
+      },
+      "read_layout": {
+         "file_1": {
+            "adapt_3": "AATGATACGGCGACC",
+            "polyA_frac": 10.0
+         },
+         "file_2": {
+            "adapt_3": "AATGATACGGCGACC",
+            "polyA_frac": 10.0
+         }
+      }
+   }
+
+For more details on the output structure, refer to the :code:`Results` model in the API documentation.