docs: update RtD guides (#172)

* docs: update RtD page * docs: add installation guide * docs: add usage and examples pages * docs: update guides * docs: update README * docs: update guides * fix README badges * docs: update README, guides * update version * update rtd config * update versioning * remove docker image and build * update readme * update versioning * update guides * update usage guide with tables * update Results model description * docs: update index, restructure API docs * update style
zavolanlab · Nov 20, 2024 · a43cb92 · a43cb92
1 parent 797abe8
commit a43cb92
Show file tree

Hide file tree

Showing 18 changed files with 385 additions and 208 deletions.
diff --git a/.dockerignore b/.dockerignore
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -126,38 +126,3 @@ jobs:
       - name: integration test - paired-ended library
         run: htsinfer --cleanup-regime=KEEP_NONE --verbosity=DEBUG tests/files/adapter_{1,2}.fastq
 
-  publish:
-    name: build and publish app image
-    runs-on: ubuntu-latest
-    if: |
-      github.event_name == 'push' && 
-      github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
-
-    steps:
-
-      - name: check out repository
-        uses: actions/checkout@v3
-
-      - name: generate tag
-        run: |
-          echo "TAG=$(date '+%Y%m%d')" >> $GITHUB_ENV
-
-      - name: build and publish image
-        id: docker
-        uses: philips-software/docker-ci-scripts@v5.1.0
-        with:
-          dockerfile: .
-          image-name: "htsinfer"
-          tags: "latest ${{ env.TAG }}"
-          push-branches: "${{ github.event.repository.default_branch }}"
-        env:
-          REGISTRY_USERNAME: ${{ secrets.DOCKERHUB_LOGIN }}
-          REGISTRY_TOKEN: "${{ secrets.DOCKERHUB_TOKEN }}"
-          DOCKER_ORGANIZATION: ${{ secrets.DOCKERHUB_ORG }}
-          GITHUB_ORGANIZATION: ${{ github.repository_owner }}
-
-      - name: Verify that image was pushed
-        run: |
-          echo "Push indicator: ${{ steps.docker.outputs.push-indicator }}"
-          echo "# Set to 'true' if image was pushed, empty string otherwise"
-          test "${{ steps.docker.outputs.push-indicator }}" == "true"
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
diff --git a/README.md b/README.md
@@ -3,21 +3,41 @@
 [![license][badge-license]][badge-url-license]
 [![docs][badge-docs]][badge-url-docs]
 [![release_gh][badge-release-gh]][badge-url-release-gh]
-[![release_docker][badge-release-docker]][badge-url-release-docker]
 [![ci][badge-ci]][badge-url-ci]
 [![coverage][badge-coverage]][badge-url-coverage]
+[![release_biocontainer][badge-release-biocontainer]][badge-url-release-biocontainer]
+[![DOI:zenodo][badge-doi-zenodo]][badge-url-doi-zenodo]
 
-HTSinfer infers metadata from Illumina high-throughput sequencing (HTS) data.
+HTSinfer infers RNA-Seq 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
+
+HTSinfer is available on [Bioconda][bioconda-release]. To install it in your currently active [Conda][conda] environment, run:
+
+```sh
+conda install bioconda::htsinfer
+```
+
+### General usage
+
+```sh
+htsinfer [-h] [--verbosity {DEBUG,INFO,WARN,ERROR,CRITICAL}] [--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
@@ -85,73 +105,13 @@ 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).
+To better understand the output, please refer to the [`Results`][docs-results]
+section in the [documentation][badge-url-docs].
 
-## API documentation
+## Versioning
 
-Auto-built API documentation is hosted on [ReadTheDocs][badge-url-docs].
+The project follows the [Semantic Versioning][semver] guidelines for version management. 
+Currently, the service is in its beta phase, meaning API breaking changes or updates may occur without prior notice.
 
 ## Contributing
 
@@ -169,20 +129,25 @@ 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-biocontainer]: <https://img.shields.io/badge/BioContainer-%20htsinfer-blue?style=flat.svg>
 [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-biocontainer]: <https://quay.io/repository/biocontainers/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>
+[bioconda-release]: <https://anaconda.org/bioconda/htsinfer>
+[semver]: <https://semver.org/>
 [contact]: <https://zavolan.biozentrum.unibas.ch/>
-[docs-api-results]: <https://htsinfer.readthedocs.io/en/latest/modules/htsinfer.html#htsinfer.models.Results>
+[docs-documentation]: <https://htsinfer.readthedocs.io/>
+[docs-results]: <https://htsinfer.readthedocs.io/en/latest/guides/examples.html#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
@@ -1,4 +1,4 @@
-from htsinfer import __version__
+from htsinfer.version import __version__
 
 # Configuration file for the Sphinx documentation builder.
 #
@@ -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 -----------------------------------------------------
@@ -38,6 +38,7 @@
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.napoleon',
+    'sphinx.ext.autosectionlabel'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -46,7 +47,9 @@
 # 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 = [
+    'setup.py'
+]
 
 # Default doc to search for
 master_doc = 'index'
@@ -61,7 +64,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 +77,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')