Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update RtD guides #172

Merged
merged 25 commits into from
Nov 20, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
21695ca
docs: update RtD page
balajtimate Sep 19, 2024
eac14ed
docs: add installation guide
balajtimate Sep 19, 2024
acba203
docs: add usage and examples pages
balajtimate Oct 21, 2024
cc56fa4
Merge branch 'dev' of https://github.com/zavolanlab/htsinfer into doc…
balajtimate Oct 21, 2024
488d4b7
docs: update guides
balajtimate Oct 21, 2024
f9a1a3b
docs: update README
balajtimate Oct 21, 2024
f1b4b4c
docs: update guides
balajtimate Oct 21, 2024
206d146
fix README badges
balajtimate Oct 24, 2024
797c596
Merge branch 'dev' of https://github.com/zavolanlab/htsinfer into doc…
balajtimate Oct 30, 2024
db6bd5c
docs: update README, guides
balajtimate Oct 31, 2024
2b17aca
update version
balajtimate Oct 31, 2024
b3d5d05
update rtd config
balajtimate Nov 4, 2024
4623fe2
update versioning
balajtimate Nov 13, 2024
6bfcf1a
remove docker image and build
balajtimate Nov 13, 2024
89da34f
update readme
balajtimate Nov 13, 2024
47f3842
update versioning
balajtimate Nov 13, 2024
1252899
update guides
balajtimate Nov 15, 2024
f36c812
update usage guide with tables
balajtimate Nov 15, 2024
21f72f0
update Results model description
balajtimate Nov 15, 2024
3971d5e
docs: update index, restructure API docs
balajtimate Nov 15, 2024
140c918
update style
balajtimate Nov 15, 2024
8223260
docs: update guides, README
balajtimate Nov 18, 2024
316c173
update conf exclusions
balajtimate Nov 18, 2024
d9f56fa
update conf exclusions
balajtimate Nov 18, 2024
f231a54
update conf exclusions
balajtimate Nov 18, 2024
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 0 additions & 8 deletions .dockerignore

This file was deleted.

35 changes: 0 additions & 35 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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/[email protected]
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"
2 changes: 1 addition & 1 deletion .readthedocs.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ build:
tools:
python: "mambaforge-4.10"
sphinx:
configuration: docs/api/conf.py
configuration: docs/conf.py
formats:
- pdf
- epub
Expand Down
48 changes: 0 additions & 48 deletions Dockerfile

This file was deleted.

115 changes: 40 additions & 75 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand All @@ -169,20 +129,25 @@ by email: <[email protected]>

(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>
4 changes: 4 additions & 0 deletions docs/_static/custom.css
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
/* Increase font size for toctree elements */
.toctree-l1 {
font-size: 18px; /* Adjust the size as needed */
}
24 changes: 0 additions & 24 deletions docs/api/index.rst

This file was deleted.

14 changes: 9 additions & 5 deletions docs/api/conf.py → docs/conf.py
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
from htsinfer import __version__
from htsinfer.version import __version__

# Configuration file for the Sphinx documentation builder.
#
Expand All @@ -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 -----------------------------------------------------
Expand All @@ -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.
Expand All @@ -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'
Expand All @@ -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 -------------------------------------------------------------
Expand All @@ -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')
Loading
Loading