Skip to content

Commit

Permalink
Merge branch 'main' into governance
Browse files Browse the repository at this point in the history
  • Loading branch information
@maelle
maelle authored Dec 9, 2024
2 parents 298b3d8 + aa902f2 commit 6d93928
Show file tree
Hide file tree
Showing 12 changed files with 154 additions and 101 deletions.
51 changes: 25 additions & 26 deletions browse/api.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,26 +2,25 @@
title: "Programmatic access (APIs)"
---

R-universe offers several APIs.
There is no authentication.
R-universe provides several APIs for programmatic access, requiring no authentication.
Thanks to the APIs you can list universes, packages in an universe, get information on packages, perform searches.

You can call the API as you prefer:
You can interact with the API in two ways:
- Create API calls "manually" in the command-line or R.
- Use the [universe R package](https://docs.ropensci.org/universe/) available from rOpenSci's R-universe.

- creating your API calls "manually" in the command-line or R;
- using the [universe R package](https://docs.ropensci.org/universe/) available from rOpensci R-universe.

On this page we'll show examples using {httr2} or {universe} directly.
This page demonstrates usage with `{httr2}` or `{universe}` directly.

## Universe-specific APIs

The URL of these APIs start with the universe URL.
Here we will often use `https://jeroen.r-universe.dev` as an example but you can replace it with any universe URL.
API endpoints start with the universe URL.
This documentation uses `https://jeroen.r-universe.dev` as an example, but you can replace it with any universe URL.

### List of all universes

URL: `https://r-universe.dev/stats/everyone`

Example
Example using `{httr2}`:

```{r}
universes <- httr2::request("https://r-universe.dev/stats/everyone") |>
Expand All @@ -33,7 +32,7 @@ head(universes[["universes"]])
head(universes[["maintainers"]])
```

Or:
Example using `{universe}`:

```{r}
universe::everyone() |> head()
Expand All @@ -45,7 +44,7 @@ universe::everyone(type = "maintainers") |> head()

URL: `https://<username>.r-universe.dev/api/ls`

Example
Example using `{httr2}`:

```{r}
packages <- httr2::request("https://jeroen.r-universe.dev/api/ls") |>
Expand All @@ -55,7 +54,7 @@ packages <- httr2::request("https://jeroen.r-universe.dev/api/ls") |>
str(packages)
```

Or:
Example using `{universe}`:

```{r}
packages <- universe::universe_ls("jeroen")
Expand All @@ -68,9 +67,9 @@ URL: `https://<username>.r-universe.dev/api/packages`

Parameters:

- limit: the number of results to return, by default a maximum of 100. You can use the [ls endpoint](#ls) to determine the total number of packages in the universe and set that as a limit.
- limit: Maximum number of results (default: 100). Use the [ls endpoint](#ls) to determine the total number of packages and adjust the limit accordingly.

Example:
Example using `{httr2}`:

```{r}
packages <- httr2::request("https://jeroen.r-universe.dev/api/packages") |>
Expand All @@ -81,7 +80,7 @@ packages <- httr2::request("https://jeroen.r-universe.dev/api/packages") |>
str(packages[[1]], max.level = 1)
```

Or:
Example using `{universe}`:

```{r}
packages <- universe::universe_all_packages("jeroen")
Expand All @@ -93,7 +92,7 @@ str(packages[[1]], max.level = 1)

URL: `https://<username>.r-universe.dev/api/packages/<package>`

Example:
Example using `{httr2}`:

```{r}
v8 <- httr2::request("https://jeroen.r-universe.dev/api/packages/V8") |>
Expand All @@ -104,7 +103,7 @@ v8 <- httr2::request("https://jeroen.r-universe.dev/api/packages/V8") |>
str(v8, max.level = 1)
```

Or:
Example using `{universe}`:

```{r}
V8 <- universe::universe_one_package("jeroen", "V8")
Expand All @@ -117,12 +116,12 @@ str(V8, max.level = 1)
URL: `https://<username>.r-universe.dev/api/search`
Parameters:

- q: the query string. You can use the [advanced fields](/browse/search.html).
- limit: the number of results to return, by default a maximum of 100 but you can
- do a first request to determine the total number of hits `N`, returned in the response as the `total` field,
- then do a second request using `limit=N`.
- q: Query string (supports [advanced fields](/browse/search.html)).
- limit: Maximum number of results (default: 100). To retrieve all results:
- Perform an initial query to get the value `total` field.
- Perform a second query with `limit=total`.

Example:
Using `{httr2}`:

How many packages in the rOpenSci universe depend on httr2?

Expand All @@ -137,7 +136,7 @@ str(deps, max.level = 1)
deps$total
```

Or:
Using `{universe}`:

```{r}
deps <- universe::universe_search("ropensci", query = 'needs:httr2')
Expand All @@ -157,7 +156,7 @@ Parameters:
- do a first request to determine the total number of hits `N`, returned in the response as the `total` field,
- then do a second request using `limit=N`.

Example:
Example using `{httr2}`:

```{r}
packages <- httr2::request("https://r-universe.dev/api/search") |>
Expand All @@ -169,7 +168,7 @@ str(packages, max.level = 1)
str(packages$results[[1]])
```

Or:
Example using `{universe}`:

```{r}
packages <- universe::global_search(query = '"weather data"', limit = 100L)
Expand Down
22 changes: 11 additions & 11 deletions browse/get-started.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,20 +2,20 @@
title: "A catalogue of R packages"
---

R-universe can be your entry point to many R packages.
R-universe is a collection of universes, each of them featuring the packages of a team or individual.
R-universe serves as your gateway to discovering a wide variety of R packages.
R-universe is a collection of **universes**, each representing the packages maintained by an individual or team.

You can search packages, and assess them thanks to all the information provided on universe and package pages.
Find out more about the three levels of navigation in R-universe:
You can search for packages and evaluate them using the detailed information provided on universe and package pages.
Explore the three levels of navigation within R-universe:

- [searching the entire R ecosystem](/browse/search.html)
- [browsing work from a maintainer or organization](/browse/universes.html)
- [individual package information](/browse/packages.html)
- [Search the entire R ecosystem](/browse/search.html)
- [Browse work from a specific maintainer or organization](/browse/universes.html)
- [Access detailed information about individual packages](/browse/packages.html)

:::{.callout-caution}
R-universe does not vet packages: it is an open publishing system.
The system builds and deploys R packages from Git repositories into installation repositories.
The owner of the universe is responsible for their own policies and quality control.
R-universe does not vet packages; it is an open publishing system.
The platform builds and deploys R packages from Git repositories into installation repositories.
The responsibility for policies and quality control lies solely with the owner of each universe.
:::

With R-universe, you can also follow updates thanks to [RSS feeds](/browse/rss-feeds.html).
Stay up-to-date with the latest developments by following [RSS feeds](/browse/rss-feeds.html).
30 changes: 22 additions & 8 deletions browse/packages.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,25 @@
title: "Individual package information"
---

Clicking on a package in search results or in a universe overview will lead you to the [homepage for that package](/browse/packages.html). You can also link to this page directly via the url `https://{owner}.r-universe.dev/{package}`.
Clicking on a package in search results or in a universe overview will take you to the [homepage for that package](/browse/packages.html). You can also link to this page directly using the url `https://{owner}.r-universe.dev/{package}`.


## Package Homepage

![Landing page for the sf package](../img/pkg-.png){group="pkg" fig-alt="Landing page for the sf package, displaying much information including installation instructions."}

![Citation for the sf package](../img/pkg-citation.png){group="pkg" fig-alt="Citation for the sf package."}

These package pages are generated automatically and provide detailed information about each project, and all the information and resources to quickly install and try the package locally in R.
Each package page is automatically generated and provides:
- Detailed information about the project,
- Installation instructions for quick setup in R,
- Other relevant resources.

## Website tour

To familiarize yourself with the information provided on the R-universe page of each package you can read this documentation chapter but also follow the "Website Tour".
Click on the "Website Tour" button in the navbar.
To explore the information provided on the R-universe page for each package, you can:
- Read this documentation chapter, or
- Click the "Website Tour" button in the navbar for an interactive guide.

## Package information

Expand All @@ -28,9 +35,12 @@ If specified, we also show how the package should be cited in papers.

### How are the dependencies / dependents calculated?

Both are calculated using transitive (recursive) strong dependencies, hence this includes both direct and indirect dependencies. Or in practical terms: other packages that need to be installed at minimum to be able to use the target package.
Dependencies and dependents are derived using transitive (recursive) strong dependencies. Hence this includes both direct and indirect dependencies.

At package build time, we use `tools::package_dependencies(pkg, recursive = TRUE)` to derive the list of hard dependencies and store this in the database. R-base packages are not included. The `dependencies` value is simply the size of this list. The `dependents` value is the opposite: this is the number of packages in R-universe which list the target package as one of its dependencies.
- Dependencies: Other packages required to use the target package.
- Dependents: Packages listing the target package as a dependency.

At package build time, we use `tools::package_dependencies(pkg, recursive = TRUE)` to compute the list of hard dependencies, excluding R-base packages. The size of this list determines the `dependencies` value, while the `dependents` value reflects the number of packages in R-universe depending on the target package.


### How does R-universe analyze system dependencies (C/C++)
Expand All @@ -56,15 +66,15 @@ The maketools vignette explains this in more detail: [Automatically determine ru

## All the documentation

To let you start using packages as quickly as possible, R-universe renders all available documentation and presents this as clear and concisely as possible on the homepage.
R-universe renders and presents all available documentation to help you start using packages quickly.

![README of the sf package](../img/pkg-readme.png){group="pkg" fig-alt="README of the sf package."}

![Manual of the sf package](../img/pkg-manual.png){group="pkg" fig-alt="Manual of the sf package, displaying a list of all functions in the package, hyperlinked."}
![Documentation of one function of the sf package](../img/pkg-function-doc.png){group="pkg" fig-alt="Documentation of one function of the sf package."}


Most R packages have 3 forms of documentation: a README file, a reference manual (help pages), and a number of articles (vignettes).
Most R packages have 3 forms of documentation: a README file, a reference manual (help pages), and a number of articles (including vignettes).
These articles are often a good place to get started, and are listed on the package homepage right under the descriptives.
From here you can view both the rendered html/pdf document, as well as the rmarkdown source file used to (re)produce the article.

Expand Down Expand Up @@ -143,6 +153,10 @@ Note that not all packages have a `devel` version available. CRAN packages that

## Usage and development activity

::: {.callout-warning}
The information on development is only accurate if the developers push to the tracked Git repository. If for instance a maintainer updates a package on Bioconductor or CRAN without updating the Git repository, the information on R-universe will be stale.
:::

Besides familiarizing yourself with what the package does, you may be interested in who is working on it, who else is using it, and if it is still actively developed.

![Development information the sf package](../img/pkg-development.png){group="pkg" fig-alt="Development information the sf package"}
Expand Down
21 changes: 12 additions & 9 deletions browse/rss-feeds.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,18 @@
title: "RSS feeds of package updates"
---

The /feed.xml endpoint on any R-universe domain gives an RSS feed of recent R package updates in the repository:

- https://ropensci.r-universe.dev/feed.xml
- https://tidyverse.r-universe.dev/feed.xml
- https://jeroen.r-universe.dev/feed.xml

Each feed item contains the name and version of the updated R package, along with a timestamp and a link to the build log of the most recent commit.
The feed also contains some additional metadata such as the package description, and a list of the articles (vignettes) contained in the package.

The `/feed.xml` endpoint on any R-universe domain provides an RSS feed of recent R package updates in the repository.

Examples:
- [ropensci.r-universe.dev/feed.xml](https://ropensci.r-universe.dev/feed.xml)
- [tidyverse.r-universe.dev/feed.xml](https://tidyverse.r-universe.dev/feed.xml)
- [jeroen.r-universe.dev/feed.xml](https://jeroen.r-universe.dev/feed.xml)

Each feed item includes:
- The name and version of the updated R package,
- A timestamp,
- A link to the build log for the most recent commit, and
- Additional metadata such as the package description and a list of articles (vignettes) in the package.

```{r, echo=FALSE, results='asis'}
url <- "https://jeroen.r-universe.dev/feed.xml"
Expand Down
31 changes: 15 additions & 16 deletions browse/search.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@
title: "Search for packages"
---

You can search for packages via <https://r-universe.dev/search/> using keywords or author names.
If you want to use an exact phrase like "weather data", you must use double quotes, not single quotes, around it.
The search bar includes an arrow-down button that allows to access the advanced search fields.
You can search for packages via <https://r-universe.dev/search/> using keywords or author names.
To search for an exact phrase like "weather data," use **double quotes** instead of single quotes.
The search bar includes a drop-down button for accessing advanced search fields.

![Search landing page](../img/search.png){group="search" fig-alt="Search landing page, with a search box"}

Expand All @@ -26,24 +26,23 @@ At the time of writing it includes:
- Number of unique contributors;
- Commit activity over the last year;
- Downloads per month from CRAN or Bioconductor mirrors;
- Number of files on GitHub that mention ’library(pkgname)'.
- Number of files on GitHub that mention 'library(pkgname)'.

You can browse [scores and metrics for all packages](https://r-universe.dev/packages).

We plan to keep updating the algorithm as R-universe matures and better data becomes available.

## Why is a package sometimes listed twice?

If a source package fails to build (which means something is very wrong) then you see a red “build failure” message.
If there was a previous successful build, it is kept there as well for users to install.
You can explore [scores and metrics for all packages](https://r-universe.dev/packages).
The algorithm will evolve as R-universe matures and better data becomes available.

## Which packages get included in search? {#deduplication}

In R-universe, a given R package can be included in many different registries. To prevent duplicates, search only shows packages from the universes of the upstream GitHub owners of the package, and not from third parties that have added a copy of the package to their registry.
In R-universe, a given R package can appear in multiple registries.
To avoid duplicates, search results only display packages from the upstream GitHub owner's universe, excluding third-party copies.

Specifically, search results include:

More specifically, search results include packages for which:
- Packages where the GitHub owner matches the universe name (e.g., packages under `https://jeroen.r-universe.dev` from `https://github.com/jeroen/`). This includes all CRAN packages.
- Packages where the universe name differs from the GitHub owner, but the DESCRIPTION file includes the full `user.r-universe.dev` URL in the `URL` field (e.g., `https://jeroen.r-universe.dev` or `https://jeroen.r-universe.dev/mypkg`).

- The GitHub owner is the same as the universe, for example packages under `https://jeroen.r-universe.dev` from GitHub user `https://github.com/jeroen/`. This also includes all CRAN packages.
- Alternatively: to opt-in packages for which the universe name is different from the GitHub owner, the package author must include the full `user.r-universe.dev` in the URL field of the DESCRIPTION file. For example, if the registry from `https://jeroen.r-universe.dev` has a package `https://github.com/elsewhere/mypkg`, but the URL field in the DESCRIPTION includes e.g. `https://jeroen.r-universe.dev` or `https://jeroen.r-universe.dev/mypkg`, then it also shows up in the search results.

## Why is a package sometimes listed twice?

If a source package fails to build (indicating a critical issue), a red "build failure" message is displayed.
If a previous build succeeded, it remains available for users to install.
Loading

0 comments on commit 6d93928

Please sign in to comment.