knitr::opts_chunk$set( comment = "#>", tidy = FALSE, error = FALSE, fig.width = 8, fig.height = 8)
Markdown + Roxygen = Maxygen
Write your Roxygen documentation in CommonMark Markdown. See http://spec.commonmark.org/ for the complete specification.
devtools::install_github("gaborcsardi/maxygen")
library(maxygen) macument(pkg_dir)
You can use the macument()
command instead of devtools::document()
to
create the Rd documentation from Markdown-Roxygen. macument()
converts
the Markdown formatting within the Roxygen comments to proper R manual
format, and then calls devtools::document()
itself.
See a complete example and the
generated Rd
files.
Use backticks instead of \code{}
:
#' @param ns Optionally, a named vector giving prefix-url pairs, as #' produced by `xml_ns`. If provided, all names will be explicitly #' qualified with the ns prefix, i.e. if the element `bar` is define ...
Put your code between three backticks:
#' ``` #' pkg <- make_packages( #' foo1 = { f <- function() print("hello!") ; d <- 1:10 }, #' foo2 = { f <- function() print("hello again!") ; d <- 11:20 } #' ) #' foo1::f() #' foo2::f() #' foo1::d #' foo2::d #' dispose_packages(pkg) #' ```
Regular Markdown lists are recognized and converted to
\enumerate{}
or \itemize{}
lists:
#' There are two ways to use this function: #' 1. If its first argument is not named, then it returns a function #' that can be used to color strings. #' 1. If its first argument is named, then it also creates a #' style with the given name. This style can be used in #' `style`. One can still use the return value #' of the function, to create a style function.
#' The style (the `...` argument) can be anything of the #' following: #' * An R color name, see `colors()`. #' * A 6- or 8-digit hexa color string, e.g. `#ff0000` means #' red. Transparency (alpha channel) values are ignored. #' * A one-column matrix with three rows for the red, green #' and blue channels, as returned by `col2rgb` (in the base #' grDevices package).
Nested lists are also supported.
Emphasis and strong (bold) text is supported:
#' See `::is_falsy` for the definition of what is _falsy_ #' and what is _truthy_.
#' @references #' Robert E Tarjan and Mihalis Yannakakis. (1984). Simple #' linear-time algorithms to test chordality of graphs, test acyclicity #' of hypergraphs, and selectively reduce acyclic hypergraphs. #' *SIAM Journal of Computation* **13**, 566-579.
Markdown notation can be used to create links to other manual pages. There are four kinds of links:
#' Link to another manual page: [](::my_function). #' Link to a manual page from another package: [](maxygen::macument). #' #' This is a link in the text. Look at [this function](::=my_function). #' Also look at [this function in maxygen](maxygen::macument). #' #' It is possible to make text links verbatim, [`like this`](::=my_function). #' Even if they refer to another package, #' [`like this`](maxygen::macument). #' With quotes: [`"like this"`](maxygen::macument).
URLs are currently not automatically recognized, but Markdown links are:
#' This dataset is licensed under a Creative Commons #' Attribution-Share Alike 2.0 UK: England & Wales License, #' see [http://creativecommons.org/licenses/by-sa/2.0/uk/]() for details. #' Please cite the reference below if you use this dataset.
Images are also recognized. The actual files must be in man/figures
:
#' Here is an example plot: #' ![](example-plot.jpg "Example Plot Title")
macument()
is called, all calls to roxygen::document()
will understand the Markdown formatting.@title
, @description
and
@details
tags in your documentation. Once
this issue is
fixed, this will not be necessary.MIT © Gábor Csárdi.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.