Public Documentation

Documentation for Documenter.jl's public interface.

See the Internals section of the manual for internal package docs covering all submodules.

Contents

Index

Public Interface

Documenter.makedocsFunction
makedocs(
    root    = "<current-directory>",
    source  = "src",
    build   = "build",
    clean   = true,
    doctest = true,
    modules = Module[],
    repo    = "",
    highlightsig = true,
    sitename = "",
    expandfirst = [],
)

Combines markdown files and inline docstrings into an interlinked document. In most cases makedocs should be run from a make.jl file:

using Documenter
makedocs(
    # keywords...
)

which is then run from the command line with:

$ julia make.jl

The folder structure that makedocs expects looks like:

docs/
    build/
    src/
    make.jl

Keywords

root is the directory from which makedocs should run. When run from a make.jl file this keyword does not need to be set. It is, for the most part, needed when repeatedly running makedocs from the Julia REPL like so:

julia> makedocs(root = joinpath(dirname(pathof(MyModule)), "..", "docs"))

source is the directory, relative to root, where the markdown source files are read from. By convention this folder is called src. Note that any non-markdown files stored in source are copied over to the build directory when makedocs is run.

build is the directory, relative to root, into which generated files and folders are written when makedocs is run. The name of the build directory is, by convention, called build, though, like with source, users are free to change this to anything else to better suit their project needs.

clean tells makedocs whether to remove all the content from the build folder prior to generating new content from source. By default this is set to true.

doctest instructs makedocs on whether to try to test Julia code blocks that are encountered in the generated document. By default this keyword is set to true. Doctesting should only ever be disabled when initially setting up a newly developed package where the developer is just trying to get their package and documentation structure correct. After that, it's encouraged to always make sure that documentation examples are runnable and produce the expected results. See the Doctests manual section for details about running doctests.

Setting doctest to :only allows for doctesting without a full build. In this mode, most build stages are skipped and the strict keyword is ignore (a doctesting error will always make makedocs throw an error).

modules specifies a vector of modules that should be documented in source. If any inline docstrings from those modules are seen to be missing from the generated content then a warning will be printed during execution of makedocs. By default no modules are passed to modules and so no warnings will appear. This setting can be used as an indicator of the "coverage" of the generated documentation. For example Documenter's make.jl file contains:

makedocs(
    modules = [Documenter],
    # ...
)

and so any docstring from the module Documenter that is not spliced into the generated documentation in build will raise a warning.

repo specifies a template for the "link to source" feature. If you are using GitHub, this is automatically generated from the remote. If you are using a different host, you can use this option to tell Documenter how URLs should be generated. The following placeholders will be replaced with the respective value of the generated link:

  • {commit} Git branch or tag name, or commit hash
  • {path} Path to the file in the repository
  • {line} Line (or range of lines) in the source file

BitBucket, GitLab and Azure DevOps are supported along with GitHub, for example:

makedocs(repo = "https://gitlab.com/user/project/blob/{commit}{path}#{line}") # GitLab
makedocs(repo = "https://dev.azure.com/org/project/_git/repo?path={path}&version={commit}{line}&lineStartColumn=1&lineEndColumn=1") # Azure DevOps
makedocs(repo = "https://bitbucket.org/user/project/src/{commit}/{path}#lines-{line}") # BitBucket

highlightsig enables or disables automatic syntax highlighting of leading, unlabeled code blocks in docstrings (as Julia code). For example, if your docstring begins with an indented code block containing the function signature, then that block would be highlighted as if it were a labeled Julia code block. No other code blocks are affected. This feature is enabled by default.

sitename is displayed in the title bar and/or the navigation menu when applicable.

expandfirst allows some of the pages to be expanded (i.e. at-blocks evaluated etc.) before the others. Documenter normally evaluates the files in the alphabetic order of their file paths relative to src, but expandfirst allows some pages to be prioritized.

For example, if you have foo.md and bar.md, bar.md would normally be evaluated before foo.md. But with expandfirst = ["foo.md"], you can force foo.md to be evaluated first.

Evaluation order among the expandfirst pages is according to the order they appear in the argument.

Experimental keywords

In addition to standard arguments there is a set of non-finalized experimental keyword arguments. The behaviour of these may change or they may be removed without deprecation when a minor version changes (i.e. except in patch releases).

checkdocs instructs makedocs to check whether all names within the modules defined in the modules keyword that have a docstring attached have the docstring also listed in the manual (e.g. there's a @docs block with that docstring). Possible values are :all (check all names; the default), :exports (check only exported names) and :none (no checks are performed). If strict is also enabled then the build will fail if any missing docstrings are encountered.

linkcheck – if set to true makedocs uses curl to check the status codes of external-pointing links, to make sure that they are up-to-date. The links and their status codes are printed to the standard output. If strict is also enabled then the build will fail if there are any broken (400+ status code) links. Default: false.

linkcheck_ignore allows certain URLs to be ignored in linkcheck. The values should be a list of strings (which get matched exactly) or Regex objects. By default nothing is ignored.

linkcheck_timeout configures how long curl waits (in seconds) for a link request to return a response before giving up. The default is 10 seconds.

strictmakedocs fails the build right before rendering if it encountered any errors with the document in the previous build phases.

workdir determines the working directory where @example and @repl code blocks are executed. It can be either a path or the special value :build (default).

If the workdir is set to a path, the working directory is reset to that path for each code block being evaluated. Relative paths are taken to be relative to root, but using absolute paths is recommended (e.g. workdir = joinpath(@__DIR__, "..") for executing in the package root for the usual docs/make.jl setup).

With the default :build option, the working directory is set to a subdirectory of build, determined from the source file path. E.g. for src/foo.md it is set to build/, for src/foo/bar.md it is set to build/foo etc.

Note that workdir does not affect doctests.

Output formats

format allows the output format to be specified. The default format is Documenter.HTML which creates a set of HTML files, but Documenter also provides PDF output via the Documenter.LaTeX writer.

Other formats can be enabled by using other addon-packages. For example, the DocumenterMarkdown package provides the original Markdown -> Markdown output. See the Other Output Formats for more information.

See Also

A guide detailing how to document a package using Documenter's makedocs is provided in the setup guide in the manual.

source
Documenter.hideFunction
hide(page)

Allows a page to be hidden in the navigation menu. It will only show up if it happens to be the current page. The hidden page will still be present in the linear page list that can be accessed via the previous and next page links. The title of the hidden page can be overridden using the => operator as usual.

Usage

makedocs(
    ...,
    pages = [
        ...,
        hide("page1.md"),
        hide("Title" => "page2.md")
    ]
)
source
hide(root, children)

Allows a subsection of pages to be hidden from the navigation menu. root will be linked to in the navigation menu, with the title determined as usual. children should be a list of pages (note that it can not be hierarchical).

Usage

makedocs(
    ...,
    pages = [
        ...,
        hide("Hidden section" => "hidden_index.md", [
            "hidden1.md",
            "Hidden 2" => "hidden2.md"
        ]),
        hide("hidden_index.md", [...])
    ]
)
source
Documenter.Writers.HTMLWriter.assetFunction
asset(uri)

Can be used to pass non-local web assets to HTML, where uri should be an absolute HTTP or HTTPS URL.

It accepts the following keyword arguments:

class can be used to override the asset class, which determines how exactly the asset gets included in the HTML page. This is necessary if the class can not be determined automatically (default).

Should be one of: :js, :css or :ico. They become a <script>, <link rel="stylesheet" type="text/css"> and <link rel="icon" type="image/x-icon"> elements in <head>, respectively.

islocal can be used to declare the asset to be local. The uri should then be a path relative to the documentation source directory (conventionally src/). This can be useful when it is necessary to override the asset class of a local asset.

Usage

Documenter.HTML(assets = [
    # Standard local asset
    "assets/extra_styles.css",
    # Standard remote asset (extension used to determine that class = :js)
    asset("https://example.com/jslibrary.js"),
    # Setting asset class manually, since it can't be determined manually
    asset("https://example.com/fonts", class = :css),
    # Same as above, but for a local asset
    asset("asset/foo.script", class=:js, islocal=true),
])
source
Documenter.deploydocsFunction
deploydocs(
    root   = "<current-directory>",
    target = "build",
    repo   = "<required>",
    branch = "gh-pages",
    deps   = nothing | <Function>,
    make   = nothing | <Function>,
    devbranch = "master",
    devurl = "dev",
    versions = ["stable" => "v^", "v#.#", devurl => devurl],
    push_preview    = false,
    repo_previews   = repo,
    branch_previews = branch,
)

Copies the files generated by makedocs in target to the appropriate (sub-)folder on the deployment branch, commits them, and pushes to repo. This function should be called from within a package's docs/make.jl file after the call to makedocs, like so

using Documenter, PACKAGE_NAME
makedocs(
    # options...
)
deploydocs(
    repo = "github.com/..."
)

When building the docs for a tag (i.e. a release) the documentation is deployed to a directory with the tag name (i.e. vX.Y.Z) and to the stable directory. Otherwise the docs are deployed to the directory determined by the devurl argument.

The deployment procedure consists of the following steps:

  • Check out the branch of repo to a temporary location
  • Remove the existing deployment (sub-)directory with git rm -r
  • Copy the target (build) folder to the deployment directory
  • Generate index.html, and versions.js in the branch root and siteinfo.js in the deployment directory
  • Add all files on the deployment branch (git add -A .), commit them, and push the repo. Note that any .gitignore files in the target directory affect which files will be committed to branch.

Required keyword arguments

repo is the remote repository where generated HTML content should be pushed to. Do not specify any protocol - "https://" or "git@" should not be present. This keyword must be set and will throw an error when left undefined. For example this package uses the following repo value:

repo = "github.com/JuliaDocs/Documenter.jl.git"

Optional keyword arguments

deploy_config determines configuration for the deployment. If this is not specified Documenter will try to autodetect from the currently running environment. See the manual section about Deployment systems.

root has the same purpose as the root keyword for makedocs.

target is the directory, relative to root, where generated content that should be deployed to gh-pages is written to. It should generally be the same as makedocs's build and defaults to "build".

branch is the branch where the generated documentation is pushed. If the branch does not exist, a new orphaned branch is created automatically. It defaults to "gh-pages".

deps is the function used to install any additional dependencies needed to build the documentation. By default nothing is installed.

It can be used e.g. for a Markdown build. The following example installed the pygments and mkdocs Python packages using the Deps.pip function:

deps = Deps.pip("pygments", "mkdocs")

make is the function used to specify an additional build phase. By default, nothing gets executed.

devbranch is the branch that "tracks" the in-development version of the generated documentation. By default this value is set to "master".

devurl the folder that in-development version of the docs will be deployed. Defaults to "dev".

forcepush a boolean that specifies the behavior of the git-deployment. The default (forcepush = false) is to push a new commit, but when forcepush = true the changes will be combined with the previous commit and force pushed, erasing the Git history on the deployment branch.

versions determines content and order of the resulting version selector in the generated html. The following entries are valid in the versions vector:

  • "v#": includes links to the latest documentation for each major release cycle (i.e. v2.0, v1.1).
  • "v#.#": includes links to the latest documentation for each minor release cycle (i.e. v2.0, v1.1, v1.0, v0.1).
  • "v#.#.#": includes links to all released versions.
  • "v^": includes a link to the docs for the maximum version (i.e. a link vX.Y pointing to vX.Y.Z for highest X, Y, Z, respectively).
  • A pair, e.g. "first" => "second", which will put "first" in the selector, and generate a url from which "second" can be accessed. The second argument can be "v^", to point to the maximum version docs (as in e.g. "stable" => "v^").

If versions = nothing documentation will be deployed directly to the "root", i.e. not to a versioned subfolder. See the manual section on Deploying without the versioning scheme for more details.

push_preview a boolean that specifies if preview documentation should be deployed from pull requests or not. If your published documentation is hosted at "https://USER.github.io/PACKAGE.jl/stable, by default the preview will be hosted at "https://USER.github.io/PACKAGE.jl/previews/PR##". This feature works for pull requests with head branch in the same repository, i.e. not from forks.

branch_previews is the branch to which pull request previews are deployed. It defaults to the value of branch.

repo_previews is the remote repository to which pull request previews are deployed. It defaults to the value of repo.

Note

Pull requests made from forks will not have previews. Hosting previews requires access to the deploy key. Therefore, previews are available only for pull requests that were submitted directly from the main repository.

Releases vs development branches

deploydocs will automatically figure out whether it is deploying the documentation for a tagged release or just a development branch (usually, based on the environment variables set by the CI system).

With versioned tags, deploydocs discards the build metadata (i.e. + and everything that follows it) from the version number when determining the name of the directory into which the documentation gets deployed. Pre-release identifiers are preserved.

See Also

The Hosting Documentation section of the manual provides a step-by-step guide to using the deploydocs function to automatically generate docs and push them to GitHub.

source
Documenter.DepsModule

Exported module that provides build and deploy dependencies and related functions.

Currently only pip is implemented.

source
Documenter.Deps.pipFunction
pip(deps)

Installs (as non-root user) all python packages listed in deps.

Examples

using Documenter

makedocs(
    # ...
)

deploydocs(
    deps = Deps.pip("pygments", "mkdocs", "mkdocs-material"),
    # ...
)
source
Documenter.doctestFunction
doctest(package::Module; kwargs...)

Convenience method that runs and checks all the doctests for a given Julia package. package must be the Module object corresponding to the top-level module of the package. Behaves like an @testset call, returning a testset if all the doctests are successful or throwing a TestSetException if there are any failures. Can be included in other testsets.

Keywords

manual controls how manual pages are handled. By default (manual = true), doctest assumes that manual pages are located under docs/src. If that is not the case, the manual keyword argument can be passed to specify the directory. Setting manual = false will skip doctesting of manual pages altogether.

Additional keywords are passed on to the main doctest method.

source
doctest(source, modules; kwargs...)

Runs all the doctests in the given modules and on manual pages under the source directory. Behaves like an @testset call, returning a testset if all the doctests are successful or throwing a TestSetException if there are any failures. Can be included in other testsets.

The manual pages are searched recursively in subdirectories of source too. Doctesting of manual pages can be disabled if source is set to nothing.

Keywords

testset specifies the name of test testset (default Doctests).

doctestfilters vector of regex to filter tests (see the manual on Filtering Doctests)

fix, if set to true, updates all the doctests that fail with the correct output (default false).

Warning

When running doctest(...; fix=true), Documenter will modify the Markdown and Julia source files. It is strongly recommended that you only run it on packages in Pkg's develop mode and commit any staged changes. You should also review all the changes made by doctest before committing them, as there may be edge cases when the automatic fixing fails.

source
Documenter.DocMetaModule

This module provides APIs for handling documentation metadata in modules.

The implementation is similar to how docstrings are handled in Base by the Base.Docs module — a special variable is created in each module that has documentation metadata.

Public API

Supported metadata

  • DocTestSetup: contains the doctest setup code for doctests in the module.
source
Documenter.DocMeta.getdocmetaFunction
getdocmeta(m::Module)

Returns the documentation metadata dictionary for the module m. The dictionary should be considered immutable and assigning values to it is not well-defined. To set documentation metadata values, DocMeta.setdocmeta! should be used instead.

source
getdocmeta(m::Module, key::Symbol, default=nothing)

Return the key entry from the documentation metadata for module m, or default if the value is unset.

source
Documenter.DocMeta.setdocmeta!Function
setdocmeta!(m::Module, key::Symbol, value; recursive=false, warn=true)

Set the documentation metadata value key for module m to value.

If recursive is set to true, it sets the same metadata value for all the submodules too. If warn is true, it prints a warning when key already exists and is gets rewritten.

source

DocumenterTools

DocumenterTools.generateFunction
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.

Note

The package must be in development mode. Make sure you run pkg> develop pkg from the Pkg REPL, or Pkg.develop("pkg") before generating docs.

Examples

julia> using DocumenterTools

julia> using MyPackage

julia> DocumenterTools.generate(MyPackage)
[ ... output ... ]
DocumenterTools.genkeysFunction
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.

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

  • which (Unix) or where (Windows)
  • ssh-keygen

Examples

julia> using DocumenterTools

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

ssh-rsa AAAAB3NzaC2yc2EAAAaDAQABAAABAQDrNsUZYBWJtXYUk21wxZbX3KxcH8EqzR3ZdTna0Wgk...jNmUiGEMKrr0aqQMZEL2BG7 username@hostname

[ Info: add a secure environment variable named 'DOCUMENTER_KEY' to https://travis-ci.com/$USER/$REPO/settings (if you deploy using Travis CI) or 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 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 environment variable 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==
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
  • ssh-keygen
Note

The package must be in development mode. Make sure you run pkg> develop pkg from the Pkg REPL, or Pkg.develop("pkg") before generating the SSH keys.

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 environment variable 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.OutdatedWarning.generateFunction
generate([io::IO = stdout,] root::String;force = false)

This function adds a 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 packge.