diff --git a/docs/articles/cputools.R b/docs/articles/cputools.R index 140f6fd..fb9f442 100644 --- a/docs/articles/cputools.R +++ b/docs/articles/cputools.R @@ -22,10 +22,10 @@ makeTravisShield("cputools", user = "ComputationalProteomicsUnit") makeTravisShield("cputools", user = "ComputationalProteomicsUnit") ## ----pkgqst0, eval=TRUE---------------------------------------------------- -pkgqsts("cputools", level = 2L) +pkgqsts("cputools", level = 2L, user = "ComputationalProteomicsUnit") ## ----pkgqst, eval=TRUE, results='asis'------------------------------------- -pkgqsts("cputools", bioc=FALSE, level = 2L) +pkgqsts("cputools", bioc=FALSE, level = 2L, user = "ComputationalProteomicsUnit") ## ----si-------------------------------------------------------------------- sessionInfo() diff --git a/docs/articles/cputools.html b/docs/articles/cputools.html index 509576c..675371a 100644 --- a/docs/articles/cputools.html +++ b/docs/articles/cputools.html @@ -80,6 +80,23 @@

This vignette summarises some good practice for R programming and package development. I tend to follow these myself and advise my collaborators to use them when we work on projects together.

library("cputools")

See also the CPU wiki for a non-exhaustive list.

+
+

+ GitHub user

+

Several function in the cputools package require a GitHub user name to generate correct links to the software’s page using makeGithubUrl, for example. The user name, when not provided explicitly, is fetched from the session options with options("GitHubUserName"), which can be set in your .Rprofile using

+
options(GitHubUserName = "ComputationalProteomicsUnit")
+

If set, one can just call this function above with

+
makeGithubUrl("cputools")
+

Otherwise, the user can be specified explicitly with

+
makeGithubUrl("cputools", user = "ComputationalProteomicsUnit")
+
+ +
+

+ Credibility

+

Demonstrate good programming skills by writing clean and maintainable code, provide good documentation and follow good community practice. I would recommend to follow the Bioconductor guidelines for package development and submission, in particular good documentation, vignettes and unit testing. I would also add continous integration (see below) to this.

+

An essential aspect is to officially release the package. This can be done by submitting it to a public package repository such as CRAN or Biocondcutor. For any package related to high throughput biology, acceptance to Bioconductor is becoming, in my opinion, a requirement. It doesn’t mean that there aren’t any good biology-related packages that are not in Bioconductor, or that all packages in Bioconductor are first class packages, but any serious package developer should ideally develope a package that matches Bioconductor standards and review. A package that is only available on a personal web page might not be reagarded positively in a first instance; a package that has passed a well defined and formal review process (and has been looked at by an experience R developer, which is probably more that most of the bioinformatics tools available out there), shows that the authors cared enough about his work to polish it to Bioconductor standards.

+

If the package is not to be submitted to Bioconductor (in particular if it doesn’t fall into the project’s remit), then the developer should implement their own continous integration system (see below) to demonstrate that the package successfully builds/checks on a third-party infrastructure, ideally on different systems.

@@ -142,10 +159,9 @@

Bioconductor shields

If the package is on Biocondcutor, then the build/check status and testing coverage will be provided by them and the shields can be directly generated with the makeBiocBuildShield and makeBiocCovrShield. Below is an example for the hpar package.

makeBiocBuildShield("hpar")
-
## [![Bioconductor devel build status](http://bioconductor.org/shields/build/devel/bioc/hpar.svg)](http://bioconductor.org/packages/devel/bioc/html/hpar.html)
+

Bioconductor devel build status

makeBiocCovrShield("hpar")
-
## [![Bioconductor devel build status](https://bioconductor.org/shields/coverage/devel/hpar.svg)](https://codecov.io/github/Bioconductor-mirror/hpar/branch/master)
-

Bioconductor devel build status Bioconductor devel build status

+

Bioconductor devel build status

By default, the shields for the devel branch are produced. Use branch = "release" to use the release branch.

If your package is on Bioconductor, display the build and coverage shields.

@@ -156,7 +172,6 @@

Travis shield

If the package is not on Bioconductor, you’ll have to set up a continuous integration server that automatically builds and checks your package. I recommend travis-ci for linux (and OSX, although I haven’t successfully used that myself) and appveyor for windows to build/check the package and covr and codecov for test coverage.

makeTravisShield("cputools", user = "ComputationalProteomicsUnit")
-
## [![Build Status](https://travis-ci.org/ComputationalProteomicsUnit/cputools.svg?branch=master)](https://travis-ci.org/ComputationalProteomicsUnit/cputools)

Build Status

Add a travis build/check shield, unless there’s already a Bioconductor shield.

@@ -172,13 +187,13 @@

Asking for help

It is important to provide a venue for users to ask for help and report bugs. I tend to use two channels for that, namely GitHub issues and, for Bioconductor package, the Bioconductor support site. The pkgqsts function will create a default section (level 2 below, default is 1):

-
pkgqsts("cputools", level = 2L)
+
pkgqsts("cputools", level = 2L, user = "ComputationalProteomicsUnit")
## ## Questions and support
 ## To get help:
 ##  - Open a GitHub [issue](https://github.com/ComputationalProteomicsUnit/cputools/issues)
 ##  - Post your question on the [Bioconductor support site](https://support.bioconductor.org/)

As this package is not on Bioconductor, the Bioconductor support site is disables with bioc = FALSE and rendered as shown below.

-
pkgqsts("cputools", bioc=FALSE, level = 2L)
+
pkgqsts("cputools", bioc=FALSE, level = 2L, user = "ComputationalProteomicsUnit")

Questions and support

@@ -256,7 +271,12 @@

Contents

    -
  • Introduction
    • +
  • +Introduction +
    • +
  • Credibility
  • DESCRIPTION
  • README files
  • Code versioning, dissemination and issues
    • diff --git a/docs/articles/cputools.md b/docs/articles/cputools.md index 7537dbf..74b1f5b 100644 --- a/docs/articles/cputools.md +++ b/docs/articles/cputools.md @@ -39,6 +39,66 @@ See also the [CPU wiki](https://github.com/ComputationalProteomicsUnit/cputools/wiki) for a non-exhaustive list. +## GitHub user + +Several function in the `cputools` package require a GitHub user name +to generate correct links to the software's page using +`makeGithubUrl`, for example. The user name, when not provided +explicitly, is fetched from the session options with +`options("GitHubUserName")`, which can be set in your `.Rprofile` +using + + +```r +options(GitHubUserName = "ComputationalProteomicsUnit") +``` + +If set, one can just call this function above with + + +```r +makeGithubUrl("cputools") +``` + +Otherwise, the user can be specified explicitly with + + +```r +makeGithubUrl("cputools", user = "ComputationalProteomicsUnit") +``` + +# Credibility + +Demonstrate good programming skills by writing clean and maintainable +code, provide good documentation and follow good community practice. I +would recommend to follow the +[Bioconductor guidelines](https://bioconductor.org/developers/package-guidelines/) +for package development and submission, in particular good +documentation, vignettes and unit testing. I would also add continous +integration (see below) to this. + +An essential aspect is to officially release the package. This can be +done by submitting it to a public package repository such as CRAN or +Biocondcutor. For any package related to high throughput biology, +acceptance to Bioconductor is becoming, in my opinion, a +requirement. It doesn't mean that there aren't any good +biology-related packages that are not in Bioconductor, or that all +packages in Bioconductor are first class packages, but any serious +package developer should ideally develope a package that matches +Bioconductor standards and review. A package that is only available on +a personal web page might not be reagarded positively in a first +instance; a package that has passed a well defined and formal review +process (and has been looked at by an experience R developer, which is +probably more that most of the bioinformatics tools available out +there), shows that the authors cared enough about his work to polish +it to Bioconductor standards. + +If the package is not to be submitted to Bioconductor (in particular +if it doesn't fall into the project's remit), then the developer +should implement their own continous integration system (see below) to +demonstrate that the package successfully builds/checks on a +third-party infrastructure, ideally on different systems. + # DESCRIPTION > Use `Authors@R` to define authors and their respective roles. @@ -132,19 +192,12 @@ directly generated with the `makeBiocBuildShield` and makeBiocBuildShield("hpar") ``` -``` -## [![Bioconductor devel build status](http://bioconductor.org/shields/build/devel/bioc/hpar.svg)](http://bioconductor.org/packages/devel/bioc/html/hpar.html) -``` +[![Bioconductor devel build status](http://bioconductor.org/shields/build/devel/bioc/hpar.svg)](http://bioconductor.org/packages/devel/bioc/html/hpar.html) ```r makeBiocCovrShield("hpar") ``` -``` -## [![Bioconductor devel build status](https://bioconductor.org/shields/coverage/devel/hpar.svg)](https://codecov.io/github/Bioconductor-mirror/hpar/branch/master) -``` - -[![Bioconductor devel build status](http://bioconductor.org/shields/build/devel/bioc/hpar.svg)](http://bioconductor.org/packages/devel/bioc/html/hpar.html) [![Bioconductor devel build status](https://bioconductor.org/shields/coverage/devel/hpar.svg)](https://codecov.io/github/Bioconductor-mirror/hpar/branch/master) By default, the shields for the devel branch are produced. Use `branch @@ -168,10 +221,6 @@ appveyor for windows to build/check the package and makeTravisShield("cputools", user = "ComputationalProteomicsUnit") ``` -``` -## [![Build Status](https://travis-ci.org/ComputationalProteomicsUnit/cputools.svg?branch=master)](https://travis-ci.org/ComputationalProteomicsUnit/cputools) -``` - [![Build Status](https://travis-ci.org/ComputationalProteomicsUnit/cputools.svg?branch=master)](https://travis-ci.org/ComputationalProteomicsUnit/cputools) > Add a travis build/check shield, unless there's already a @@ -183,8 +232,6 @@ manually. ## Bioc and/or travis - - # Asking for help It is important to provide a venue for users to ask for help and @@ -195,13 +242,13 @@ default is 1): ```r -pkgqsts("cputools", level = 2L) +pkgqsts("cputools", level = 2L, user = "ComputationalProteomicsUnit") ``` ``` ## ## Questions and support ## To get help: -## - Open a GitHub [issue](https://github.com/lgatto/cputools/issues) +## - Open a GitHub [issue](https://github.com/ComputationalProteomicsUnit/cputools/issues) ## - Post your question on the [Bioconductor support site](https://support.bioconductor.org/) ``` @@ -210,12 +257,12 @@ is disables with `bioc = FALSE` and rendered as shown below. ```r -pkgqsts("cputools", bioc=FALSE, level = 2L) +pkgqsts("cputools", bioc=FALSE, level = 2L, user = "ComputationalProteomicsUnit") ``` ## Questions and support To get help: - - Open a GitHub [issue](https://github.com/lgatto/cputools/issues) + - Open a GitHub [issue](https://github.com/ComputationalProteomicsUnit/cputools/issues) > Add a *Questions and support* section. @@ -239,7 +286,8 @@ resources to guide users: - [How to write a reproducible example](http://adv-r.had.co.nz/Reproducibility.html) To update or discuss this, please use this -issue[^https://github.com/ComputationalProteomicsUnit/cputools/issues/3] +issue^[https://github.com/ComputationalProteomicsUnit/cputools/issues/3] +or send directly a pull request. # Testing coverage diff --git a/docs/reference/makeFigName.html b/docs/reference/makeFigName.html index b4094e4..2cc124e 100644 --- a/docs/reference/makeFigName.html +++ b/docs/reference/makeFigName.html @@ -118,7 +118,7 @@

    Details

    Examples

    - 
    makeFigName("foo")
    #> [1] "./Fig-foo-Tue-Jan-10-11:45:58-2017.pdf"
    makeFigName("foo", date = FALSE)
    #> [1] "./Fig-foo.pdf"
    makeDatName("foo", date = FALSE)
    #> [1] "./Dat-foo.rda"
    makeFigName("foo", path = "~/projects/big-project/figs")
    #> [1] "~/projects/big-project/figs/Fig-foo-Tue-Jan-10-11:45:58-2017.pdf"
    makeDatName("foo", path = "~/projects/big-project/Data")
    #> [1] "~/projects/big-project/Data/Dat-foo-Tue-Jan-10-11:45:58-2017.rda"
    + 
    makeFigName("foo")
    #> [1] "./Fig-foo-Tue-Jan-10-17:33:03-2017.pdf"
    makeFigName("foo", date = FALSE)
    #> [1] "./Fig-foo.pdf"
    makeDatName("foo", date = FALSE)
    #> [1] "./Dat-foo.rda"
    makeFigName("foo", path = "~/projects/big-project/figs")
    #> [1] "~/projects/big-project/figs/Fig-foo-Tue-Jan-10-17:33:03-2017.pdf"
    makeDatName("foo", path = "~/projects/big-project/Data")
    #> [1] "~/projects/big-project/Data/Dat-foo-Tue-Jan-10-17:33:03-2017.rda"