Orchestrating Microbiome Analysis Book

Overview

This is a reference cookbook for performing Microbiome Analysis with Bioconductor in R. This is a book based on Quarto and BiocBook (https://www.bioconductor.org/packages/release/bioc/html/BiocBook.html).

Deployment

The book is automatically built and deployed from the devel branch to the gh-pages branch using GitHub Actions.

You can also preview it locally after cloning this Github repository. This is useful for instance if you like to suggest improvements in the material. You can use this to test the build before making a pull request to add your new changes in the official release.

Building and viewing the book locally involves the following steps:

Install the necessary dependencies to build to book, if necessary:

BiocManager::install(remotes::local_package_deps(dependencies=TRUE))
devtools::install('.')

Render and view the book:

BiocBook::preview(BiocBook::BiocBook('.'))

Development and Contributions

To contribute reports, follow the Git flow procedure (you can see instructions to getting started with Github):

Fork the project
Clone your fork
Modify the material. Check that the code runs successfully.
Check locally that the changes render successfully (see above)
Add and commit the changes to your fork
Create a pull request (PR) from your fork back to the original repo
Fix and discuss issues in the review process

You can set OMA devel branch as your upstream branch and pull the changes from that before making new Pull Requests (see below). This way you can make sure that your local version is in sync with the latest full release.

Setting upstream

After you forked OMA, you have two repositories to care about:

origin: your own Github fork of OMA, under your github account
upstream: devel branch of OMA

The origin you have after you cloned your own fork.

The upstream you can set on command line as follows, for instance (and you can educate yourself more through various online resources on using Git/hub):

git remote add upstream git@github.com:microbiome/OMA.git

Pull changes from the origin and upstream to your local version:

git fetch --all
git merge origin/devel
git merge upstream/devel

Sync your local version with the origin and upstream:

git add . 
git commit -am "my changes"

Push your changes to origin:

git push origin devel

After this you can open a PR from origin to the official devel branch in Github.

Adding new sections

Please note that chapters should be independent of each other.

Create the relevant .qmd file; follow the numbering logic.
Add it also to the list in file inst/assets/_book.yml.
Add any new dependency you use to the DESCRIPTION file.

Styling

Use a coding style consistent with the rest of the book. It makes the book look coherent.
Use quarto-styling instead or Rmarkdown style in code options. See quarto execution options.
All chunks should have labels. It is easier to see for instance which chunk is causing problems.
Focus on interpreting the results, as this is often what readers find most helpful and clarifying.
Use callout blocks where possible. They enhance the book's appearance and help structure the text effectively. See quarto callout blocks.
Use the following style: `package` and `function()`.
The text lines should not exceed 80 characters.
The code lines should not exceed 80 characters. Code exceeding this limit does not fit to html pages correctly.

Instead of this

long_variable_name <- long_function_name(parameter = "parameter".
                                         parameter2 = "parameter2")

use the following styling

long_variable_name <- long_function_name(
    parameter = "parameter".
    parameter2 = "parameter2"
	)

Code of conduct

Please note that the OMA project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

artur-sannikov/OMA