Utilities

Documenter.DefaultType
struct Default{T}

Internal wrapper type that is meant to be used in situations where it is necessary to distinguish whether the user explicitly passed the same value as the default value to a keyword argument, or whether the keyword argument was not passed at all.

function foo(; kwarg = Default("default value"))
    if isa(kwarg, Default)
        # User did not explicitly pass a value for kwarg
    else kwarg === "default value"
        # User passed "default value" explicitly
    end
end
source
Documenter.codelangMethod
codelang(infostring)

Extracts the language identifier from the info string of a Markdown code block.

source
Documenter.docsFunction
docs(ex, str)

Returns an expression that, when evaluated, returns the docstrings associated with ex.

source
Documenter.find_root_parentMethod
find_root_parent(f, path)

Tries to determine the "root" of the directory hierarchy containing path. Returns the absolute path to the root directory or nothing if no root was found. If path is a directory, it may itself already be a root.

The predicate f gets called with absolute paths to directories and must return true if the directory is a "root". An example predicate is is_git_repo_root that checks if the directory is a Git repository root.

The dbdir keyword argument specifies the name of the directory we are searching for to determine if this is a repository or not. If there is a file called dbdir, then it's contents is checked under the assumption that it is a Git worktree or a submodule.

source
Documenter.getremoteMethod
getremote(
    dir::AbstractString
) -> Union{Nothing, Documenter.Remotes.Remote}

Determines the GitHub remote of a directory by checking remote.origin.url of the repository. Returns a Remotes.GitHub, or nothing is something has gone wrong (e.g. it's run on a directory not in a Git repo, or origin.url points to a non-GitHub remote).

The results for a given directory are memoized in GIT_REMOTE_CACHE, since calling git is expensive and it is often called on the same directory over and over again.

source
Documenter.git_remote_head_branchMethod

Calls git remote show $(remotename) to try to determine the main (development) branch of the remote repository. Returns master and prints a warning if it was unable to figure it out automatically.

root is the the directory where git gets run. varname is just informational and used to construct the warning messages.

source
Documenter.is_git_repo_rootMethod
is_git_repo_root(directory; dbdir)

Check is directory is a Git repository root.

The dbdir keyword argument specifies the name of the directory we are searching for to determine if this is a repository or not. If there is a file called dbdir, then it's contents is checked under the assumption that it is a Git worktree or a submodule.

source
Documenter.mdparseMethod
mdparse(s::AbstractString; mode=:single)

Parses the given string as Markdown using Markdown.parse, but strips away the surrounding layers, such as the outermost Markdown.MD. What exactly is returned depends on the mode keyword. The resulting Markdown AST is converted into an array of MarkdownAST.Nodes.

The mode keyword argument can be one of the following:

  • :single (default) – returns a single block-level object (e.g. Markdown.Paragraph or Markdown.Admonition) and errors if the string parses into multiple blocks.
  • :blocks – the function returns a Vector{Any} of Markdown blocks.
  • :span – Returns a Vector{Any} of span-level items, stripping away the outer block. This requires the string to parse into a single Markdown.Paragraph, the contents of which gets returned.
source
Documenter.parseblockMethod

Returns a vector of parsed expressions and their corresponding raw strings.

Returns a Vector of tuples (expr, code), where expr is the corresponding expression (e.g. a Expr or Symbol object) and code is the string of code the expression was parsed from.

The keyword argument skip = N drops the leading N lines from the input string.

If raise=false is passed, the Meta.parse does not raise an exception on parse errors, but instead returns an expression that will raise an error when evaluated. parseblock returns this expression normally and it must be handled appropriately by the caller.

The linenumbernode can be passed as a LineNumberNode to give information about filename and starting line number of the block (requires Julia 1.6 or higher).

source
Documenter.srcpathMethod

Find the path of a file relative to the source directory. root is the path to the directory containing the file file.

It is meant to be used with walkdir(source).

source
Documenter.@docerrorMacro
@docerror(doc, tag, msg, exs...)

Add tag to the doc.internal.errors array and log the message msg as an error (if tag matches the doc.user.strict setting) or warning.

  • doc must be the instance of Document used for the Documenter run
  • tag must be one of the Symbols in ERROR_NAMES
  • msg is the explanation of the issue to the user
  • exs... are additional expressions that will be included with the message; see @error and @warn
source
Documenter.Remotes.URLType
URL(urltemplate, repourl=nothing)

A Remote type used internally in Documenter when the user passes a URL template string as the repo argument. Will return nothing from repourl if the optional repourl argument is not passed.

Can contain the following template sections that Documenter will replace:

  • {commit}: replaced by the commit SHA, branch or tag name
  • {path}: replaced by the path of the file, relative to the repository root
  • {line}: replaced by the line (or line range) reference

For example, the template URLs might look something like:

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

However, an explicit Remote object is preferred over using a template string when configuring Documenter.

source
Documenter.Remotes.repofileFunction
repofile(remote::Remote, ref, filename, linerange=nothing)

Documenter's internal version of fileurl, which sanitizes the inputs before they are passed to the potentially user-defined fileurl implementations.

source