forked from ropensci/codemetar
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathREADME.Rmd
More file actions
114 lines (69 loc) · 4.93 KB
/
README.Rmd
File metadata and controls
114 lines (69 loc) · 4.93 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
---
output: github_document
---
[](http://www.repostatus.org/#active)
[](https://travis-ci.org/ropensci/codemetar)
[](https://ci.appveyor.com/project/cboettig/codemetar/branch/master)
[](https://codecov.io/github/ropensci/codemetar?branch=master)
[](https://cran.r-project.org/package=codemetar)
[](https://github.com/ropensci/onboarding/issues/130)
[](https://zenodo.org/badge/latestdoi/86626030)
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
message = FALSE,
comment = "",
fig.path = "tools/README-"
)
```
# codemetar
The goal of codemetar is to generate the JSON-LD file, `codemeta.json` containing software metadata describing an R package. For more general information about the CodeMeta Project for defining software metadata, see <https://codemeta.github.io>. In particular, new users might want to start with the [User Guide](https://codemeta.github.io/user-guide/), while those looking to learn more about JSON-LD and consuming existing codemeta files should see the [Developer Guide](https://codemeta.github.io/developer-guide/).
## Installation
You can install the latest version from CRAN using:
```{r cran-installation, eval = FALSE}
install.packages("codemetar")
```
You can also install the development version of `codemetar` from github with:
```{r gh-installation, eval = FALSE}
# install.packages("devtools")
devtools::install_github("ropensci/codemetar")
```
```{r}
library("codemetar")
```
## Example
This is a basic example which shows you how to generate a `codemeta.json` for an R package (e.g. for `testthat`):
```r
write_codemeta("testthat")
```
`codemetar` can take the path to the package root instead. This may allow `codemetar` to glean some additional information that is not available from the description file alone.
```r
write_codemeta(".")
```
Which creates a file looking like so (first 10 lines; see full [codemeta.json here](https://github.com/codemeta/codemetar/blob/master/codemeta.json)):
```{r echo = FALSE}
cat(readLines("codemeta.json", n = 10), sep="\n")
```
## Modifying or enriching CodeMeta metadata
The best way to ensure `codemeta.json` is as complete as possible is to begin by making full use of the fields that can be set in an R package DESCRIPTION file, such as `BugReports` and `URL`. Using the `Authors@R` notation allows a much richer specification of author roles, correct parsing of given vs family names, and email addresses.
In the current implementation, developers may specify an ORCID url for an author in the optional `comment` field of `Authors@R`, e.g.
```
Authors@R: person("Carl", "Boettiger", role=c("aut", "cre", "cph"), email="cboettig@gmail.com", comment="http://orcid.org/0000-0002-1642-628X")
```
which will allow `codemetar` to associate an identifier with the person. If the package is hosted on CRAN, including the ORCiD in this way will cause an ORCiD logo and link to the ORCiD page to be added to the package CRAN webpage.
### Using the DESCRIPTION file
The DESCRIPTION file is the natural place to specify any metadata for an R package. The `codemetar` package can detect certain additional terms in the [CodeMeta context](https://codemeta.github.io/terms). Almost any additional codemeta field (see `codemetar:::additional_codemeta_terms` for a list) and can be added to and read from the DESCRIPTION into a `codemeta.json` file.
CRAN requires that you prefix any additional such terms to indicate the use of `schema.org` explicitly, e.g. `keywords` would be specified in a DESCRIPTION file as:
```
X-schema.org-keywords: metadata, codemeta, ropensci, citation, credit, linked-data
```
Where applicable, these will override values otherwise guessed from the source repository. Use comma-separated lists to separate multiple values to a property, e.g. keywords.
See the [DESCRIPTION](https://github.com/codemeta/codemetar/blob/master/DESCRIPTION) file of the `codemetar` package for an example.
```{r include=FALSE}
#unlink("codemeta.json")
```
## Going further
Check out all the [codemetar vignettes](https://codemeta.github.io/codemetar/articles/index.html) for tutorials on other cool stuff you can do with codemeta and json-ld.
[](https://ropensci.org)