setup_docs: Initialize documentation website settings

In altdoc: Package Documentation Websites with 'Quarto', 'Docsify', 'Docute', or 'MkDocs'

Initialize documentation website settings

Description

Creates a subdirectory called ⁠altdoc/⁠ in the package root directory to store the settings files used to by one of the documentation generator utilities (docsify, docute, mkdocs, or quarto_website). The files in this folder are never altered automatically by altdoc unless the user explicitly calls overwrite=TRUE. They can thus be edited manually to customize the sidebar and website.

Usage

setup_docs(tool, path = ".", overwrite = FALSE)

Arguments

tool	String. "docsify", "docute", "mkdocs", or "quarto_website".
path	Path to the package root directory.
overwrite	Logical. If TRUE, overwrite existing files. Warning: This will completely delete the settings files in the altdoc directory, including any customizations you may have made.

Package structure

altdoc makes assumptions about your package structure:

• The homepage of the website is stored in README.qmd, README.Rmd, or README.md.

• ⁠vignettes/⁠ stores the vignettes in .md, .Rmd or .qmd format.

• ⁠docs/⁠ stores the rendered website. This folder is overwritten every time a user calls render_docs(), so you should not edit it manually.

• ⁠altdoc/⁠ stores the settings files created by setup_docs(). These files are never modified automatically after initialization, so you can edit them manually to customize the settings of your documentation and website. All the files stored in ⁠altdoc/⁠ are copied to ⁠docs/⁠ and made available as static files in the root of the website.

• These files are imported automatically: NEWS.md, CHANGELOG.md, CODE_OF_CONDUCT.md, LICENSE.md, LICENCE.md.

Altdoc variables

The settings files in the ⁠altdoc/⁠ directory can include ⁠$ALTDOC⁠ variables which are replaced automatically by altdoc when calling render_docs():

• ⁠$ALTDOC_PACKAGE_NAME⁠: Name of the package from DESCRIPTION.

• ⁠$ALTDOC_PACKAGE_VERSION⁠: Version number of the package from DESCRIPTION

• ⁠$ALTDOC_PACKAGE_URL⁠: First URL listed in the DESCRIPTION file of the package.

• ⁠$ALTDOC_PACKAGE_URL_GITHUB⁠: First URL that contains "github.com" from the URLs listed in the DESCRIPTION file of the package. If no such URL is found, lines containing this variable are removed from the settings file.

• ⁠$ALTDOC_MAN_BLOCK⁠: Nested list of links to the individual help pages for each exported function of the package. The format of this block depends on the documentation generator.

• ⁠$ALTDOC_VIGNETTE_BLOCK⁠: Nested list of links to the vignettes. The format of this block depends on the documentation generator.

• ⁠$ALTDOC_VERSION⁠: Version number of the altdoc package.

Also note that you can store images and static files in the ⁠altdoc/⁠ directory. All the files in this folder are copied to ⁠docs/⁠ and made available in the root of the website, so you can link to them easily.

Altdoc preambles

When you call render_docs(), altdoc will automatically paste the content of one of these three files to the top of a document:

• altdoc/preamble_vignettes_qmd.yml

• altdoc/preamble_vignettes_rmd.yml

• altdoc/preamble_man_qmd.yml

The README file uses the vignette preamble.

To preempt this behavior, add your own preamble to the README file or to a vignette.

Examples

if (interactive()) {

  # Create docute documentation
  setup_docs(tool = "docute")

  # Create docsify documentation
  setup_docs(tool = "docsify")

  # Create mkdocs documentation
  setup_docs(tool = "mkdocs")

  # Create quarto website documentation
  setup_docs(tool = "quarto_website")
}

altdoc documentation built on April 3, 2025, 10:52 p.m.