generate([io::IO = stdout,] root::String;force = false)

This function adds a (unconditional) warning (and noindex meta tag) to all versions of the documentation in root.

force overwrites a previous injected warning message created by this function.

A typical use case is to run this on the gh-pages branch of a package. Make sure you review which changes you check in if you are not tagging a new release of your package's documentation at the same time.

Provides the functions related to generating documentation stubs.

gitignore()

Contents of the default .gitignore file.

index(pkgname)

Contents of the default src/index.md file.

make(pkgname; format)

Contents of the default make.jl file.

mkdocs(pkgname; description, author, url)

Contents of the default mkdocs.yml file.

project(; format)

Contents of the default Project.toml file.

savefile(f, root, filename)

Attempts to save a file at $(root)/$(filename). f will be called with file stream (see open).

filename can also be a file in a subdirectory (e.g. src/index.md), and then then subdirectories will be created automatically.

DocumenterTools.generate(path::String = "docs"; name = nothing, format = :html)

Create a documentation stub in path, which is usually a sub folder in the package root. The name of the package is determined automatically, but can be given with the name keyword argument.

generate can also be called without any arguments, in which case it simply puts all the generated files into a docs directory in the current working directory. This way, if you are already in the root directory of your package, you generally only need to call generate() to generate the documentation stub.

generate creates the following files in path:

.gitignore
src/index.md
make.jl
mkdocs.yml
Project.toml

Arguments

path file path to the documentation directory to be created (default is "docs").

Keywords Arguments

name is the name of the package (without .jl). If name is not given generate tries to detect it automatically.

format can be either :html (default), :markdown or :pdf corresponding to the format keyword to Documenter's makedocs function, see Documenter's manual.

Examples

julia> using DocumenterTools

julia> DocumenterTools.generate("path/to/MyPackage/docs")
[ ... output ... ]

DocumenterTools.generate(pkg::Module; dir = "docs", format = :html)

Same as generate(path::String) but the path and name is determined automatically from the module.

Examples

julia> using DocumenterTools

julia> using MyPackage

julia> DocumenterTools.generate(MyPackage)
[ ... output ... ]

genkeys(package::Module; remote="origin")

Like the other method, this generates the SSH keys necessary for the automatic deployment of documentation with Documenter from a builder to GitHub Pages, but attempts to guess the package URLs from the Git remote.

package needs to be the top level module of the package. The remote keyword argument can be used to specify which Git remote is used for guessing the repository's GitHub URL.

This method requires the following command lines programs to be installed:

• which (Unix) or where (Windows)
• git

Examples

julia> using DocumenterTools

julia> DocumenterTools.genkeys(DocumenterTools)
[Info: add the public key below to https://github.com/JuliaDocs/DocumenterTools.jl/settings/keys with read/write access:

ssh-rsa AAAAB3NzaC2yc2EAAAaDAQABAAABAQDrNsUZYBWJtXYUk21wxZbX3KxcH8EqzR3ZdTna0Wgk...jNmUiGEMKrr0aqQMZEL2BG7 username@hostname

[ Info: add a secure 'Repository secret' named 'DOCUMENTER_KEY' to https://travis-ci.com/JuliaDocs/DocumenterTools.jl/settings (if you deploy using Travis CI) or https://github.com/JuliaDocs/DocumenterTools.jl/settings/secrets (if you deploy using GitHub Actions) with value:

LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBNnpiRkdXQVZpYlIy...QkVBRWFjY3BxaW9uNjFLaVdOcDU5T2YrUkdmCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==

DocumenterTools.genkeys(; user="$USER", repo="$REPO")

Generates the SSH keys necessary for the automatic deployment of documentation with Documenter from a builder to GitHub Pages.

By default the links in the instructions need to be modified to correspond to actual URLs. The optional user and repo keyword arguments can be specified so that the URLs in the printed instructions could be copied directly. They should be the name of the GitHub user or organization where the repository is hosted and the full name of the repository, respectively.

Examples

julia> using DocumenterTools

julia> DocumenterTools.genkeys()
┌ Info: Add the key below as a new 'Deploy key' on GitHub (https://github.com/$USER/$REPO/settings/keys) with read and write access.
└ The 'Title' field can be left empty as GitHub can infer it from the key comment.

ssh-rsa AAAAB3NzaC2yc2EAAAaDAQABAAABAQDrNsUZYBWJtXYUk21wxZbX3KxcH8EqzR3ZdTna0Wgk...jNmUiGEMKrr0aqQMZEL2BG7 Documenter

[ Info: Add a secure 'Repository secret' named 'DOCUMENTER_KEY' (to https://github.com/$USER/$REPO/settings/secrets if you deploy using GitHub Actions) with value:

LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBNnpiRkdXQVZpYlIy...QkVBRWFjY3BxaW9uNjFLaVdOcDU5T2YrUkdmCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==


julia> DocumenterTools.genkeys(user="JuliaDocs", repo="DocumenterTools.jl")
┌ Info: Add the key below as a new 'Deploy key' on GitHub (https://github.com/JuliaDocs/DocumenterTools.jl/settings/keys) with read and write access.
└ The 'Title' field can be left empty as GitHub can infer it from the key comment.

ssh-rsa AAAAB3NzaC2yc2EAAAaDAQABAAABAQDrNsUZYBWJtXYUk21wxZbX3KxcH8EqzR3ZdTna0Wgk...jNmUiGEMKrr0aqQMZEL2BG7 Documenter

[ Info: Add a secure 'Repository secret' named 'DOCUMENTER_KEY' (to https://github.com/JuliaDocs/DocumenterTools.jl/settings/secrets if you deploy using GitHub Actions) with value:

LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBNnpiRkdXQVZpYlIy...QkVBRWFjY3BxaW9uNjFLaVdOcDU5T2YrUkdmCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==

package_devpath(pkg)

Returns the path to the top level directory of a devved out package source tree. The package is identified by its top level module pkg.

The Themes module contains APIs to more easily compile the Documenter Sass themes into CSS files.

To compile an Sass file into a Documenter theme, you can use the Themes.compile function:

julia> using DocumenterTools: Themes

julia> Themes.compile("mytheme.scss")

When working on the Documenter built-in themes, the Themes.themewatcher function can be used to automatically update all the built-in themes when any of the Sass files are modified. To enable it, just run

julia> using DocumenterTools: Themes

julia> Themes.themewatcher()

Note that it will read and overwrite the Sass and CSS files of the Documenter of the environment DocumenterTools is loaded in — make sure that you have Documenter added as a development dependency to that environment.

compile(src[, dst])

Compile an input Sass/SCSS file src into a CSS file. The standard Documenter Sass/SCSS files are available in the include path.

The optional dst argument can be used to specify the output file. Otherwise, the file extension of the src file is simply replaced by .css.

compile_native_theme(name; dst=nothing)

Compiles a native Documenter theme and places it into Documenter's assets directory.

Optionally, the dst keyword argument can be used to specify the output file.

themewatcher()

Starts an asynchronous background task that checks for changes in the Documenter Sass files and recompiles all native themes whenever changes are detected.