https://github.com/moodymudskipper/alt.doc

Alternative help files.
https://github.com/moodymudskipper/alt.doc

Last synced: 17 days ago
JSON representation

Alternative help files.

• Host: GitHub
• URL: https://github.com/moodymudskipper/alt.doc
• Owner: moodymudskipper
• Created: 2023-07-19T12:23:14.000Z (over 1 year ago)
• Default Branch: main
• Last Pushed: 2023-07-19T12:52:16.000Z (over 1 year ago)
• Last Synced: 2024-08-13T07:11:05.834Z (4 months ago)
• Language: R
• Size: 25.4 KB
• Stars: 1
• Watchers: 2
• Forks: 0
• Open Issues: 1
• Metadata Files:
  • Readme: README.Rmd

Awesome Lists containing this project

• jimsghstars - moodymudskipper/alt.doc - Alternative help files. (R)

README

        
---

output: github_document

---

```{r, include = FALSE}

knitr::opts_chunk$set(

  collapse = TRUE,

  comment = "#>",

  fig.path = "man/figures/README-",

  out.width = "100%"

)

```

# alt.doc

{alt.doc} contains no useful function. Only alternative documentation. It has no

strong dependency.

Install with:

``` r

remotes::install_github("moodymudskipper/alt.doc")

```

Then in your R profile call `requireNamespace("alt.doc", quietly = TRUE)`. This will make all

help files accessible silently and without attaching the package.

# Why

R has a handful of objects that are not extensively documented, many prefixed by a dot

and aimed at advanced users.

Keeping the doc terse is sometimes a choice, more to read might mean it's not as easy to

access the essential information. However we feel some topics are insufficiently documented 

and we propose alternative documentation for those.

This will be work in progress for a long time, or forever.

# contribute

We make it convenient to work on the project a few minutes at a time.

* Clone the repo : `usethis::create_from_github("moodymudskipper/alt.doc", "~/path/to/alt.doc")`

* Set in your R profile `options(alt.doc.path = "path/to/alt.doc")` : `usethis::edit_r_profile()`

* Call `alt.doc::new_doc(some.function)` to create a new script in your {alt.doc} project,

  following a convenient template, or open the script if it already exists.

* Call `alt.doc::sync()` to reinstall, and make your new doc available

* Call `alt.doc::pr(some.function)` to commit changes to a newly created branch, check out the 

  main branch back and open a webpage to a new PR .

The package only has these 3 exported functions and you're not expected to ever need `library(alt.doc)`,

Some loose guidelines :

* If possible give a descriptive title to the help file rather than the function name,

that makes the index of this package more helpful.

* One R script per documentation page, one documentation page per script.

* We might document several functions per help file when it makes sense (e.g. `registerS3method`

and `registerS3methods`).

* It's ok to have help files for non base functions 

* Sometimes a contribution to R itself might be more fitting, especially if there

are mistakes in the doc, use your judgement.

* It's ok to reference non base functions, like tidyverse or data.table equivalent