/1.1`. This
is inspired from the python documentation style)
To acheive this, there will be two branches created: `md-outputs` and `gh-pages`
that will inerit like so main -> `md-outputs` -> `gh-pages`. Because the build
time from main to `md-outputs` can be time intensive, this will default to
-updating only files that were changed.
+updating only files that were changed.
- `md-outputs`: this branch will contain the files and artifacts generated from
- rmarkdown in the vignettes directory of a thin package skeleton.
+ rmarkdown in the vignettes directory of a thin package skeleton.
- `gh-pages`: this branch is generated via `md-outputs` and bundles the html,
css, and js for the website. This will contain a single `index.html` file
with several subfolders with different versions of the site. The `index.html`
file will redirect to the `current/` directory, which contains the up-to-date
- site.
+ site.
#### Scheduled builds
@@ -145,11 +145,11 @@ updating only files that were changed.
separated from the styling, we will set up the CI to generate the webpage
from the pre-built sources on a weekly basis, which will check if there has
been an update to the styles (which I have in the [{varnish}] package) and
- then rebuild the site without rebuilding the content.
+ then rebuild the site without rebuilding the content.
- `md-outputs` branch: This will be rerun every month from scratch with the
most recent version of R and R packages. If there is a change, a pull request
can be generated to update the `renv.lock` file with a link to the changed
- markdown files in this branch.
+ markdown files in this branch.
### Function syntax
@@ -189,11 +189,12 @@ Accessors
- `build_episode_html()` renders a built markdown file to html (internal use)
- `build_lesson()` builds the lesson into a static website
- `build_portable_lesson()` builds the lesson into a portable static website
+ - `build_glossary()` builds a Glosario-based glossary for the lesson
**Continuous Integration Utilities**
- `ci_deploy()` builds and deploys the lesson on CI from the source files
- - `ci_build_markdown()` builds the markdown files on CI from the source and deploys them to the markdown branch.
+ - `ci_build_markdown()` builds the markdown files on CI from the source and deploys them to the markdown branch.
- `ci_build_site()` deploys the lesson on CI from pre-rendered markdown files
- `ci_release()` builds and deploys the lesson on CI from the source files and adds a release tag
- `update_github_workflows()` updates GitHub workflows
@@ -201,7 +202,7 @@ Accessors
Cleanup
- `reset_episodes()` removes the schedule from the config.yaml file
- - `reset_site()` clears the website and cache
+ - `reset_site()` clears the website and cache
## Usage
@@ -234,7 +235,7 @@ the following structure:
|-- episodes/ # - PUT YOUR MARKDOWN FILES IN THIS FOLDER
| |-- data/ # - Data for your lesson goes here
| |-- figures/ # - All static figures and diagrams are here
-| |-- files/ # - Additional files (e.g. handouts)
+| |-- files/ # - Additional files (e.g. handouts)
| `-- 00-introducition.Rmd # - Lessons start with a two-digit number
|-- instructors/ # - Information for Instructors
|-- learners/ # - Information for Learners
@@ -265,10 +266,10 @@ sandpaper::build_lesson()
```
> #### Working in RStudio?
->
+>
> If you are using RStudio, you can preview the lesson site using the keyboard
> shortcut ctrl + shift + B (which corresponds to the "Build Website" button in the "Build" tab. To preview individual files, you can use
-> ctrl + shift + K (This corresponds to the "Knit" button in the editor pane)
+> ctrl + shift + K (This corresponds to the "Knit" button in the editor pane)
This will create the website structure inside of the the `site/` folder, render
the RMarkdown files to markdown (for inspection and quick rendering), render the
@@ -279,14 +280,14 @@ markdown files to HTML, and then enable a preview within your browser window.
To contribute to a lesson, you can either fork the lesson to your own repository
and clone it to your computer manually from GitHub, or you can use the {usethis}
-package to automate it. For example, This is how you can create a copy of
+package to automate it. For example, This is how you can create a copy of
[**Programming With R**](http://swcarpentry.github.io/r-novice-inflammation/) to
your computer's Desktop.
```{r}
usethis::create_from_github(
- repo = "swcarpentry/r-novice-gapminder",
+ repo = "swcarpentry/r-novice-gapminder",
destdir = "~/Desktop/r-novice-gampinder",
fork = TRUE
)
@@ -303,9 +304,9 @@ already have a copy on your machine. If not, follow the instructions in the
The typical workflow will look like this:
-1. open the sandpaper project in RStudio and make edits to files in the
+1. open the sandpaper project in RStudio and make edits to files in the
`episodes/` folder
-2. in the R console run the following
+2. in the R console run the following
```{r}
@@ -325,8 +326,8 @@ sandpaper::build_portable_lesson(version = "current")
```
This will render a fully portable lesson site as a zip file in the `site/`
-folder. You can distribute this lesson to learners who do not have reliable
-internet access for use offline without sacrificing any of the styling.
+folder. You can distribute this lesson to learners who do not have reliable
+internet access for use offline without sacrificing any of the styling.
### Rendering with GitHub actions
@@ -359,7 +360,7 @@ sandpaper::ci_release(tag = "0.1", md_branch = "md-outputs", site_branch = "gh-p
[The Carpentries]: https://carpentries.org
-[Markdown]: https://www.markdownguide.org/getting-started/
+[Markdown]: https://www.markdownguide.org/getting-started/
[RMarkdown]: https://rmarkdown.rstudio.com/
[{learnr}]: https://rstudio.github.io/learnr/index.html
[{remotes}]: https://remotes.r-lib.org/
diff --git a/man/build_episode_html.Rd b/man/build_episode_html.Rd
index 5b6957fa1..92c1fde0d 100644
--- a/man/build_episode_html.Rd
+++ b/man/build_episode_html.Rd
@@ -13,7 +13,8 @@ build_episode_html(
quiet = FALSE,
page_progress = NULL,
sidebar = NULL,
- date = NULL
+ date = NULL,
+ glosario = NULL
)
}
\arguments{
@@ -40,6 +41,9 @@ sidebar. The current episode will be replaced with an index of all the
chapters in the episode.}
\item{date}{the date the episode was last built.}
+
+\item{glosario}{a dictionary of terms read in from Glosario glossary.yaml
+on Github. Defaults to NULL.}
}
\value{
\code{TRUE} if the page was successful, \code{FALSE} otherwise.
diff --git a/man/build_glossary.Rd b/man/build_glossary.Rd
new file mode 100644
index 000000000..e375b1a22
--- /dev/null
+++ b/man/build_glossary.Rd
@@ -0,0 +1,72 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/build_glossary.R
+\name{build_glossary}
+\alias{build_glossary}
+\alias{build_glossary_page}
+\title{Build a page for aggregating glosario links found in lesson elements}
+\usage{
+build_glossary(pkg, pages = NULL, quiet = FALSE)
+
+build_glossary_page(
+ pkg,
+ pages,
+ title = "Glosario Links",
+ slug = "reference",
+ aggregate = "*",
+ append = "self::node()",
+ quiet = FALSE
+)
+}
+\arguments{
+\item{pkg}{an object created via \code{\link[pkgdown:as_pkgdown]{pkgdown::as_pkgdown()}} of a lesson.}
+
+\item{pages}{output from the function \code{\link[=read_all_html]{read_all_html()}}: a nested list of
+\code{xml_document} objects representing episodes in the lesson}
+
+\item{quiet}{if \code{TRUE}, no messages will be emitted. If FALSE, pkgdown will
+report creation of the temporary file.}
+
+\item{title}{the new page title}
+
+\item{slug}{the slug for the page (e.g. "aio" will become "aio.html")}
+
+\item{aggregate}{a selector for the lesson content you want to aggregate.
+The default is "*", which will aggregate links from all content.
+To grab only links from sections, use "section".}
+
+\item{append}{a selector for the section of the page where the aggregate data
+should be placed. This defaults to "self::node()", which indicates that the
+entire page should be appended.}
+}
+\value{
+NULL, invisibly. This is called for its side-effect
+}
+\description{
+Build a page for aggregating glosario links found in lesson elements
+}
+\details{
+We programmatically search through lesson content to find links that point to
+glosario terms. We then aggregate these links into a single page.
+
+To customise the page, we need a few things:
+\enumerate{
+\item a title
+\item a slug
+}
+}
+\note{
+This function assumes that you have already built all the episodes of your lesson.
+}
+\examples{
+if (FALSE) {
+ # build_glossary_page() assumes that your lesson has been built and takes in a
+ # pkgdown object, which can be created from the `site/` folder in your
+ # lesson.
+ lsn <- "/path/to/my/lesson"
+ pkg <- pkgdown::as_pkgdown(fs::path(lsn, "site"))
+
+ htmls <- read_all_html(pkg$dst_path)
+ build_glossary_page(pkg, htmls, quiet = FALSE)
+}
+}
+\keyword{internal}
diff --git a/man/known_languages.Rd b/man/known_languages.Rd
index 79f820c65..c1ff7e3e6 100644
--- a/man/known_languages.Rd
+++ b/man/known_languages.Rd
@@ -21,6 +21,7 @@ details of how to do so in the source code for \code{{sandpaper}}.
\subsection{List of Known Languages:}{
\if{html}{\out{}}\preformatted{#> - en
+#> - de
#> - es
#> - fr
#> - ja
diff --git a/man/render_html.Rd b/man/render_html.Rd
index 77933e5d7..14516e300 100644
--- a/man/render_html.Rd
+++ b/man/render_html.Rd
@@ -4,7 +4,7 @@
\alias{render_html}
\title{Render html from a markdown file}
\usage{
-render_html(path_in, ..., quiet = FALSE)
+render_html(path_in, ..., quiet = FALSE, glosario = NULL)
}
\arguments{
\item{path_in}{path to a markdown file}
@@ -13,6 +13,8 @@ render_html(path_in, ..., quiet = FALSE)
\item{quiet}{if \code{TRUE}, no output is produced. Default is \code{FALSE}, which
reports the markdown build via pandoc}
+
+\item{glosario}{a named list of glosario terms and definitions. Defaults to NULL.}
}
\value{
a character containing the rendred HTML file
diff --git a/man/sandpaper-package.Rd b/man/sandpaper-package.Rd
index 9c1a31c08..2ede82ce4 100644
--- a/man/sandpaper-package.Rd
+++ b/man/sandpaper-package.Rd
@@ -40,6 +40,7 @@ Other contributors:
\item Hugo Gruson \email{hugo.gruson+R@normalesup.org} [contributor]
\item Milan Malfait \email{milan.malfait94@gmail.com} (\href{https://orcid.org/0000-0001-9144-3701}{ORCID}) [contributor]
\item Yanina Bellini Saibene (\href{https://orcid.org/0000-0002-4522-7466}{ORCID}) [contributor, translator]
+ \item Martin Raden (\href{https://orcid.org/0000-0002-7926-5911}{ORCID}) [contributor, translator]
}
}
diff --git a/man/yaml_list.Rd b/man/yaml_list.Rd
index c6edd157c..aea4ad033 100644
--- a/man/yaml_list.Rd
+++ b/man/yaml_list.Rd
@@ -25,9 +25,7 @@ cat(yaml::as.yaml(hx)) # representation in yaml
#> - a
#> - b
#> - c
-}\if{html}{\out{
}}
-
-\if{html}{\out{}}\preformatted{cat(whisker::whisker.render("hello: \{\{hello\}\}", hx)) # messed up whisker
+cat(whisker::whisker.render("hello: \{\{hello\}\}", hx)) # messed up whisker
#> hello: a,b,c
}\if{html}{\out{
}}