Utilities
Documenter.Utilities
— ModuleProvides a collection of utility functions and types that are used in other submodules.
Documenter.Utilities.Default
— Typestruct 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
Documenter.Utilities.Object
— TypeRepresents an object stored in the docsystem by its binding and signature.
Documenter.Utilities.assetsdir
— MethodReturns the path to the Documenter assets
directory.
Documenter.Utilities.check_kwargs
— MethodPrints a formatted warning to the user listing unrecognised keyword arguments.
Documenter.Utilities.check_strict_kw
— Functioncheck_strict_kw(strict) -> Nothing
Internal function to check if strict
is a valid value for the keyword argument strict
to makedocs.
Throws an ArgumentError
if it is not valid.
Documenter.Utilities.codelang
— Methodcodelang(infostring)
Extracts the language identifier from the info string of a Markdown code block.
Documenter.Utilities.currentdir
— MethodReturns the current directory.
Documenter.Utilities.doccat
— MethodReturns the category name of the provided Object
.
Documenter.Utilities.docs
— Functiondocs(ex, str)
Returns an expression that, when evaluated, returns the docstrings associated with ex
.
Documenter.Utilities.filterdocs
— Methodfilterdocs(doc, modules)
Remove docstrings from the markdown object, doc
, that are not from one of modules
.
Documenter.Utilities.get_commit_short
— Methodget_commit_short(dir)
Returns the first 5 characters of the current git commit hash of the directory dir
.
Documenter.Utilities.git_remote_head_branch
— MethodCalls 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.
Documenter.Utilities.is_strict
— Functionis_strict(strict, val::Symbol) -> Bool
Internal function to check if strict
is strict about val
, i.e. if errors of type val
should be fatal, according to the setting strict
(as a keyword to makedocs
).
Single-argument is_strict(strict)
provides a curried function.
Documenter.Utilities.isabsurl
— Methodisabsurl(url)
Checks whether url
is an absolute URL (as opposed to a relative one).
Documenter.Utilities.issubmodule
— Methodissubmodule(sub, mod)
Checks whether sub
is a submodule of mod
. A module is also considered to be its own submodule.
E.g. A.B.C
is a submodule of A
, A.B
and A.B.C
, but it is not a submodule of D
, A.D
nor A.B.C.D
.
Documenter.Utilities.mdparse
— Methodmdparse(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 mode
keyword argument can be one of the following:
:single
(default) – returns a single block-level object (e.g.Markdown.Paragraph
orMarkdown.Admonition
) and errors if the string parses into multiple blocks.:blocks
– the function returns aVector{Any}
of Markdown blocks.:span
– Returns aVector{Any}
of span-level items, stripping away the outer block. This requires the string to parse into a singleMarkdown.Paragraph
, the contents of which gets returned.
Documenter.Utilities.nodocs
— MethodDoes the given docstring represent actual documentation or a no docs error message?
Documenter.Utilities.object
— Methodobject(ex, str)
Returns a expression that, when evaluated, returns an Object
representing ex
.
Documenter.Utilities.parseblock
— MethodReturns 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).
Documenter.Utilities.relpath_from_repo_root
— Methodrelpath_from_repo_root(file)
Returns the path of file
, relative to the root of the Git repository, or nothing
if the file is not in a Git repository.
Documenter.Utilities.repo_root
— Methodrepo_root(file; dbdir=".git")
Tries to determine the root directory of the repository containing file
. If the file is not in a repository, the function returns nothing
.
The dbdir
keyword argument specifies the name of the directory we are searching for to determine if this is a repostory 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.
Documenter.Utilities.slugify
— MethodSlugify a string into a suitable URL.
Documenter.Utilities.srcpath
— MethodFind 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)
.
Documenter.Utilities.submodules
— MethodReturns the set of submodules of a given root module/s.
Documenter.Utilities.@docerror
— Macro@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 ofDocument
used for the Documenter runtag
must be one of theSymbol
s inERROR_NAMES
msg
is the explanation of the issue to the userexs...
are additional expressions that will be included with the message; see@error
and@warn