docs: update guides, README

README.md

@@ -16,24 +16,10 @@ For a more in-depth guide please refer to the [HTSinfer documentation][docs-docu
 
 ### Installation
 
-HTSinfer is available as part of the [Bioconda][bioconda-release] channel, therefore the preferred installation method is via [Mamba][mamba] or [Conda][conda].
-
-To create a new Conda environment with HTSinfer and its dependencies installed, run:
-
-```sh
-mamba create --name htsinfer bioconda::htsinfer
-```
-
-Then, activate the `htsinfer` Conda environment with:
-
-```sh
-conda activate htsinfer
-```
-
-To install HTSinfer in your current environment, run:
+HTSinfer is available on [Bioconda][bioconda-release]. To install it in your currently active [Conda][conda] environment, run:
 
 ```sh
-mamba install bioconda::htsinfer
+conda install bioconda::htsinfer
 ```
 
 ### General usage
@@ -119,11 +105,13 @@ example library:
 }
 ```
 
-To better understand the output, please refer to the [`Results`][docs-api-results] model in the [API documentation][badge-url-docs].
+To better understand the output, please refer to the [`Results`][docs-results]
+section in the [documentation][badge-url-docs].
 
 ## Versioning
 
-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.
+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
 
@@ -160,6 +148,6 @@ by email: <[email protected]>
 [semver]: <https://semver.org/>
 [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>
+[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>

docs/conf.py

@@ -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.

docs/guides/examples.rst

@@ -87,10 +87,10 @@ Here is a sample output for the paired-ended library:
 Results
 -------
 
-For more details on the output structure, refer to the :code:`Results` model in the API documentation.
-
 - :code:`library_stats`: Read length statistics results, including the minimum, maximum, mean, median and mode.
 - :code:`library_source`: Library source inference results, with the short name and NCBI taxonomy ID of the source organism.
 - :code:`library_type`: Library type inference results, single- or paired-end. In case of paired-end samples, the mate designation.
 - :code:`read_orientation`: Read orientation inference results, based on the fragment library types notation from `Salmon <https://salmon.readthedocs.io/en/latest/library_type.html>`_.
-- :code:`read_layout`: Read layout inference results, including the 3'-adapter sequence and the poly(A) fraction. 
+- :code:`read_layout`: Read layout inference results, including the 3'-adapter sequence and the poly(A) fraction. 
+
+For more details on the output structure, refer to the :code:`Results` model in the API documentation.

docs/guides/installation.rst

@@ -1,59 +1,65 @@
 Installation
 ============
 
-This section describes how to install `HTSinfer`.
+This section describes how to install `HTSinfer`, either from :ref:`Bioconda<Install from Bioconda>` (recommended for most users) or :ref:`GitHub<Install from GitHub>` (for experienced users and developers).
 
-Install using Conda
--------------------
-
-The easiest and quickest installation method is via `Mamba <https://mamba.readthedocs.io/en/latest/installation.html>`_ or `Conda <https://docs.conda.io/en/latest/miniconda.html>`_.
-`HTSinfer` is available as part of the `Bioconda <https://anaconda.org/bioconda/htsinfer>`_ channel.
+Both installation methods require the popular package and environment manager `Conda <https://docs.conda.io/en/latest/miniconda.html>`_ to be available on your system.
 
-To create a new Conda environment with `HTSinfer` and its dependencies installed, run:
+.. note::
 
-.. code-block:: bash
+   For improved performance, we recommend using Conda's drop-in replacement `Mamba <https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html>`_ instead. 
+   In that case, simply replace :code:`conda` with :code:`mamba` in all of the commands below.
 
-   mamba create --name htsinfer bioconda::htsinfer
+Install from Bioconda
+---------------------
 
+The easiest and quickest installation method is to install the latest `HTSinfer` release from `Bioconda <https://anaconda.org/bioconda/htsinfer>`_. 
 
-Then, activate the `htsinfer` Conda environment with:
+To install `HTSinfer` in your currently active environment, run:
 
 .. code-block:: bash
 
-   conda activate htsinfer
+   conda install bioconda::htsinfer
 
+.. note::
 
-To install `HTSinfer` in your current environment, run:
-
-.. code-block:: bash
-
-   mamba install bioconda::htsinfer
+   We do not recommend installing HTSinfer into the default (:code:`base`) environment. 
+   Instead, activate a project- or tool-specific environment with :code:`conda activate MY_CONDA_PROJECT`. 
+   If you do not have such an environment, just create one with :code:`conda create --name MY_CONDA_PROJECT`. 
+   :code:`MY_CONDA_PROJECT` can be any name you like (with some constraints imposed by Conda), e.g., :code:`htsinfer`.
 
 Install from GitHub
 -------------------
 
-If you would like to contribute to the development of `HTSinfer`, or wishing to use unreleased versions, you can install `HTSinfer` from the `GitHub <https://github.com/zavolanlab/htsinfer>`_.
-First clone the repository and install the dependencies via `Conda <https://docs.conda.io/en/latest/miniconda.html>`_:
+If you wish to use the latest unreleased version of the tool or if you would like to contribute to its further development,
+please install `HTSinfer` from `GitHub <https://github.com/zavolanlab/htsinfer>`_.
+
+First clone the repository:
 
 .. code-block:: bash
 
    git clone https://github.com/zavolanlab/htsinfer.git
    cd htsinfer
-   mamba env create --file environment.yml
-   # Alternatively, to install with development dependencies,
-   # run the following instead
-   mamba env create --file environment-dev.ymls
+
+Then, install `HTSinfer` and its dependencies via `Conda <https://docs.conda.io/en/latest/miniconda.html>`_:
+
+.. code-block:: bash
+
+   conda env create --file environment.yml
+
+Alternatively, to include `HTSinfer`'s optional development dependencies, run the following instead:
+
+.. code-block:: bash
+
+   conda env create --file environment-dev.yml
 
 After the installation is complete, activate the :code:`htsinfer` Conda environment with:
 
 .. code-block:: bash
 
    conda activate htsinfer
 
-Verify the installation (optional)
-----------------------------------
-
-If you have installed the development or testing dependencies, you can verify that `HTSinfer` was installed correctly by executing the tests shipped with the package:
+If you have installed the development dependencies, you can verify that `HTSinfer` was installed correctly by executing the tests shipped with the package:
 
 .. code-block:: bash
 

docs/guides/usage.rst

@@ -35,8 +35,10 @@ Command-line options
 
 Available command-line parameters are categorized as follows:
 
-.. list-table:: General Options
-   :widths: 40 60
+**General options**
+
+.. list-table::
+   :widths: 30 70
 
    * - :code:`--output-directory`
      - Path where output data will be saved. 
@@ -52,8 +54,10 @@ Available command-line parameters are categorized as follows:
      - Show version information and exit.
 
 
-.. list-table:: Processing and Performance Options
-   :widths: 40 60
+**Processing and performance options**
+
+.. list-table::
+   :widths: 30 70
 
    * - :code:`--records`
      - Limits the number of input records to process; setting this to 0 will process all records.
@@ -62,29 +66,51 @@ Available command-line parameters are categorized as follows:
    * - :code:`--tax-id`
      - Taxonomy ID for the sample source, aiding in organism-specific analyses.
 
-.. list-table:: Library-specific Options
-   :widths: 40 60
+
+**Library-specific options**
+
+.. list-table::
+   :widths: 30 70
 
    * - :code:`PATH [PATH]`
-     - Path(s) to the RNA-Seq input data. For paired-end libraries, provide paths to both mate files.
+     - |  
+       | Path(s) to the RNA-Seq input data. 
+       | For paired-end libraries, provide paths to both mate files.
    * - :code:`--transcripts`
      - Path to the FASTA file containing transcript sequences for reference.
    * - :code:`--read-layout-adapters`
-     - Path to a file with 3' adapter sequences (one sequence per line) used to identify adapter content.
+     - |  
+       | Path to a file with 3' adapter sequences (one sequence per line)
+       | used to identify adapter content.
    * - :code:`--read-layout-min-match-percentage`
-     - Minimum percentage of reads containing an adapter for\n it to be considered as the library’s 3’-end adapter.
+     - |  
+       | Minimum percentage of reads containing an adapter 
+       | for it to be considered as the library’s 3’-end adapter.
    * - :code:`--read-layout-min-frequency-ratio`
-     - Minimum frequency ratio between the most and second most frequent adapters to select the 3’-end adapter.
+     - |  
+       | Minimum frequency ratio between the most and second most
+       | frequent adapters to select the 3’-end adapter.
    * - :code:`--library-source-min-match-percentage`
-     - Minimum percentage of reads aligning with a library source for it to be considered representative of the library.
+     - |  
+       | Minimum percentage of reads aligning with a library source
+       | for it to be considered representative of the library.
    * - :code:`--library-source-min-frequency-ratio`
-     - Minimum frequency ratio between primary and secondary library sources,
-       ensuring only the most prominent source is identified.
+     - |  
+       | Minimum frequency ratio between primary and secondary library sources,
+       | ensuring only the most prominent source is identified.
    * - :code:`--library-type-max-distance`
-     - Maximum allowable distance between read pairs to classify the library type.
+     - |  
+       | Maximum allowable distance between read pairs
+       | to classify the library type.
    * - :code:`--library-type-mates-cutoff`
-     - Ratio cutoff to determine the consistency of mate orientation in paired-end reads.
+     - |  
+       | Ratio cutoff to determine the consistency
+       | of mate orientation in paired-end reads.
    * - :code:`--read-orientation-min-mapped-reads`
-     - Minimum number of mapped reads to ensure reliable inference of read orientation.
+     - |  
+       | Minimum number of mapped reads to ensure
+       | reliable inference of read orientation.
    * - :code:`--read-orientation-min-fraction`
-     - Minimum fraction (must exceed 0.5) of reads supporting a given orientation to confirm its accuracy.
+     - |  
+       | Minimum fraction (must exceed 0.5) of reads
+       | supporting a given orientation to confirm its accuracy.