---
title: "Get started"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Get started}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
## Quick start
To create, render, and preview a new documentation website, execute these
commands from the root directory of your package:
```r
library(altdoc)
### Initialize
setup_docs("docsify")
## setup_docs("docute")
## setup_docs("mkdocs")
### Render
render_docs()
### Preview
preview_docs()
```
Below, we explain in more detail what these commands do.
## Installation
```r
install.packages("altdoc")
```
To create documentation websites with either `docsify` or `docute`, you only need
to install `altdoc` in `R`. The rest of this section only concerns `mkdocs` users.
The procedure to use `mkdocs` is slightly more involved. `mkdocs` is a Python
library, meaning that you will first need to set up a Python virtual environment
(or "venv") in your package folder. In the terminal, run the following:
```bash
python -m venv .venv_altdoc
```
Then, you can now install `mkdocs` (and other libraries such as `mkdocs-material` if needed). The correct commands to run can depend on your environment. For example, on Linux or Mac, this command may work:
```bash
.venv_altdoc/bin/pip install mkdocs mkdocs-material
```
On Windows, this might work:
```bash
.venv_altdoc\Scripts\pip.exe install mkdocs mkdocs-material
```
See the [`mkdocs`](https://www.mkdocs.org/user-guide/installation/) and
[`mkdocs-material`](https://squidfunk.github.io/mkdocs-material/getting-started/#with-pip)
installation guides for details.
## Package structure
`altdoc` makes assumptions about your package structure:
* `README.md` is the homepage of the website.
* `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.
* The content of the (optional) "news" section is stored in `NEWS.md` or `CHANGELOG.md`
* The content of the (optional) "code of conduct" section is stored in `CODE_OF_CONDUCT.md`.
* The license is stored in `LICENSE.md` or `LICENSE.md`.
### README images
When using a Rmarkdown or Quarto document to generate the README and Home Page of the package website, we recommend that you include this code chunk at the top of the document:
````{verbatim, lang = "markdown"}
```{r}
knitr::opts_chunk$set(
fig.path = "man/figures/README-"
)
```
````
This will store images in the `man/` and allow them to be displayed on CRAN, Github, as well as on the website.
Static images can also be stored in `man/`, and linked using the normal syntax, ex:
```markdown
```
## Initialize
These functions initialize a documentation website structure: `setup_docs(tool = "docsify")`, `setup_docs(tool = "docute")` and `setup_docs(tool = "mkdocs")`. Calling one of them will:
1. Create a `docs/` folder
2. Create a `altdoc/` folder
3. Add `altdoc/` to `.Rbuildignore`
4. Copy default settings files to `altdoc/` for the chosen documentation generator
## Customize
To customize the documentation, you can edit the settings files in the `altdoc/` folder. The settings files differ between the different documentation generators. For example, this is the default `mkdocs.yml` settings created when one calls `setup_docs(tool = "mkdocs")`:
```yaml
site_name: $ALTDOC_PACKAGE_NAME
repo_url: $ALTDOC_PACKAGE_URL
repo_name: $ALTDOC_PACKAGE_NAME
plugins:
- search
nav:
- Home: README.md
$ALTDOC_VIGNETTE_BLOCK
- Changelog: $ALTDOC_NEWS
- Code of Conduct: $ALTDOC_CODE_OF_CONDUCT
- License: $ALTDOC_LICENSE
```
By editing this file, you can change the name of the website, the order of the sections, add new sections or drop irrelevant ones, etc.
The settings files 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. Note that PDF files in the "vignettes/" folder are included, except when docute is used.
* `$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.
Interested readers should refer to their chosen documentation generator documentation for more details:
* https://docsify.js.org/
* https://docute.egoist.dev/
* https://www.mkdocs.org/
## Render and update
Once the documentation is initialized, you can render it with:
```r
render_docs()
```
This function will:
1. Render and copy standard `R` package files to `docs/`.
- Ex: `NEWS.md`, `README.md`, `LICENSE.md`, `CODE_OF_CONDUCT.md`, etc.
2. Render Rmarkdown and Quarto files (`.Rmd` and `.qmd` extensions) from the `vignettes/` directory and store them in `docs/vignettes/`.
3. Copy Markdown files with extension `.md` from `vignettes/` to `docs/vignettes/`.
4. Convert the manual pages stored in `man/` from `.Rd` to `.md` format, and copy them to `docs/man/`.
5. Copy all static files from `altdoc/` to `docs/`.
Whenever you make changes to the man pages or to the vignettes, you can call `render_docs()` again to render the new files and update the website.
## Preview
To preview the website, you need to run a local web server.
In RStudio you can launch one automatically in the Preview Pane by calling:
```r
preview_docs()
```
In Visual Studio Code, you can use one of the many "live preview" or "local server" extensions available. For example,
1. Install the [Live Preview](https://marketplace.visualstudio.com/items?itemName=ms-vscode.live-server) extension from Microsoft.
2. From the command palette, select "Live Preview: Start Server".
3. When the preview pane opens, navigate to the `docs/` folder.
##### Test
The code and images in this subsection are inserted as a demonstration of images in Rmarkdown vignettes.
```{r}
with(mtcars, plot(mpg, wt))
```
