diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 2604cbe170..9988e04701 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.9.2","generation_timestamp":"2023-08-18T05:39:31","documenter_version":"0.28.0-DEV"}} \ No newline at end of file +{"documenter":{"julia_version":"1.9.2","generation_timestamp":"2023-08-20T22:58:26","documenter_version":"0.28.0-DEV"}} \ No newline at end of file diff --git a/dev/contributing/index.html b/dev/contributing/index.html index 3e30f46bd2..c2dc97fdb3 100644 --- a/dev/contributing/index.html +++ b/dev/contributing/index.html @@ -3,4 +3,4 @@ function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'UA-136089579-2', {'page_path': location.pathname + location.search + location.hash}); -
GitHub

Contributing

This page details the some of the guidelines that should be followed when contributing to this package.

Branches

From Documenter version 0.3 onwards release-* branches are used for tagged minor versions of this package. This follows the same approach used in the main Julia repository, albeit on a much more modest scale.

Please open pull requests against the master branch rather than any of the release-* branches whenever possible.

Backports

Bug fixes are backported to the release-* branches using git cherry-pick -x by a JuliaDocs member and will become available in point releases of that particular minor version of the package.

Feel free to nominate commits that should be backported by opening an issue. Requests for new point releases to be tagged in METADATA.jl can also be made in the same way.

release-* branches

  • Each new minor version x.y.0 gets a branch called release-x.y (a protected branch).
  • New versions are usually tagged only from the release-x.y branches.
  • For patch releases, changes get backported to the release-x.y branch via a single PR with the standard name "Backports for x.y.z" and label "Type: Backport". The PR message links to all the PRs that are providing commits to the backport. The PR gets merged as a merge commit (i.e. not squashed).
  • The old release-* branches may be removed once they have outlived their usefulness.
  • Patch version milestones are used to keep track of which PRs get backported etc.

Style Guide

Follow the style of the surrounding text when making changes. When adding new features please try to stick to the following points whenever applicable.

Julia

  • 4-space indentation;
  • modules spanning entire files should not be indented, but modules that have surrounding code should;
  • no blank lines at the start or end of files;
  • do not manually align syntax such as = or :: over adjacent lines;
  • use function ... end when a method definition contains more than one toplevel expression;
  • related short-form method definitions don't need a new line between them;
  • unrelated or long-form method definitions must have a blank line separating each one;
  • surround all binary operators with whitespace except for ::, ^, and :;
  • files containing a single module ... end must be named after the module;
  • method arguments should be ordered based on the amount of usage within the method body;
  • methods extended from other modules must follow their inherited argument order, not the above rule;
  • explicit return should be preferred except in short-form method definitions;
  • avoid dense expressions where possible e.g. prefer nested ifs over complex nested ?s;
  • include a trailing , in vectors, tuples, or method calls that span several lines;
  • do not use multiline comments (#= and =#);
  • wrap long lines as near to 92 characters as possible, this includes docstrings;
  • follow the standard naming conventions used in Base.

Markdown

  • Use unbalanced # headers, i.e. no # on the right hand side of the header text;
  • include a single blank line between toplevel blocks;
  • unordered lists must use * bullets with two preceding spaces;
  • do not hard wrap lines;
  • use emphasis (*) and bold (**) sparingly;
  • always use fenced code blocks instead of indented blocks;
  • follow the conventions outlined in the Julia documentation page on documentation.
+
GitHub

Contributing

This page details the some of the guidelines that should be followed when contributing to this package.

Branches

From Documenter version 0.3 onwards release-* branches are used for tagged minor versions of this package. This follows the same approach used in the main Julia repository, albeit on a much more modest scale.

Please open pull requests against the master branch rather than any of the release-* branches whenever possible.

Backports

Bug fixes are backported to the release-* branches using git cherry-pick -x by a JuliaDocs member and will become available in point releases of that particular minor version of the package.

Feel free to nominate commits that should be backported by opening an issue. Requests for new point releases to be tagged in METADATA.jl can also be made in the same way.

release-* branches

  • Each new minor version x.y.0 gets a branch called release-x.y (a protected branch).
  • New versions are usually tagged only from the release-x.y branches.
  • For patch releases, changes get backported to the release-x.y branch via a single PR with the standard name "Backports for x.y.z" and label "Type: Backport". The PR message links to all the PRs that are providing commits to the backport. The PR gets merged as a merge commit (i.e. not squashed).
  • The old release-* branches may be removed once they have outlived their usefulness.
  • Patch version milestones are used to keep track of which PRs get backported etc.

Style Guide

Follow the style of the surrounding text when making changes. When adding new features please try to stick to the following points whenever applicable.

Julia

  • 4-space indentation;
  • modules spanning entire files should not be indented, but modules that have surrounding code should;
  • no blank lines at the start or end of files;
  • do not manually align syntax such as = or :: over adjacent lines;
  • use function ... end when a method definition contains more than one toplevel expression;
  • related short-form method definitions don't need a new line between them;
  • unrelated or long-form method definitions must have a blank line separating each one;
  • surround all binary operators with whitespace except for ::, ^, and :;
  • files containing a single module ... end must be named after the module;
  • method arguments should be ordered based on the amount of usage within the method body;
  • methods extended from other modules must follow their inherited argument order, not the above rule;
  • explicit return should be preferred except in short-form method definitions;
  • avoid dense expressions where possible e.g. prefer nested ifs over complex nested ?s;
  • include a trailing , in vectors, tuples, or method calls that span several lines;
  • do not use multiline comments (#= and =#);
  • wrap long lines as near to 92 characters as possible, this includes docstrings;
  • follow the standard naming conventions used in Base.

Markdown

  • Use unbalanced # headers, i.e. no # on the right hand side of the header text;
  • include a single blank line between toplevel blocks;
  • unordered lists must use * bullets with two preceding spaces;
  • do not hard wrap lines;
  • use emphasis (*) and bold (**) sparingly;
  • always use fenced code blocks instead of indented blocks;
  • follow the conventions outlined in the Julia documentation page on documentation.
diff --git a/dev/index.html b/dev/index.html index f7525329b6..9fe0a608ae 100644 --- a/dev/index.html +++ b/dev/index.html @@ -3,4 +3,4 @@ function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'UA-136089579-2', {'page_path': location.pathname + location.search + location.hash}); -
GitHub

Documenter.jl

A documentation generator for Julia.

A package for building documentation from docstrings and markdown files.

Note

Please read through the Documentation section of the main Julia manual if this is your first time using Julia's documentation system. Once you've read through how to write documentation for your code then come back here.

Package Features

  • Write all your documentation in Markdown.
  • Minimal configuration.
  • Doctests Julia code blocks.
  • Cross references for docs and section headers.
  • $\LaTeX$ syntax support.
  • Checks for missing docstrings and incorrect cross references.
  • Generates tables of contents and docstring indexes.
  • Automatically builds and deploys docs from Travis to GitHub Pages.

The Package Guide provides a tutorial explaining how to get started using Documenter.

Some examples of packages using Documenter can be found on the Examples page.

See the Index for the complete list of documented functions and types.

Manual Outline

Library Outline

Index

+
GitHub

Documenter.jl

A documentation generator for Julia.

A package for building documentation from docstrings and markdown files.

Note

Please read through the Documentation section of the main Julia manual if this is your first time using Julia's documentation system. Once you've read through how to write documentation for your code then come back here.

Package Features

  • Write all your documentation in Markdown.
  • Minimal configuration.
  • Doctests Julia code blocks.
  • Cross references for docs and section headers.
  • $\LaTeX$ syntax support.
  • Checks for missing docstrings and incorrect cross references.
  • Generates tables of contents and docstring indexes.
  • Automatically builds and deploys docs from Travis to GitHub Pages.

The Package Guide provides a tutorial explaining how to get started using Documenter.

Some examples of packages using Documenter can be found on the Examples page.

See the Index for the complete list of documented functions and types.

Manual Outline

Library Outline

Index

diff --git a/dev/lib/internals/anchors/index.html b/dev/lib/internals/anchors/index.html index 39d9b8956c..a94408006c 100644 --- a/dev/lib/internals/anchors/index.html +++ b/dev/lib/internals/anchors/index.html @@ -3,8 +3,8 @@ function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'UA-136089579-2', {'page_path': location.pathname + location.search + location.hash}); -
GitHub

Anchors

Documenter.Anchor — Type

Stores an arbitrary object called .object and it's location within a document.

Fields

  • object – the stored object.
  • order – ordering of object within the entire document.
  • file – the destination file, in build, where the object will be written to.
  • id – the generated "slug" identifying the object.
  • nth – integer that unique-ifies anchors with the same id.
source
Documenter.AnchorMap — Type

Tree structure representing anchors in a document and their relationships with each other.

Object Hierarchy

id -> file -> anchors

Each id maps to a file which in turn maps to a vector of Anchor objects.

source
Documenter.anchor — Method
anchor(m, id)
-

Returns the Anchor object matching id. file and n may also be provided. An Anchor is returned, or nothing in case of no match.

source
Documenter.anchor_exists — Method
anchor_exists(m, id, file, n)
-

Does the given id exist within the AnchorMap? A file and integer n may also be provided to narrow the search for existence.

source
+
GitHub

Anchors

Documenter.Anchor — Type

Stores an arbitrary object called .object and it's location within a document.

Fields

  • object – the stored object.
  • order – ordering of object within the entire document.
  • file – the destination file, in build, where the object will be written to.
  • id – the generated "slug" identifying the object.
  • nth – integer that unique-ifies anchors with the same id.
source
Documenter.AnchorMap — Type

Tree structure representing anchors in a document and their relationships with each other.

Object Hierarchy

id -> file -> anchors

Each id maps to a file which in turn maps to a vector of Anchor objects.

source
Documenter.anchor — Method
anchor(m, id)
+

Returns the Anchor object matching id. file and n may also be provided. An Anchor is returned, or nothing in case of no match.

source
Documenter.anchor_exists — Method
anchor_exists(m, id, file, n)
+

Does the given id exist within the AnchorMap? A file and integer n may also be provided to narrow the search for existence.

source
diff --git a/dev/lib/internals/builder/index.html b/dev/lib/internals/builder/index.html index 76797ab2e4..45731f3e0d 100644 --- a/dev/lib/internals/builder/index.html +++ b/dev/lib/internals/builder/index.html @@ -3,5 +3,5 @@ function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'UA-136089579-2', {'page_path': location.pathname + location.search + location.hash}); -
GitHub

Builder

Documenter.lt_page — Method
lt_page(a::AbstractString, b::AbstractString)

Checks if the page path a should come before b in a sorted list. Falls back to standard string sorting, except for prioritizing index.md (i.e. index.md always comes first).

source
Documenter.walk_navpages — Method
walk_navpages(visible, title, src, children, parent, doc)
-

Recursively walks through the Document's .user.pages field, generating NavNodes and related data structures in the process.

This implementation is the de facto specification for the .user.pages field.

source
Documenter.Builder — Module

Defines the Documenter.jl build "pipeline" named DocumentPipeline.

Each stage of the pipeline performs an action on a Document object. These actions may involve creating directory structures, expanding templates, running doctests, etc.

source
+
GitHub

Builder

Documenter.lt_page — Method
lt_page(a::AbstractString, b::AbstractString)

Checks if the page path a should come before b in a sorted list. Falls back to standard string sorting, except for prioritizing index.md (i.e. index.md always comes first).

source
Documenter.walk_navpages — Method
walk_navpages(visible, title, src, children, parent, doc)
+

Recursively walks through the Document's .user.pages field, generating NavNodes and related data structures in the process.

This implementation is the de facto specification for the .user.pages field.

source
Documenter.Builder — Module

Defines the Documenter.jl build "pipeline" named DocumentPipeline.

Each stage of the pipeline performs an action on a Document object. These actions may involve creating directory structures, expanding templates, running doctests, etc.

source
diff --git a/dev/lib/internals/docchecks/index.html b/dev/lib/internals/docchecks/index.html index 7d73528d95..7bac585b6c 100644 --- a/dev/lib/internals/docchecks/index.html +++ b/dev/lib/internals/docchecks/index.html @@ -4,6 +4,6 @@ gtag('js', new Date()); gtag('config', 'UA-136089579-2', {'page_path': location.pathname + location.search + location.hash});
GitHub

DocChecks

Documenter.missingdocs — Method
missingdocs(doc)
-

Checks that a Document contains all available docstrings that are defined in the modules keyword passed to makedocs.

Prints out the name of each object that has not had its docs spliced into the document.

Returns the number of missing bindings to allow for automated testing of documentation.

source
+

Checks footnote links in a Document.

source
Documenter.linkcheck — Method
linkcheck(doc)
+

Checks external links using curl.

source
Documenter.missingdocs — Method
missingdocs(doc)
+

Checks that a Document contains all available docstrings that are defined in the modules keyword passed to makedocs.

Prints out the name of each object that has not had its docs spliced into the document.

Returns the number of missing bindings to allow for automated testing of documentation.

source
diff --git a/dev/lib/internals/docmeta/index.html b/dev/lib/internals/docmeta/index.html index eee57a491b..e30c293570 100644 --- a/dev/lib/internals/docmeta/index.html +++ b/dev/lib/internals/docmeta/index.html @@ -3,4 +3,4 @@ function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'UA-136089579-2', {'page_path': location.pathname + location.search + location.hash}); -
GitHub
+
GitHub
diff --git a/dev/lib/internals/docsystem/index.html b/dev/lib/internals/docsystem/index.html index 10c0ae8783..17536b0591 100644 --- a/dev/lib/internals/docsystem/index.html +++ b/dev/lib/internals/docsystem/index.html @@ -3,15 +3,15 @@ function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'UA-136089579-2', {'page_path': location.pathname + location.search + location.hash}); -
GitHub

DocSystem

Documenter.DocSystem — Module

Provides a consistent interface to retrieving DocStr objects from the Julia docsystem in both 0.4 and 0.5.

source
Documenter.DocSystem.binding — Method

Converts an object to a Base.Docs.Binding object.

binding(any)
-

Supported inputs are:

  • Binding
  • DataType
  • Function
  • Module
  • Symbol

Note that unsupported objects will throw an ArgumentError.

source
Documenter.DocSystem.docstr — Method
docstr(md; kws...)
-

Construct a DocStr object from a Markdown.MD object.

The optional keyword arguments are used to add new data to the DocStr's .data dictionary.

source
Documenter.DocSystem.getdocs — Function
getdocs(binding)
+
GitHub
DocSystem
Documenter.DocSystem — Module
Provides a consistent interface to retrieving DocStr objects from the Julia docsystem in both 0.4 and 0.5.
source
Documenter.DocSystem.binding — Method
Converts an object to a Base.Docs.Binding object.
binding(any)
+
Supported inputs are:
  • Binding
  • DataType
  • Function
  • Module
  • Symbol
Note that unsupported objects will throw an ArgumentError.
source
Documenter.DocSystem.docstr — Method
docstr(md; kws...)
+
Construct a DocStr object from a Markdown.MD object.
The optional keyword arguments are used to add new data to the DocStr's .data dictionary.
source
Documenter.DocSystem.getdocs — Function
getdocs(binding)
 getdocs(binding, typesig; compare, modules, aliases)
-
Find all DocStr objects that somehow match the provided arguments. That is, if getspecificdocs fails, get docs for aliases of binding (unless aliases is set to false). For compare being == also try getting docs for <:.
source
Documenter.DocSystem.getdocs — Function
getdocs(object)
+
Find all DocStr objects that somehow match the provided arguments. That is, if getspecificdocs fails, get docs for aliases of binding (unless aliases is set to false). For compare being == also try getting docs for <:.
source
Documenter.DocSystem.getdocs — Function
getdocs(object)
 getdocs(object, typesig; kws...)
-
Accepts objects of any type and tries to convert them to Bindings before searching for the Binding in the docsystem.
Note that when conversion fails this method returns an empty Vector{DocStr}.
source
Documenter.DocSystem.getspecificdocs — Function
getspecificdocs(binding)
+
Accepts objects of any type and tries to convert them to Bindings before searching for the Binding in the docsystem.
Note that when conversion fails this method returns an empty Vector{DocStr}.
source
Documenter.DocSystem.getspecificdocs — Function
getspecificdocs(binding)
 getspecificdocs(binding, typesig)
 getspecificdocs(binding, typesig, compare)
 getspecificdocs(binding, typesig, compare, modules)
-
Find all DocStr objects that match the provided arguments exactly.
  • binding: the name of the object.
  • typesig: the signature of the object. Default: Union{}.
  • compare: how to compare signatures? (== (default), <: or >:)
  • modules: which modules to search through. Default: all modules.
Return a Vector{DocStr} ordered by definition order.
source
Documenter.DocSystem.parsedoc — Method
DocSystem.parsedoc(docstr::DocStr)
Thin internal wrapper around Base.Docs.parsedoc which prints additional debug information in case Base.Docs.parsedoc fails with an exception.
source

+

Find all DocStr objects that match the provided arguments exactly.

  • binding: the name of the object.
  • typesig: the signature of the object. Default: Union{}.
  • compare: how to compare signatures? (== (default), <: or >:)
  • modules: which modules to search through. Default: all modules.

Return a Vector{DocStr} ordered by definition order.

source
Documenter.DocSystem.parsedoc — Method
DocSystem.parsedoc(docstr::DocStr)

Thin internal wrapper around Base.Docs.parsedoc which prints additional debug information in case Base.Docs.parsedoc fails with an exception.

source
diff --git a/dev/lib/internals/doctests/index.html b/dev/lib/internals/doctests/index.html index 8d42c74f81..1376efa045 100644 --- a/dev/lib/internals/doctests/index.html +++ b/dev/lib/internals/doctests/index.html @@ -4,4 +4,4 @@ gtag('js', new Date()); gtag('config', 'UA-136089579-2', {'page_path': location.pathname + location.search + location.hash});
GitHub

DocTests

Documenter._doctest — Method
_doctest(blueprint, doc)
-

Traverses the pages and modules in the documenter blueprint, searching and executing doctests.

Will abort the document generation when an error is thrown. Use doctest = false keyword in Documenter.makedocs to disable doctesting.

source
+

Traverses the pages and modules in the documenter blueprint, searching and executing doctests.

Will abort the document generation when an error is thrown. Use doctest = false keyword in Documenter.makedocs to disable doctesting.

source diff --git a/dev/lib/internals/documenter/index.html b/dev/lib/internals/documenter/index.html index cb1a71f991..3b36aeeaca 100644 --- a/dev/lib/internals/documenter/index.html +++ b/dev/lib/internals/documenter/index.html @@ -3,10 +3,10 @@ function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'UA-136089579-2', {'page_path': location.pathname + location.search + location.hash}); -
GitHub

Documenter

Documenter.gitrm_copy — Function
gitrm_copy(src, dst)

Uses git rm -r to remove dst and then copies src to dst. Assumes that the working directory is within the git repository of dst is when the function is called.

This is to get around #507 on filesystems that are case-insensitive (e.g. on OS X, Windows). Without doing a git rm first, git add -A will not detect case changes in filenames.

source
Documenter.git_push — Function
git_push(
+
GitHub
Documenter
Documenter.gitrm_copy — Function
gitrm_copy(src, dst)
Uses git rm -r to remove dst and then copies src to dst. Assumes that the working directory is within the git repository of dst is when the function is called.
This is to get around #507 on filesystems that are case-insensitive (e.g. on OS X, Windows). Without doing a git rm first, git add -A will not detect case changes in filenames.
source
Documenter.git_push — Function
git_push(
     root, tmp, repo;
     branch="gh-pages", dirname="", target="site", sha="", devurl="dev",
     deploy_config, folder,
-)
Handles pushing changes to the remote documentation branch. The documentation are placed in the folder specified by subfolder.
source
Documenter.user_host_upstream — Function
user_host_upstream(repo)
Disassemble repo address into user, host, and path to repo. If no user is given, default to "git". Reassemble user, host and path into an upstream to git push to.
source
Documenter.find_object — Function
find_object(doc, binding, typesig)
-
Find the included Object in the doc matching binding and typesig. The matching heuristic isn't too picky about what matches and will only fail when no Bindings matching binding have been included.
source
Documenter.xrefname — Function
Parse the link.url field of an at-ref link. Returns nothing if it's not an at-ref, an empty string the reference link has no label, or a whitespace-stripped version the label.
source

+)

Handles pushing changes to the remote documentation branch. The documentation are placed in the folder specified by subfolder.

source
Documenter.user_host_upstream — Function
user_host_upstream(repo)

Disassemble repo address into user, host, and path to repo. If no user is given, default to "git". Reassemble user, host and path into an upstream to git push to.

source
Documenter.find_object — Function
find_object(doc, binding, typesig)
+

Find the included Object in the doc matching binding and typesig. The matching heuristic isn't too picky about what matches and will only fail when no Bindings matching binding have been included.

source
Documenter.xrefname — Function

Parse the link.url field of an at-ref link. Returns nothing if it's not an at-ref, an empty string the reference link has no label, or a whitespace-stripped version the label.

source
diff --git a/dev/lib/internals/documentertools/index.html b/dev/lib/internals/documentertools/index.html index 2b7e436294..683c21d173 100644 --- a/dev/lib/internals/documentertools/index.html +++ b/dev/lib/internals/documentertools/index.html @@ -14,4 +14,4 @@ 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.

source
DocumenterTools.Themes.compile — Function
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.

source
DocumenterTools.Themes.compile_native_theme — Method
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.

source
DocumenterTools.Themes.themewatcher — Method
themewatcher()

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

source
+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.

source
DocumenterTools.Themes.compile — Function
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.

source
DocumenterTools.Themes.compile_native_theme — Method
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.

source
DocumenterTools.Themes.themewatcher — Method
themewatcher()

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

source
diff --git a/dev/lib/internals/documents/index.html b/dev/lib/internals/documents/index.html index 732a23ddb4..7981bc4f1b 100644 --- a/dev/lib/internals/documents/index.html +++ b/dev/lib/internals/documents/index.html @@ -3,7 +3,7 @@ function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'UA-136089579-2', {'page_path': location.pathname + location.search + location.hash}); -
GitHub

Documents

Documenter.LocalImage — Type

Represents a reference to a local image. The path can be assumed to be an "absolute" path relative to the document root (i.e. src/ or build/ directories). See LocalLink for more details.

source
Documenter.LocalLink — Type

Represents a reference to a local file. The path can be assumed to be an "absolute" path relative to the document root (i.e. src/ or build/ directories).

In the standard setup, when the documentation setup lives in docs/, with source files in docs/src, a link to the file docs/src/foo/bar.md would have path = "foo/bar.md".

source
Documenter.NavNode — Type

Element in the navigation tree of a document, containing navigation references to other page, reference to the Page object etc.

source
Documenter.getplugin — Method
getplugin(doc::Document, T)

Retrieves the Plugin type for T stored in doc. If T was passed to makedocs, the passed type will be returned. Otherwise, a new T object will be created using the default constructor T().

source
Documenter.is_strict — Method
is_strict(::Document, val::Symbol) -> Bool

Internal function to check if Documenter should throw an error or simply print a warning when hitting error condition.

Single-argument is_strict(strict) provides a curried function.

source
Documenter.navpath — Method

Constructs a list of the ancestors of the navnode (including the navnode itself), ordered so that the root of the navigation tree is the first and navnode itself is the last item.

source
Documenter.populate! — Method
populate!(document)
-

Populates the ContentsNodes and IndexNodes of the document with links.

This can only be done after all the blocks have been expanded (and nodes constructed), because the items have to exist before we can gather the links to those items.

source
Documenter.relpath_from_remote_root — Method
relpath_from_remote_root(remotes, path)
-

Returns the the the remote that contains the file, and the relative path of the file within the repo (or nothing, nothing if the file is not in a known repo).

source
+
GitHub

Documents

Documenter.LocalImage — Type

Represents a reference to a local image. The path can be assumed to be an "absolute" path relative to the document root (i.e. src/ or build/ directories). See LocalLink for more details.

source
Documenter.LocalLink — Type

Represents a reference to a local file. The path can be assumed to be an "absolute" path relative to the document root (i.e. src/ or build/ directories).

In the standard setup, when the documentation setup lives in docs/, with source files in docs/src, a link to the file docs/src/foo/bar.md would have path = "foo/bar.md".

source
Documenter.NavNode — Type

Element in the navigation tree of a document, containing navigation references to other page, reference to the Page object etc.

source
Documenter.getplugin — Method
getplugin(doc::Document, T)

Retrieves the Plugin type for T stored in doc. If T was passed to makedocs, the passed type will be returned. Otherwise, a new T object will be created using the default constructor T().

source
Documenter.is_strict — Method
is_strict(::Document, val::Symbol) -> Bool

Internal function to check if Documenter should throw an error or simply print a warning when hitting error condition.

Single-argument is_strict(strict) provides a curried function.

source
Documenter.navpath — Method

Constructs a list of the ancestors of the navnode (including the navnode itself), ordered so that the root of the navigation tree is the first and navnode itself is the last item.

source
Documenter.populate! — Method
populate!(document)
+

Populates the ContentsNodes and IndexNodes of the document with links.

This can only be done after all the blocks have been expanded (and nodes constructed), because the items have to exist before we can gather the links to those items.

source
Documenter.relpath_from_remote_root — Method
relpath_from_remote_root(remotes, path)
+

Returns the the the remote that contains the file, and the relative path of the file within the repo (or nothing, nothing if the file is not in a known repo).

source
diff --git a/dev/lib/internals/dom/index.html b/dev/lib/internals/dom/index.html index a8a78ee478..9253fd3c9e 100644 --- a/dev/lib/internals/dom/index.html +++ b/dev/lib/internals/dom/index.html @@ -27,8 +27,8 @@ tag[:src => "foo.jpg"] # ... or any combination of the above arguments.

Internal Representation

The @tags macro defines named Tag objects as follows

@tags div p em strong

expands to

const div, p, em, strong = Tag(:div), Tag(:p), Tag(:em), Tag(:strong)

These Tag objects are lightweight representations of empty HTML elements without any attributes and cannot be used to represent a complete document. To create an actual tree of HTML elements that can be rendered we need to add some attributes and/or child elements using getindex or call syntax. Applying either to a Tag object will construct a new Node object.

tag(...)      # No attributes.
 tag[...]      # No children.
-tag[...](...) # Has both attributes and children.

All three of the above syntaxes return a new Node object. Printing of Node objects is defined using the standard Julia display functions, so only needs a call to print to print out a valid HTML document with all necessary text escaped.

source
Documenter.DOM.HTMLDocument — Type

A HTML node that wraps around the root node of the document and adds a DOCTYPE to it.

source
Documenter.DOM.Node — Type

Represents an element within an HTML document including any textual content, children Nodes, and attributes.

This type should not be constructed directly, but instead via (...) and [...] applied to a Tag or another Node object.

source
Documenter.DOM.Tag — Type

Represents a empty and attribute-less HTML element.

Use @tags to define instances of this type rather than manually creating them via Tag(:tagname).

source
Documenter.DOM.escapehtml — Method

Escape characters in the provided string. This converts the following characters:

  • < to &lt;
  • > to &gt;
  • & to &amp;
  • ' to &#39;
  • " to &quot;

When no escaping is needed then the same object is returned, otherwise a new string is constructed with the characters escaped. The returned object should always be treated as an immutable copy and compared using == rather than ===.

source
Documenter.DOM.flatten! — Method

Signatures

flatten!(f!, out, x::Atom)
-flatten!(f!, out, xs)

Flatten the contents the third argument into the second after applying the function f! to the element.

source
Documenter.DOM.@tags — Macro

Define a collection of Tag objects and bind them to constants with the same names.

Examples

Defined globally within a module:

@tags div ul li

Defined within the scope of a function to avoid cluttering the global namespace:

function template(args...)
+tag[...](...) # Has both attributes and children.

All three of the above syntaxes return a new Node object. Printing of Node objects is defined using the standard Julia display functions, so only needs a call to print to print out a valid HTML document with all necessary text escaped.

source
Documenter.DOM.HTMLDocument — Type

A HTML node that wraps around the root node of the document and adds a DOCTYPE to it.

source
Documenter.DOM.Node — Type

Represents an element within an HTML document including any textual content, children Nodes, and attributes.

This type should not be constructed directly, but instead via (...) and [...] applied to a Tag or another Node object.

source
Documenter.DOM.Tag — Type

Represents a empty and attribute-less HTML element.

Use @tags to define instances of this type rather than manually creating them via Tag(:tagname).

source
Documenter.DOM.escapehtml — Method

Escape characters in the provided string. This converts the following characters:

  • < to &lt;
  • > to &gt;
  • & to &amp;
  • ' to &#39;
  • " to &quot;

When no escaping is needed then the same object is returned, otherwise a new string is constructed with the characters escaped. The returned object should always be treated as an immutable copy and compared using == rather than ===.

source
Documenter.DOM.flatten! — Method

Signatures

flatten!(f!, out, x::Atom)
+flatten!(f!, out, xs)

Flatten the contents the third argument into the second after applying the function f! to the element.

source
Documenter.DOM.@tags — Macro

Define a collection of Tag objects and bind them to constants with the same names.

Examples

Defined globally within a module:

@tags div ul li

Defined within the scope of a function to avoid cluttering the global namespace:

function template(args...)
     @tags div ul li
     # ...
-end
source
+endsource diff --git a/dev/lib/internals/expanders/index.html b/dev/lib/internals/expanders/index.html index a28c00629f..86e86debcf 100644 --- a/dev/lib/internals/expanders/index.html +++ b/dev/lib/internals/expanders/index.html @@ -3,32 +3,32 @@ function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'UA-136089579-2', {'page_path': location.pathname + location.search + location.hash}); -
GitHub

Expanders

Documenter.expand_recursively — Method

Similar to expand(), but recursively calls itself on all descendants of node and applies NestedExpanderPipeline instead of ExpanderPipeline.

source
Documenter.Expanders.AutoDocsBlocks — Type

Parses each code block where the language is @autodocs and replaces it with all the docstrings that match the provided key/value pairs Modules = ... and Order = ....

```@autodocs
+
GitHub
Expanders
Documenter.expand_recursively — Method
Similar to expand(), but recursively calls itself on all descendants of node and applies NestedExpanderPipeline instead of ExpanderPipeline.
source
Documenter.Expanders.AutoDocsBlocks — Type
Parses each code block where the language is @autodocs and replaces it with all the docstrings that match the provided key/value pairs Modules = ... and Order = ....
```@autodocs
 Modules = [Foo, Bar]
 Order   = [:function, :type]
-```
source
Documenter.Expanders.ContentsBlocks — Type
Parses each code block where the language is @contents and replaces it with a nested list of all Header nodes in the generated document. The pages and depth of the list can be set using Pages = [...] and Depth = N where N is and integer.
```@contents
+```
source
Documenter.Expanders.ContentsBlocks — Type
Parses each code block where the language is @contents and replaces it with a nested list of all Header nodes in the generated document. The pages and depth of the list can be set using Pages = [...] and Depth = N where N is and integer.
```@contents
 Pages = ["foo.md", "bar.md"]
 Depth = 1
-```
The default Depth value is 2.
source
Documenter.Expanders.DocsBlocks — Type
Parses each code block where the language is @docs and evaluates the expressions found within the block. Replaces the block with the docstrings associated with each expression.
```@docs
+```
The default Depth value is 2.
source
Documenter.Expanders.DocsBlocks — Type
Parses each code block where the language is @docs and evaluates the expressions found within the block. Replaces the block with the docstrings associated with each expression.
```@docs
 Documenter
 makedocs
 deploydocs
-```
source
Documenter.Expanders.EvalBlocks — Type
Parses each code block where the language is @eval and evaluates it's content. Replaces the block with the value resulting from the evaluation. This can be useful for inserting generated content into a document such as plots.
```@eval
+```
source
Documenter.Expanders.EvalBlocks — Type
Parses each code block where the language is @eval and evaluates it's content. Replaces the block with the value resulting from the evaluation. This can be useful for inserting generated content into a document such as plots.
```@eval
 using PyPlot
 x = linspace(-π, π)
 y = sin(x)
 plot(x, y, color = "red")
 savefig("plot.svg")
 Markdown.parse("![Plot](plot.svg)")
-```
source
Documenter.Expanders.ExampleBlocks — Type
Parses each code block where the language is @example and evaluates the parsed Julia code found within. The resulting value is then inserted into the final document after the source code.
```@example
+```
source
Documenter.Expanders.ExampleBlocks — Type
Parses each code block where the language is @example and evaluates the parsed Julia code found within. The resulting value is then inserted into the final document after the source code.
```@example
 a = 1
 b = 2
 a + b
-```
source
Documenter.Expanders.IndexBlocks — Type
Parses each code block where the language is @index and replaces it with an index of all docstrings spliced into the document. The pages that are included can be set using a key/value pair Pages = [...] such as
```@index
+```
source
Documenter.Expanders.IndexBlocks — Type
Parses each code block where the language is @index and replaces it with an index of all docstrings spliced into the document. The pages that are included can be set using a key/value pair Pages = [...] such as
```@index
 Pages = ["foo.md", "bar.md"]
-```
source
Documenter.Expanders.MetaBlocks — Type
Parses each code block where the language is @meta and evaluates the key/value pairs found within the block, i.e.
```@meta
 CurrentModule = Documenter
 DocTestSetup  = quote
     using Documenter
 end
-```
source

+```
source
diff --git a/dev/lib/internals/jsdependencies/index.html b/dev/lib/internals/jsdependencies/index.html index 7d99fa07a8..77b95642de 100644 --- a/dev/lib/internals/jsdependencies/index.html +++ b/dev/lib/internals/jsdependencies/index.html @@ -3,12 +3,12 @@ function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'UA-136089579-2', {'page_path': location.pathname + location.search + location.hash}); -
GitHub

JSDependencies

Documenter.JSDependencies.RemoteLibrary — Type
struct RemoteLibrary

Declares a remote JS dependency that should be declared in the RequireJS configuration shim.

Fields

  • name: a unique name for the dependency, used to refer to it in other dependencies and snippets
  • url: full remote URL from where the dependency can be loaded from
  • deps: a list of the library's dependencies (becomes the deps configuration in the RequireJS shim)
  • exports: sets the exports config in the resulting RequireJS shim

Constructors

RemoteLibrary(name::AbstractString, url::AbstractString; deps=String[], exports=nothing)
source
Documenter.JSDependencies.RequireJS — Type
struct RequireJS

Declares a single RequireJS configuration/app file.

Fields

  • libraries: a dictionary of RemoteLibrary declarations (keys are the library names)
  • snippets: a list of JS snippets (Snippet)

Constructors

RequireJS(libraries::AbstractVector{RemoteLibrary}, snippets::AbstractVector{Snippet} = Snippet[])

API

  • The push! function can be used to add additional libraries and snippets.
source
Documenter.JSDependencies.Snippet — Type
struct Snippet

Declares a JS code snipped that should be loaded with RequireJS. This gets wrapped in require([deps...], function(args...) {script...}) in the output.

Fields

  • deps: names of the RemoteLibrary dependencies of the snippet
  • args: the arguments of the callback function, corresponding to the library objects of the dependencies, in the order of deps
  • js: the JS code of the function that gets used as the function body of the callback

Constructors

Snippet(deps::AbstractVector, args::AbstractVector, js::AbstractString)
source
Documenter.JSDependencies.json_jsescape — Method
json_jsescape(args...)

Call JSON.json(args...) to generate a String of JSON, but then also escape two Unicode characters to get valid JS (since JSON is not a JS subset).

Note

Technically, starting with ECMAScript® 2019 (10th edition), this is no longer necessary. The JS standard was changed in a way that all valid JSON is also valid JS.

source
Documenter.JSDependencies.parse_snippet — Function
parse_snippet(filename::AbstractString) -> Snippet
+
GitHub
JSDependencies
Documenter.JSDependencies.RemoteLibrary — Type
struct RemoteLibrary
Declares a remote JS dependency that should be declared in the RequireJS configuration shim.
Fields
  • name: a unique name for the dependency, used to refer to it in other dependencies and snippets
  • url: full remote URL from where the dependency can be loaded from
  • deps: a list of the library's dependencies (becomes the deps configuration in the RequireJS shim)
  • exports: sets the exports config in the resulting RequireJS shim
Constructors
RemoteLibrary(name::AbstractString, url::AbstractString; deps=String[], exports=nothing)
source
Documenter.JSDependencies.RequireJS — Type
struct RequireJS
Declares a single RequireJS configuration/app file.
Fields
  • libraries: a dictionary of RemoteLibrary declarations (keys are the library names)
  • snippets: a list of JS snippets (Snippet)
Constructors
RequireJS(libraries::AbstractVector{RemoteLibrary}, snippets::AbstractVector{Snippet} = Snippet[])
API
  • The push! function can be used to add additional libraries and snippets.
source
Documenter.JSDependencies.Snippet — Type
struct Snippet
Declares a JS code snipped that should be loaded with RequireJS. This gets wrapped in require([deps...], function(args...) {script...}) in the output.
Fields
  • deps: names of the RemoteLibrary dependencies of the snippet
  • args: the arguments of the callback function, corresponding to the library objects of the dependencies, in the order of deps
  • js: the JS code of the function that gets used as the function body of the callback
Constructors
Snippet(deps::AbstractVector, args::AbstractVector, js::AbstractString)
source
Documenter.JSDependencies.json_jsescape — Method
json_jsescape(args...)
Call JSON.json(args...) to generate a String of JSON, but then also escape two Unicode characters to get valid JS (since JSON is not a JS subset).
Note
Technically, starting with ECMAScript® 2019 (10th edition), this is no longer necessary. The JS standard was changed in a way that all valid JSON is also valid JS.
source
Documenter.JSDependencies.parse_snippet — Function
parse_snippet(filename::AbstractString) -> Snippet
 parse_snippet(io::IO) -> Snippet
Parses a JS snippet file into a Snippet object.
Format
The first few lines are parsed to get the dependencies and argument variable names of the snippet. They need to match ^//\s*([a-z]+): (i.e. start with //, optional whitespace, a lowercase identifier, and a colon). Once the parser hits a line that does not match that pattern, it will assume that it and all the following lines are the actual script.
Only lowercase letters are allowed in the identifiers. Currently only libraries and arguments are actually parsed and lines with other syntactically valid identifiers are ignored. For libraries and arguments, the value (after the colon) must be a comma separated list.
A valid snippet file would look like the following. Note that the list of arguments can be shorter than the list of dependencies.
// libraries: jquery, highlight, highlight-julia, highlight-julia-repl
 // arguments: $, hljs
 
 // Initialize the highlight.js highlighter
 $(document).ready(function() {
   hljs.initHighlighting();
-})
source
Documenter.JSDependencies.verify — Method
verify(r::RequireJS; verbose=false) -> Bool
Checks that none of the dependencies are missing (returns false if some are). If verbose is set to true, it will also log an error with the missing dependency.
source
Documenter.JSDependencies.writejs — Function
writejs(io::IO, r::RequireJS)
-writejs(filename::AbstractString, r::RequireJS)
Writes out the RequireJS object as a valid JS that can be loaded with a <script> tag, either into a stream or a file. It will contain all the configuration and snippets.
source

+})
source
Documenter.JSDependencies.verify — Method
verify(r::RequireJS; verbose=false) -> Bool

Checks that none of the dependencies are missing (returns false if some are). If verbose is set to true, it will also log an error with the missing dependency.

source
Documenter.JSDependencies.writejs — Function
writejs(io::IO, r::RequireJS)
+writejs(filename::AbstractString, r::RequireJS)

Writes out the RequireJS object as a valid JS that can be loaded with a <script> tag, either into a stream or a file. It will contain all the configuration and snippets.

source
diff --git a/dev/lib/internals/mdflatten/index.html b/dev/lib/internals/mdflatten/index.html index b02d5e4efa..1169e9a98e 100644 --- a/dev/lib/internals/mdflatten/index.html +++ b/dev/lib/internals/mdflatten/index.html @@ -3,4 +3,4 @@ function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'UA-136089579-2', {'page_path': location.pathname + location.search + location.hash}); -
GitHub

MDFlatten

Documenter.MDFlatten — Module

Provides the mdflatten function that can "flatten" Markdown objects into a string, with formatting etc. stripped.

Note that the tests in test/mdflatten.jl should be considered to be the spec for the output (number of newlines, indents, formatting, etc.).

source
Documenter.MDFlatten.mdflatten — Method

Convert a Markdown object to a String of only text (i.e. not formatting info).

It drop most of the extra information (e.g. language of a code block, URLs) and formatting (e.g. emphasis, headers). This "flattened" representation can then be used as input for search engines.

source
+
GitHub

MDFlatten

Documenter.MDFlatten — Module

Provides the mdflatten function that can "flatten" Markdown objects into a string, with formatting etc. stripped.

Note that the tests in test/mdflatten.jl should be considered to be the spec for the output (number of newlines, indents, formatting, etc.).

source
Documenter.MDFlatten.mdflatten — Method

Convert a Markdown object to a String of only text (i.e. not formatting info).

It drop most of the extra information (e.g. language of a code block, URLs) and formatting (e.g. emphasis, headers). This "flattened" representation can then be used as input for search engines.

source
diff --git a/dev/lib/internals/selectors/index.html b/dev/lib/internals/selectors/index.html index 52182a837c..0dcc961ba9 100644 --- a/dev/lib/internals/selectors/index.html +++ b/dev/lib/internals/selectors/index.html @@ -36,13 +36,13 @@ elseif i !== 1 println("not found") end -end

The module provides the following interface for creating selectors:

source
Documenter.Selectors.AbstractSelector — Type

Root selector type. Each user-defined selector must subtype from this, i.e.

abstract type MySelector <: Selectors.AbstractSelector end
+end

The module provides the following interface for creating selectors:

source
Documenter.Selectors.AbstractSelector — Type

Root selector type. Each user-defined selector must subtype from this, i.e.

abstract type MySelector <: Selectors.AbstractSelector end
 
 abstract type First  <: MySelector end
-abstract type Second <: MySelector end
source
Documenter.Selectors.disable — Method

Disable a particular case in a selector so that it is never used.

Selectors.disable(::Type{Debug}) = true
source
Documenter.Selectors.dispatch — Method

Call Selectors.runner(T, args...) where T is a subtype of MySelector for which matcher(T, args...) is true.

Selectors.dispatch(MySelector, args...)
source
Documenter.Selectors.leaf_subtypes — Method

Return a list of all subtypes of T which do not have further subtypes.

The returned list includes subtypes of subtypes, and it does not distinguish between concrete types (i.e. types which are guaranteed not to have subtypes) and abstract types (which may or may not have subtypes).

source
Documenter.Selectors.matcher — Function

Define the matching test for each case in a selector, i.e.

Selectors.matcher(::Type{First}, x)  = x == 1
-Selectors.matcher(::Type{Second}, x) = true

Note that the return type must be Bool.

To match against multiple cases use the Selectors.strict function.

source
Documenter.Selectors.order — Function

Define the precedence of each case in a selector, i.e.

Selectors.order(::Type{First})  = 1.0
-Selectors.order(::Type{Second}) = 2.0

Note that the return type must be Float64. Defining multiple case types to have the same order will result in undefined behaviour.

source
Documenter.Selectors.runner — Function

Define the code that will run when a particular Selectors.matcher test returns true, i.e.

Selectors.runner(::Type{First}, x)  = println("`x` is equal to `1`.")
-Selectors.runner(::Type{Second}, x) = println("`x` is not equal to `1`.")
source
Documenter.Selectors.strict — Method

Define whether a selector case will "fallthrough" or not when successfully matched against. By default matching is strict and does not fallthrough to subsequent selector cases.

# Adding a debugging selector case.
+abstract type Second <: MySelector end
source
Documenter.Selectors.disable — Method

Disable a particular case in a selector so that it is never used.

Selectors.disable(::Type{Debug}) = true
source
Documenter.Selectors.dispatch — Method

Call Selectors.runner(T, args...) where T is a subtype of MySelector for which matcher(T, args...) is true.

Selectors.dispatch(MySelector, args...)
source
Documenter.Selectors.leaf_subtypes — Method

Return a list of all subtypes of T which do not have further subtypes.

The returned list includes subtypes of subtypes, and it does not distinguish between concrete types (i.e. types which are guaranteed not to have subtypes) and abstract types (which may or may not have subtypes).

source
Documenter.Selectors.matcher — Function

Define the matching test for each case in a selector, i.e.

Selectors.matcher(::Type{First}, x)  = x == 1
+Selectors.matcher(::Type{Second}, x) = true

Note that the return type must be Bool.

To match against multiple cases use the Selectors.strict function.

source
Documenter.Selectors.order — Function

Define the precedence of each case in a selector, i.e.

Selectors.order(::Type{First})  = 1.0
+Selectors.order(::Type{Second}) = 2.0

Note that the return type must be Float64. Defining multiple case types to have the same order will result in undefined behaviour.

source
Documenter.Selectors.runner — Function

Define the code that will run when a particular Selectors.matcher test returns true, i.e.

Selectors.runner(::Type{First}, x)  = println("`x` is equal to `1`.")
+Selectors.runner(::Type{Second}, x) = println("`x` is not equal to `1`.")
source
Documenter.Selectors.strict — Method

Define whether a selector case will "fallthrough" or not when successfully matched against. By default matching is strict and does not fallthrough to subsequent selector cases.

# Adding a debugging selector case.
 abstract type Debug <: MySelector end
 
 # Insert prior to all other cases.
@@ -55,4 +55,4 @@
 Selectors.matcher(::Type{Debug}, x) = true
 
 # Print some debugging info.
-Selectors.runner(::Type{Debug}, x) = @show x
source
+Selectors.runner(::Type{Debug}, x) = @show xsource diff --git a/dev/lib/internals/textdiff/index.html b/dev/lib/internals/textdiff/index.html index 2ada509e98..fb8ffd5d90 100644 --- a/dev/lib/internals/textdiff/index.html +++ b/dev/lib/internals/textdiff/index.html @@ -4,4 +4,4 @@ gtag('js', new Date()); gtag('config', 'UA-136089579-2', {'page_path': location.pathname + location.search + location.hash});
GitHub

TextDiff

Documenter.TextDiff.splitby — Method
splitby(reg, text)
-

Splits text at regex matches, returning an array of substrings. The parts of the string that match the regular expression are also included at the ends of the returned strings.

source
+

Splits text at regex matches, returning an array of substrings. The parts of the string that match the regular expression are also included at the ends of the returned strings.

source diff --git a/dev/lib/internals/utilities/index.html b/dev/lib/internals/utilities/index.html index 691a4482e4..810c703da5 100644 --- a/dev/lib/internals/utilities/index.html +++ b/dev/lib/internals/utilities/index.html @@ -3,16 +3,16 @@ function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'UA-136089579-2', {'page_path': location.pathname + location.search + location.hash}); -
GitHub

Utilities

Documenter.Default — Type
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"))
+
GitHub
Utilities
Documenter.Default — Type
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.codelang — Method
codelang(infostring)
-
Extracts the language identifier from the info string of a Markdown code block.
source
Documenter.docs — Function
docs(ex, str)
Returns an expression that, when evaluated, returns the docstrings associated with ex.
source
Documenter.filterdocs — Method
filterdocs(doc, modules)
Remove docstrings from the markdown object, doc, that are not from one of modules.
source
Documenter.find_root_parent — Method
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.codelang — Method
codelang(infostring)
+
Extracts the language identifier from the info string of a Markdown code block.
source
Documenter.docs — Function
docs(ex, str)
Returns an expression that, when evaluated, returns the docstrings associated with ex.
source
Documenter.filterdocs — Method
filterdocs(doc, modules)
Remove docstrings from the markdown object, doc, that are not from one of modules.
source
Documenter.find_root_parent — Method
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.getremote — Method
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_branch — Method
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_root — Method
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.issubmodule — Method
issubmodule(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.
source
Documenter.mdparse — Method
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.nodocs — Method
Does the given docstring represent actual documentation or a no docs error message?
source
Documenter.parseblock — Method
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.srcpath — Method
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.@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 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.URL — Type
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/blob/{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.repofile — Function
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

+

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_branch — Method

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_root — Method
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.issubmodule — Method
issubmodule(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.

source
Documenter.mdparse — Method
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.nodocs — Method

Does the given docstring represent actual documentation or a no docs error message?

source
Documenter.parseblock — Method

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.srcpath — Method

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.@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 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.URL — Type
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/blob/{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.repofile — Function
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
diff --git a/dev/lib/internals/writers/index.html b/dev/lib/internals/writers/index.html index caef7040a6..a05cf36403 100644 --- a/dev/lib/internals/writers/index.html +++ b/dev/lib/internals/writers/index.html @@ -9,6 +9,6 @@ Selectors.matcher(::Type{CustomFormat}, fmt, _) = fmt === :custom Selectors.runner(::Type{CustomFormat}, _, doc) = CustomWriter.render(doc) -# Definition of `CustomWriter` module below...source
Documenter.HTMLWriter — Module

A module for rendering Document objects to HTML.

Keywords

HTMLWriter uses the following additional keyword arguments that can be passed to Documenter.makedocs: authors, pages, sitename, version. The behavior of HTMLWriter can be further customized by setting the format keyword of Documenter.makedocs to a HTML, which accepts the following keyword arguments: analytics, assets, canonical, disable_git, edit_link, prettyurls, collapselevel, sidebar_sitename, highlights, mathengine and footer.

sitename is the site's title displayed in the title bar and at the top of the *navigation menu. This argument is mandatory for HTMLWriter.

pages defines the hierarchy of the navigation menu.

Experimental keywords

version specifies the version string of the current version which will be the selected option in the version selector. If this is left empty (default) the version selector will be hidden. The special value git-commit sets the value in the output to git:{commit}, where {commit} is the first few characters of the current commit hash.

HTML Plugin options

The HTML Documenter.Plugin provides additional customization options for the HTMLWriter. For more information, see the HTML documentation.

Page outline

The HTMLWriter makes use of the page outline that is determined by the headings. It is assumed that if the very first block of a page is a level 1 heading, then it is intended as the page title. This has two consequences:

  1. It is then used to automatically determine the page title in the navigation menu and in the <title> tag, unless specified in the .pages option.
  2. If the first heading is interpreted as being the page title, it is not displayed in the navigation sidebar.
source
Documenter.HTMLWriter.ASSETS — Constant

The root directory of the HTML assets.

source
Documenter.HTMLWriter.ASSETS_SASS — Constant

The directory where all the Sass/SCSS files needed for theme building are.

source
Documenter.HTMLWriter.ASSETS_THEMES — Constant

Directory for the compiled CSS files of the themes.

source
Documenter.HTMLWriter.OUTDATED_VERSION_ATTR — Constant

Data attribute for the script inserting a warning for outdated docs.

source
Documenter.HTMLWriter.THEMES — Constant

List of Documenter native themes.

source
Documenter.HTMLWriter.HTML — Type
HTML(kwargs...)

Sets the behavior of HTMLWriter.

Keyword arguments

prettyurls (default true) – allows toggling the pretty URLs feature.

By default (i.e. when prettyurls is set to true), Documenter creates a directory structure that hides the .html suffixes from the URLs (e.g. by default src/foo.md becomes src/foo/index.html, but can be accessed with via src/foo/ in the browser). This structure is preferred when publishing the generate HTML files as a website (e.g. on GitHub Pages), which is Documenter's primary use case.

If prettyurls = false, then Documenter generates src/foo.html instead, suitable for local documentation builds, as browsers do not normally resolve foo/ to foo/index.html for local files.

To have pretty URLs disabled in local builds, but still have them enabled for the automatic CI deployment builds, you can set prettyurls = get(ENV, "CI", nothing) == "true" (the specific environment variable you will need to check may depend on the CI system you are using, but this will work on Travis CI).

disable_git can be used to disable calls to git when the document is not in a Git-controlled repository. Without setting this to true, Documenter will throw an error and exit if any of the Git commands fail. The calls to Git are mainly used to gather information about the current commit hash and file paths, necessary for constructing the links to the remote repository.

edit_link can be used to specify which branch, tag or commit (when passed a String) in the remote repository the edit buttons point to. If a special Symbol value :commit is passed, the current commit will be used instead. If set to nothing, the link edit link will be hidden altogether. By default, Documenter tries to determine it automatically by looking at the origin remote, and falls back to "master" if that fails.

repolink can be used to override the URL of the Git repository link in the top navbar (if passed a String). By default, Documenter attempts to determine the link from the Git remote of the repository (e.g. specified via the remote argument of makedocs). Passing a nothing disables the repository link.

canonical specifies the canonical URL for your documentation. We recommend you set this to the base url of your stable documentation, e.g. https://documenter.juliadocs.org/stable. This allows search engines to know which version to send their users to. See wikipedia for more information. Default is nothing, in which case no canonical link is set.

assets can be used to include additional assets (JS, CSS, ICO etc. files). See below for more information.

analytics can be used specify the Google Analytics tracking ID.

collapselevel controls the navigation level visible in the sidebar. Defaults to 2. To show fewer levels by default, set collapselevel = 1.

sidebar_sitename determines whether the site name is shown in the sidebar or not. Setting it to false can be useful when the logo already contains the name of the package. Defaults to true.

highlights can be used to add highlighting for additional languages. By default, Documenter already highlights all the "Common" highlight.js languages and Julia (julia, julia-repl). Additional languages must be specified by their filenames as they appear on CDNJS for the highlight.js version Documenter is using. E.g. to include highlighting for YAML and LLVM IR, you would set highlights = ["llvm", "yaml"]. Note that no verification is done whether the provided language names are sane.

mathengine specifies which LaTeX rendering engine will be used to render the math blocks. The options are either KaTeX (default), MathJax v2, or MathJax v3, enabled by passing an instance of KaTeX, MathJax2, or MathJax3 objects, respectively. The rendering engine can further be customized by passing options to the KaTeX or MathJax2/MathJax3 constructors.

description is the site-wide description that displays in page previews and search engines. Defaults to "Documentation for $sitename", wheresitenameis defined as an argument to [makedocs`](@ref).

footer can be a valid single-line markdown String or nothing and is displayed below the page navigation. Defaults to "Powered by [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl) and the [Julia Programming Language](https://julialang.org/).".

ansicolor can be used to globally disable colored output from @repl and @example blocks by setting it to false (default: true).

lang specifies the lang attribute of the top-level <html> element, declaring the language of the generated pages. The default value is "en".

warn_outdated inserts a warning if the current page is not the newest version of the documentation.

size_threshold sets the maximum allowed HTML file size (in bytes) that Documenter is allowed to generate for a page. If the generated HTML file is larged than this, Documenter will throw an error and the build will fail. If set to nothing, the file sizes are not checked. Defaults to 200 KiB (but increases of this default value will be considered to be non-breaking).

size_threshold_warn: like size_threshold, but going over this limit will only cause Documenter to print a warning, instead of throwing an error. Defaults to 100 KiB, and must be less than or equal to size_threshold.

Purpose of HTML size thresholds

The size threshold, with a reasonable default, exists so that users would not deploy huge pages accidentally (which among other this will result in bad UX for the readers and negatively impacts SEO). It is relatively easy to have e.g. an @example produce a lot of output.

Experimental options

prerender a boolean (true or false (default)) for enabling prerendering/build time application of syntax highlighting of code blocks. Requires a node (NodeJS) executable to be available in PATH or to be passed as the node keyword.

node path to a node (NodeJS) executable used for prerendering.

highlightjs file path to custom highglight.js library to be used with prerendering.

Default and custom assets

Documenter copies all files under the source directory (e.g. /docs/src/) over to the compiled site. It also copies a set of default assets from /assets/html/ to the site's assets/ directory, unless the user already had a file with the same name, in which case the user's files overrides the Documenter's file. This could, in principle, be used for customizing the site's style and scripting.

The HTML output also links certain custom assets to the generated HTML documents, specifically a logo, a preview image, and additional javascript files. The asset files that should be linked must be placed in assets/, under the source directory (e.g /docs/src/assets) and must be on the top level (i.e. files in the subdirectories of assets/ are not linked).

For the logo, Documenter checks for the existence of assets/logo.{svg,png,webp,gif,jpg,jpeg}, in this order. The first one it finds gets displayed at the top of the navigation sidebar. It will also check for assets/logo-dark.{svg,png,webp,gif,jpg,jpeg} and use that for dark themes.

Similarly, for the preview image, Documenter checks for the existence of assets/preview.{png,webp,gif,jpg,jpeg} in order. Assuming that canonical has been set, the canonical URL for the image gets constructed, , and a set of HTML <meta> tags are generated for the image, ensuring that the image shows up in link previews. The preview image will not be shown if canonical is not set.

Additional JS, ICO, and CSS assets can be included in the generated pages by passing them as a list with the assets keyword. Each asset will be included in the <head> of every page in the order in which they are given. The type of the asset (i.e. whether it is going to be included with a <script> or a <link> tag) is determined by the file's extension – either .js, .ico[1], or .css (unless overridden with asset).

Simple strings are assumed to be local assets and that each correspond to a file relative to the documentation source directory (conventionally src/). Non-local assets, identified by their absolute URLs, can be included with the asset function.

source
Documenter.HTMLWriter.HTMLContext — Type

HTMLWriter-specific globals that are passed to domify and other recursive functions.

source
Documenter.HTMLWriter.KaTeX — Type
KaTeX(config::Dict = <default>, override = false)

An instance of the KaTeX type can be passed to HTML via the mathengine keyword to specify that the KaTeX rendering engine should be used in the HTML output to render mathematical expressions.

A dictionary can be passed via the config argument to configure KaTeX. It becomes the options argument of renderMathInElement. By default, Documenter only sets a custom delimiters option.

By default, the user-provided dictionary gets merged with the default dictionary (i.e. the resulting configuration dictionary will contain the values from both dictionaries, but e.g. setting your own delimiters value will override the default). This can be overridden by setting override to true, in which case the default values are ignored and only the user-provided dictionary is used.

source
Documenter.HTMLWriter.MathJax2 — Type
MathJax2(config::Dict = <default>, override = false)

An instance of the MathJax2 type can be passed to HTML via the mathengine keyword to specify that the MathJax v2 rendering engine should be used in the HTML output to render mathematical expressions.

A dictionary can be passed via the config argument to configure MathJax. It gets passed to the MathJax.Hub.Config function. By default, Documenter sets custom configurations for tex2jax, config, jax, extensions and Tex.

By default, the user-provided dictionary gets merged with the default dictionary (i.e. the resulting configuration dictionary will contain the values from both dictionaries, but e.g. setting your own tex2jax value will override the default). This can be overridden by setting override to true, in which case the default values are ignored and only the user-provided dictionary is used.

The URL of the MathJax JS file can be overridden using the url keyword argument (e.g. to use a particular minor version).

source
Documenter.HTMLWriter.MathJax3 — Type
MathJax3(config::Dict = <default>, override = false)

An instance of the MathJax3 type can be passed to HTML via the mathengine keyword to specify that the MathJax v3 rendering engine should be used in the HTML output to render mathematical expressions.

A dictionary can be passed via the config argument to configure MathJax. It gets passed to Window.MathJax function. By default, Documenter specifies in the key tex that $...$ and \(...\) denote inline math, that AMS style tags should be used and the base, ams and autoload packages should be imported. The key options, by default, specifies which HTML classes to ignore and which to process using MathJax.

By default, the user-provided dictionary gets merged with the default dictionary (i.e. the resulting configuration dictionary will contain the values from both dictionaries, but e.g. setting your own tex value will override the default). This can be overridden by setting override to true, in which case the default values are ignored and only the user-provided dictionary is used.

The URL of the MathJax JS file can be overridden using the url keyword argument (e.g. to use a particular minor version).

source
Documenter.HTMLWriter.MathJax — Function

deprecated – Use MathJax2 instead

source
Documenter.HTMLWriter.canonical_url — Method

If canonical for HTML is set, returns the canonical URL of a path or Documenter.NavNode, otherwise returns nothing.

source
Documenter.HTMLWriter.collect_subsections — Method

Returns an ordered list of tuples, (toplevel, anchor, text), corresponding to level 1 and 2 headings on the page. Note that if the first header on the page is a level 1 header then it is not included – it is assumed to be the page title and so does not need to be included in the navigation menu twice.

source
Documenter.HTMLWriter.copy_asset — Method

Copies an asset from Documenters assets/html/ directory to doc.user.build. Returns the path of the copied asset relative to .build.

source
Documenter.HTMLWriter.edit_link — Method

Calls f(logo, title, url) if it is possible to create an edit link for the navnode.

source
Documenter.HTMLWriter.get_url — Method

Returns the full path corresponding to a path of a .md page file. The the input and output paths are assumed to be relative to src/.

source
Documenter.HTMLWriter.get_url — Method

Returns the full path of a Documenter.NavNode relative to src/.

source
Documenter.HTMLWriter.getpage — Method

Returns a page (as a Documenter.Page object) using the HTMLContext.

source
Documenter.HTMLWriter.navhref — Method

Get the relative hyperlink between two Documenter.NavNodes. Assumes that both Documenter.NavNodes have an associated Documenter.Page (i.e. .page is not nothing).

source
Documenter.HTMLWriter.navitem — Method

navitem returns the lists and list items of the navigation menu. It gets called recursively to construct the whole tree.

It always returns a DOM.Node. If there's nothing to display (e.g. the node is set to be invisible), it returns an empty text node (DOM.Node("")).

source
Documenter.HTMLWriter.pagetitle — Method

Tries to guess the page title by looking at the <h1> headers and returns the header contents of the first <h1> on a page (or nothing if the algorithm was unable to find any <h1> headers).

source
Documenter.HTMLWriter.pretty_url — Method

If prettyurls for HTML is enabled, returns a "pretty" version of the path which can then be used in links in the resulting HTML file.

source
Documenter.HTMLWriter.relhref — Method

Calculates a relative HTML link from one path to another.

source
Documenter.HTMLWriter.render_html — Function

Renders the main <html> tag.

source
Documenter.HTMLWriter.render_page — Method

Constructs and writes the page referred to by the navnode to .build.

source
Documenter.HTMLWriter.render_settings — Method

Renders the modal settings dialog.

source
Documenter.HTMLWriter.write_html — Method

Writes the HTML DOM into the HTML file that corresponds to navnode. Prints a warning/error if the page goes over the size_threshold or size_threshold_warn limits, and in the former case also returns false, to report back to the caller that the size threshold check failed.

source
Documenter.HTMLWriter.RD — Module

Provides a namespace for remote dependencies.

source
Documenter.HTMLWriter.RD.highlightjs! — Function

Add the highlight.js dependencies and snippet to a RequireJS declaration.

source
Documenter.LaTeXWriter — Module

A module for rendering Document objects to LaTeX and PDF.

Keywords

LaTeXWriter uses the following additional keyword arguments that can be passed to makedocs: authors, sitename.

sitename is the site's title displayed in the title bar and at the top of the navigation menu. It goes into the \title LaTeX command.

authors can be used to specify the authors of. It goes into the \author LaTeX command.

source
Documenter.LaTeXWriter.LaTeX — Type
Documenter.LaTeX(; kwargs...)

Output format specifier that results in LaTeX/PDF output. Used together with makedocs, e.g.

makedocs(
+# Definition of `CustomWriter` module below...
source
Documenter.HTMLWriter — Module

A module for rendering Document objects to HTML.

Keywords

HTMLWriter uses the following additional keyword arguments that can be passed to Documenter.makedocs: authors, pages, sitename, version. The behavior of HTMLWriter can be further customized by setting the format keyword of Documenter.makedocs to a HTML, which accepts the following keyword arguments: analytics, assets, canonical, disable_git, edit_link, prettyurls, collapselevel, sidebar_sitename, highlights, mathengine and footer.

sitename is the site's title displayed in the title bar and at the top of the *navigation menu. This argument is mandatory for HTMLWriter.

pages defines the hierarchy of the navigation menu.

Experimental keywords

version specifies the version string of the current version which will be the selected option in the version selector. If this is left empty (default) the version selector will be hidden. The special value git-commit sets the value in the output to git:{commit}, where {commit} is the first few characters of the current commit hash.

HTML Plugin options

The HTML Documenter.Plugin provides additional customization options for the HTMLWriter. For more information, see the HTML documentation.

Page outline

The HTMLWriter makes use of the page outline that is determined by the headings. It is assumed that if the very first block of a page is a level 1 heading, then it is intended as the page title. This has two consequences:

  1. It is then used to automatically determine the page title in the navigation menu and in the <title> tag, unless specified in the .pages option.
  2. If the first heading is interpreted as being the page title, it is not displayed in the navigation sidebar.
source
Documenter.HTMLWriter.ASSETS — Constant

The root directory of the HTML assets.

source
Documenter.HTMLWriter.ASSETS_SASS — Constant

The directory where all the Sass/SCSS files needed for theme building are.

source
Documenter.HTMLWriter.ASSETS_THEMES — Constant

Directory for the compiled CSS files of the themes.

source
Documenter.HTMLWriter.OUTDATED_VERSION_ATTR — Constant

Data attribute for the script inserting a warning for outdated docs.

source
Documenter.HTMLWriter.THEMES — Constant

List of Documenter native themes.

source
Documenter.HTMLWriter.HTML — Type
HTML(kwargs...)

Sets the behavior of HTMLWriter.

Keyword arguments

prettyurls (default true) – allows toggling the pretty URLs feature.

By default (i.e. when prettyurls is set to true), Documenter creates a directory structure that hides the .html suffixes from the URLs (e.g. by default src/foo.md becomes src/foo/index.html, but can be accessed with via src/foo/ in the browser). This structure is preferred when publishing the generate HTML files as a website (e.g. on GitHub Pages), which is Documenter's primary use case.

If prettyurls = false, then Documenter generates src/foo.html instead, suitable for local documentation builds, as browsers do not normally resolve foo/ to foo/index.html for local files.

To have pretty URLs disabled in local builds, but still have them enabled for the automatic CI deployment builds, you can set prettyurls = get(ENV, "CI", nothing) == "true" (the specific environment variable you will need to check may depend on the CI system you are using, but this will work on Travis CI).

disable_git can be used to disable calls to git when the document is not in a Git-controlled repository. Without setting this to true, Documenter will throw an error and exit if any of the Git commands fail. The calls to Git are mainly used to gather information about the current commit hash and file paths, necessary for constructing the links to the remote repository.

edit_link can be used to specify which branch, tag or commit (when passed a String) in the remote repository the edit buttons point to. If a special Symbol value :commit is passed, the current commit will be used instead. If set to nothing, the link edit link will be hidden altogether. By default, Documenter tries to determine it automatically by looking at the origin remote, and falls back to "master" if that fails.

repolink can be used to override the URL of the Git repository link in the top navbar (if passed a String). By default, Documenter attempts to determine the link from the Git remote of the repository (e.g. specified via the remote argument of makedocs). Passing a nothing disables the repository link.

canonical specifies the canonical URL for your documentation. We recommend you set this to the base url of your stable documentation, e.g. https://documenter.juliadocs.org/stable. This allows search engines to know which version to send their users to. See wikipedia for more information. Default is nothing, in which case no canonical link is set.

assets can be used to include additional assets (JS, CSS, ICO etc. files). See below for more information.

analytics can be used specify the Google Analytics tracking ID.

collapselevel controls the navigation level visible in the sidebar. Defaults to 2. To show fewer levels by default, set collapselevel = 1.

sidebar_sitename determines whether the site name is shown in the sidebar or not. Setting it to false can be useful when the logo already contains the name of the package. Defaults to true.

highlights can be used to add highlighting for additional languages. By default, Documenter already highlights all the "Common" highlight.js languages and Julia (julia, julia-repl). Additional languages must be specified by their filenames as they appear on CDNJS for the highlight.js version Documenter is using. E.g. to include highlighting for YAML and LLVM IR, you would set highlights = ["llvm", "yaml"]. Note that no verification is done whether the provided language names are sane.

mathengine specifies which LaTeX rendering engine will be used to render the math blocks. The options are either KaTeX (default), MathJax v2, or MathJax v3, enabled by passing an instance of KaTeX, MathJax2, or MathJax3 objects, respectively. The rendering engine can further be customized by passing options to the KaTeX or MathJax2/MathJax3 constructors.

description is the site-wide description that displays in page previews and search engines. Defaults to "Documentation for $sitename", wheresitenameis defined as an argument to [makedocs`](@ref).

footer can be a valid single-line markdown String or nothing and is displayed below the page navigation. Defaults to "Powered by [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl) and the [Julia Programming Language](https://julialang.org/).".

ansicolor can be used to globally disable colored output from @repl and @example blocks by setting it to false (default: true).

lang specifies the lang attribute of the top-level <html> element, declaring the language of the generated pages. The default value is "en".

warn_outdated inserts a warning if the current page is not the newest version of the documentation.

size_threshold sets the maximum allowed HTML file size (in bytes) that Documenter is allowed to generate for a page. If the generated HTML file is larged than this, Documenter will throw an error and the build will fail. If set to nothing, the file sizes are not checked. Defaults to 200 KiB (but increases of this default value will be considered to be non-breaking).

size_threshold_warn: like size_threshold, but going over this limit will only cause Documenter to print a warning, instead of throwing an error. Defaults to 100 KiB, and must be less than or equal to size_threshold.

Purpose of HTML size thresholds

The size threshold, with a reasonable default, exists so that users would not deploy huge pages accidentally (which among other this will result in bad UX for the readers and negatively impacts SEO). It is relatively easy to have e.g. an @example produce a lot of output.

Experimental options

prerender a boolean (true or false (default)) for enabling prerendering/build time application of syntax highlighting of code blocks. Requires a node (NodeJS) executable to be available in PATH or to be passed as the node keyword.

node path to a node (NodeJS) executable used for prerendering.

highlightjs file path to custom highglight.js library to be used with prerendering.

Default and custom assets

Documenter copies all files under the source directory (e.g. /docs/src/) over to the compiled site. It also copies a set of default assets from /assets/html/ to the site's assets/ directory, unless the user already had a file with the same name, in which case the user's files overrides the Documenter's file. This could, in principle, be used for customizing the site's style and scripting.

The HTML output also links certain custom assets to the generated HTML documents, specifically a logo, a preview image, and additional javascript files. The asset files that should be linked must be placed in assets/, under the source directory (e.g /docs/src/assets) and must be on the top level (i.e. files in the subdirectories of assets/ are not linked).

For the logo, Documenter checks for the existence of assets/logo.{svg,png,webp,gif,jpg,jpeg}, in this order. The first one it finds gets displayed at the top of the navigation sidebar. It will also check for assets/logo-dark.{svg,png,webp,gif,jpg,jpeg} and use that for dark themes.

Similarly, for the preview image, Documenter checks for the existence of assets/preview.{png,webp,gif,jpg,jpeg} in order. Assuming that canonical has been set, the canonical URL for the image gets constructed, , and a set of HTML <meta> tags are generated for the image, ensuring that the image shows up in link previews. The preview image will not be shown if canonical is not set.

Additional JS, ICO, and CSS assets can be included in the generated pages by passing them as a list with the assets keyword. Each asset will be included in the <head> of every page in the order in which they are given. The type of the asset (i.e. whether it is going to be included with a <script> or a <link> tag) is determined by the file's extension – either .js, .ico[1], or .css (unless overridden with asset).

Simple strings are assumed to be local assets and that each correspond to a file relative to the documentation source directory (conventionally src/). Non-local assets, identified by their absolute URLs, can be included with the asset function.

source
Documenter.HTMLWriter.HTMLContext — Type

HTMLWriter-specific globals that are passed to domify and other recursive functions.

source
Documenter.HTMLWriter.KaTeX — Type
KaTeX(config::Dict = <default>, override = false)

An instance of the KaTeX type can be passed to HTML via the mathengine keyword to specify that the KaTeX rendering engine should be used in the HTML output to render mathematical expressions.

A dictionary can be passed via the config argument to configure KaTeX. It becomes the options argument of renderMathInElement. By default, Documenter only sets a custom delimiters option.

By default, the user-provided dictionary gets merged with the default dictionary (i.e. the resulting configuration dictionary will contain the values from both dictionaries, but e.g. setting your own delimiters value will override the default). This can be overridden by setting override to true, in which case the default values are ignored and only the user-provided dictionary is used.

source
Documenter.HTMLWriter.MathJax2 — Type
MathJax2(config::Dict = <default>, override = false)

An instance of the MathJax2 type can be passed to HTML via the mathengine keyword to specify that the MathJax v2 rendering engine should be used in the HTML output to render mathematical expressions.

A dictionary can be passed via the config argument to configure MathJax. It gets passed to the MathJax.Hub.Config function. By default, Documenter sets custom configurations for tex2jax, config, jax, extensions and Tex.

By default, the user-provided dictionary gets merged with the default dictionary (i.e. the resulting configuration dictionary will contain the values from both dictionaries, but e.g. setting your own tex2jax value will override the default). This can be overridden by setting override to true, in which case the default values are ignored and only the user-provided dictionary is used.

The URL of the MathJax JS file can be overridden using the url keyword argument (e.g. to use a particular minor version).

source
Documenter.HTMLWriter.MathJax3 — Type
MathJax3(config::Dict = <default>, override = false)

An instance of the MathJax3 type can be passed to HTML via the mathengine keyword to specify that the MathJax v3 rendering engine should be used in the HTML output to render mathematical expressions.

A dictionary can be passed via the config argument to configure MathJax. It gets passed to Window.MathJax function. By default, Documenter specifies in the key tex that $...$ and \(...\) denote inline math, that AMS style tags should be used and the base, ams and autoload packages should be imported. The key options, by default, specifies which HTML classes to ignore and which to process using MathJax.

By default, the user-provided dictionary gets merged with the default dictionary (i.e. the resulting configuration dictionary will contain the values from both dictionaries, but e.g. setting your own tex value will override the default). This can be overridden by setting override to true, in which case the default values are ignored and only the user-provided dictionary is used.

The URL of the MathJax JS file can be overridden using the url keyword argument (e.g. to use a particular minor version).

source
Documenter.HTMLWriter.MathJax — Function

deprecated – Use MathJax2 instead

source
Documenter.HTMLWriter.canonical_url — Method

If canonical for HTML is set, returns the canonical URL of a path or Documenter.NavNode, otherwise returns nothing.

source
Documenter.HTMLWriter.collect_subsections — Method

Returns an ordered list of tuples, (toplevel, anchor, text), corresponding to level 1 and 2 headings on the page. Note that if the first header on the page is a level 1 header then it is not included – it is assumed to be the page title and so does not need to be included in the navigation menu twice.

source
Documenter.HTMLWriter.copy_asset — Method

Copies an asset from Documenters assets/html/ directory to doc.user.build. Returns the path of the copied asset relative to .build.

source
Documenter.HTMLWriter.edit_link — Method

Calls f(logo, title, url) if it is possible to create an edit link for the navnode.

source
Documenter.HTMLWriter.get_url — Method

Returns the full path corresponding to a path of a .md page file. The the input and output paths are assumed to be relative to src/.

source
Documenter.HTMLWriter.get_url — Method

Returns the full path of a Documenter.NavNode relative to src/.

source
Documenter.HTMLWriter.getpage — Method

Returns a page (as a Documenter.Page object) using the HTMLContext.

source
Documenter.HTMLWriter.navhref — Method

Get the relative hyperlink between two Documenter.NavNodes. Assumes that both Documenter.NavNodes have an associated Documenter.Page (i.e. .page is not nothing).

source
Documenter.HTMLWriter.navitem — Method

navitem returns the lists and list items of the navigation menu. It gets called recursively to construct the whole tree.

It always returns a DOM.Node. If there's nothing to display (e.g. the node is set to be invisible), it returns an empty text node (DOM.Node("")).

source
Documenter.HTMLWriter.pagetitle — Method

Tries to guess the page title by looking at the <h1> headers and returns the header contents of the first <h1> on a page (or nothing if the algorithm was unable to find any <h1> headers).

source
Documenter.HTMLWriter.pretty_url — Method

If prettyurls for HTML is enabled, returns a "pretty" version of the path which can then be used in links in the resulting HTML file.

source
Documenter.HTMLWriter.relhref — Method

Calculates a relative HTML link from one path to another.

source
Documenter.HTMLWriter.render_html — Function

Renders the main <html> tag.

source
Documenter.HTMLWriter.render_page — Method

Constructs and writes the page referred to by the navnode to .build.

source
Documenter.HTMLWriter.render_settings — Method

Renders the modal settings dialog.

source
Documenter.HTMLWriter.write_html — Method

Writes the HTML DOM into the HTML file that corresponds to navnode. Prints a warning/error if the page goes over the size_threshold or size_threshold_warn limits, and in the former case also returns false, to report back to the caller that the size threshold check failed.

source
Documenter.HTMLWriter.RD — Module

Provides a namespace for remote dependencies.

source
Documenter.HTMLWriter.RD.highlightjs! — Function

Add the highlight.js dependencies and snippet to a RequireJS declaration.

source
Documenter.LaTeXWriter — Module

A module for rendering Document objects to LaTeX and PDF.

Keywords

LaTeXWriter uses the following additional keyword arguments that can be passed to makedocs: authors, sitename.

sitename is the site's title displayed in the title bar and at the top of the navigation menu. It goes into the \title LaTeX command.

authors can be used to specify the authors of. It goes into the \author LaTeX command.

source
Documenter.LaTeXWriter.LaTeX — Type
Documenter.LaTeX(; kwargs...)

Output format specifier that results in LaTeX/PDF output. Used together with makedocs, e.g.

makedocs(
     format = Documenter.LaTeX()
-)

The makedocs argument sitename will be used for the \title field in the tex document. The authors argument should also be specified and will be used for the \authors field in the tex document. Finally, a version number can be specified with the version option to LaTeX, which will be printed in the document and also appended to the output PDF file name.

Keyword arguments

platform sets the platform where the tex-file is compiled, either "native" (default), "tectonic", "docker", or "none" which doesn't compile the tex. The option tectonic requires a tectonic executable to be available in PATH or to be passed as the tectonic keyword.

version specifies the version number that gets printed on the title page of the manual. It defaults to the value in the TRAVIS_TAG environment variable (although this behaviour is considered to be deprecated), or to an empty string if TRAVIS_TAG is unset.

tectonic path to a tectonic executable used for compilation.

See Other Output Formats for more information.

source
Documenter.Plugin — Type
abstract type Plugin end

Any plugin that needs to either solicit user input or store information in a Document should create a subtype of Plugin. The subtype, T <: Documenter.Plugin, must have an empty constructor T() that initialized T with the appropriate default values.

To retrieve the values stored in T, the plugin can call Documenter.getplugin. If T was passed to makedocs, the passed type will be returned. Otherwise, a new T object will be created.

source
+)

The makedocs argument sitename will be used for the \title field in the tex document. The authors argument should also be specified and will be used for the \authors field in the tex document. Finally, a version number can be specified with the version option to LaTeX, which will be printed in the document and also appended to the output PDF file name.

Keyword arguments

platform sets the platform where the tex-file is compiled, either "native" (default), "tectonic", "docker", or "none" which doesn't compile the tex. The option tectonic requires a tectonic executable to be available in PATH or to be passed as the tectonic keyword.

version specifies the version number that gets printed on the title page of the manual. It defaults to the value in the TRAVIS_TAG environment variable (although this behaviour is considered to be deprecated), or to an empty string if TRAVIS_TAG is unset.

tectonic path to a tectonic executable used for compilation.

See Other Output Formats for more information.

source
Documenter.Plugin — Type
abstract type Plugin end

Any plugin that needs to either solicit user input or store information in a Document should create a subtype of Plugin. The subtype, T <: Documenter.Plugin, must have an empty constructor T() that initialized T with the appropriate default values.

To retrieve the values stored in T, the plugin can call Documenter.getplugin. If T was passed to makedocs, the passed type will be returned. Otherwise, a new T object will be created.

source
diff --git a/dev/lib/public/index.html b/dev/lib/public/index.html index cecc73e36a..9bd743adfa 100644 --- a/dev/lib/public/index.html +++ b/dev/lib/public/index.html @@ -3,7 +3,7 @@ function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'UA-136089579-2', {'page_path': location.pathname + location.search + location.hash}); -
GitHub

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.makedocs — Function
makedocs(
+
GitHub
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.makedocs — Function
makedocs(
     root    = "<current-directory>",
     source  = "src",
     build   = "build",
@@ -32,9 +32,9 @@
         "Advanced" => "tutorial/features.md",
     ],
     "apireference.md",
-]
The pages keyword must be a list where each element must be one of the following:
  1. A string containing the full path of a Markdown file within the source directory (i.e. relative to the docs/src/ root in standard deployments).
  2. A "Page title" => "path/to/page.md" pair, where Page title overrides the page title in the navigation menu (but not on the page itself).
  3. A "Subsection title" => [...] pair, indicating a subsection of pages with the given title in the navigation menu. The list of pages for the subsection follow the same rules as the top-level pages keyword.
See also hide, which can be used to hide certain pages in the navigation menu.
Note that, by default, regardless of what is specified in pages, Documenter will run and render all Markdown files it finds, even if they are not present in pages. The pagesonly keyword can be used to change this behaviour.
pagesonly can be set to true (default: false) to make Documenter process only the pages listed in with the pages keyword. In that case, the Markdown files not present in pages are ignored, i.e. code blocks do not run, docstrings do not get included, and the pages are not rendered in the output in any way.
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.
draft can be set to true to build a draft version of the document. In draft mode some potentially time-consuming steps are skipped (e.g. running @example blocks), which is useful when iterating on the documentation. This setting can also be configured per-page by setting Draft = true in an @meta block.
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).
By default, if the document check detect any errors, it will fail the documentation build. This behavior can be relaxed with the warnonly keyword.
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. When enabled, any detected errors will fail the build, but this can be overridden by passing :linkcheck to warnonly. 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.
warnonly can be used to control whether the makedocs build fails with an error, or simply prints a warning if it detects any issues with the document. Additionally, a Symbol or a Vector of Symbols can be passed to make Documenter warn for only those specified error classes (see also: Documenter.except). If set to true, the build should never fail due to document checks. The keyword defaults to false.
Note that setting warnonly = true in general is not recommended, since it will make it very easy to miss Documentation build issues, and will lead to the deployment of broken manuals. The only case where you may want to consider passing true is when you are automatically deploying the documentation for a package release. In that case, warnonly should be set dynamically by checking the relevant environment variables set by the CI system.
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.except — Function
Documenter.except(errors...)
Returns the list of all valid error classes that can be passed as the warnonly argument of makedocs, except for the ones specified in the errors argument. Each error class must be a Symbol and passed as a separate argument.
This can be used to enable strict error checking for only the listed error classes, while having other error types simply print a warning. E.g. to make Documenter fail the build only for footnote and linkcheck errors, one can set warnonly as
makedocs(...,
+]
The pages keyword must be a list where each element must be one of the following:
  1. A string containing the full path of a Markdown file within the source directory (i.e. relative to the docs/src/ root in standard deployments).
  2. A "Page title" => "path/to/page.md" pair, where Page title overrides the page title in the navigation menu (but not on the page itself).
  3. A "Subsection title" => [...] pair, indicating a subsection of pages with the given title in the navigation menu. The list of pages for the subsection follow the same rules as the top-level pages keyword.
See also hide, which can be used to hide certain pages in the navigation menu.
Note that, by default, regardless of what is specified in pages, Documenter will run and render all Markdown files it finds, even if they are not present in pages. The pagesonly keyword can be used to change this behaviour.
pagesonly can be set to true (default: false) to make Documenter process only the pages listed in with the pages keyword. In that case, the Markdown files not present in pages are ignored, i.e. code blocks do not run, docstrings do not get included, and the pages are not rendered in the output in any way.
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.
draft can be set to true to build a draft version of the document. In draft mode some potentially time-consuming steps are skipped (e.g. running @example blocks), which is useful when iterating on the documentation. This setting can also be configured per-page by setting Draft = true in an @meta block.
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).
By default, if the document check detect any errors, it will fail the documentation build. This behavior can be relaxed with the warnonly keyword.
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. When enabled, any detected errors will fail the build, but this can be overridden by passing :linkcheck to warnonly. 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.
warnonly can be used to control whether the makedocs build fails with an error, or simply prints a warning if it detects any issues with the document. Additionally, a Symbol or a Vector of Symbols can be passed to make Documenter warn for only those specified error classes (see also: Documenter.except). If set to true, the build should never fail due to document checks. The keyword defaults to false.
Note that setting warnonly = true in general is not recommended, since it will make it very easy to miss Documentation build issues, and will lead to the deployment of broken manuals. The only case where you may want to consider passing true is when you are automatically deploying the documentation for a package release. In that case, warnonly should be set dynamically by checking the relevant environment variables set by the CI system.
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.except — Function
Documenter.except(errors...)
Returns the list of all valid error classes that can be passed as the warnonly argument of makedocs, except for the ones specified in the errors argument. Each error class must be a Symbol and passed as a separate argument.
This can be used to enable strict error checking for only the listed error classes, while having other error types simply print a warning. E.g. to make Documenter fail the build only for footnote and linkcheck errors, one can set warnonly as
makedocs(...,
     warnonly = Documenter.except(:linkcheck, :footnote),
-)
The possible Symbol values that can be passed to the function are: :autodocs_block, :cross_references, :docs_block, :doctest, :eval_block, :example_block, :footnote, :linkcheck, :meta_block, :missing_docs, :parse_error, and :setup_block.
source
Documenter.hide — Function
hide(page)
+)
The possible Symbol values that can be passed to the function are: :autodocs_block, :cross_references, :docs_block, :doctest, :eval_block, :example_block, :footnote, :linkcheck, :meta_block, :missing_docs, :parse_error, and :setup_block.
source
Documenter.hide — Function
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 = [
@@ -42,7 +42,7 @@
         hide("page1.md"),
         hide("Title" => "page2.md")
     ]
-)
source
hide(root, children)
+)
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 = [
@@ -53,7 +53,7 @@
         ]),
         hide("hidden_index.md", [...])
     ]
-)
source
Documenter.HTMLWriter.asset — Function
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 = [
+)
source
Documenter.HTMLWriter.asset — Function
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)
@@ -62,7 +62,7 @@
     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.deploydocs — Function
deploydocs(
     root = "<current-directory>",
     target = "build",
     dirname = "",
@@ -85,7 +85,7 @@
 )
 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.
Note
The index.html will be created at the branch root if and only if one of the following two conditions hold:
  1. No such file already exists.
  2. The file exists and starts with the HTML comment
    html  <!--This file is automatically generated by Documenter.jl-->
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".
dirname is a subdirectory of branch that the docs should be added to. By default, it is "", which will add the docs to the root directory.
devbranch is the branch that "tracks" the in-development version of the generated documentation. By default Documenter tries to figure this out using git. Can be set explicitly as a string (typically "master" or "main").
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. On GitHub Actions, GITHUB_TOKEN must be present for previews to work, even if DOCUMENTER_KEY ise being used to deploy.
deps can be set to a function or a callable object and gets called during deployment, and is usually used to install additional dependencies. By default, nothing gets executed.
make can be set to a function or a callable object and gets called during deployment, and is usually used to specify additional build steps. By default, nothing gets executed.
tag_prefix can be set to allow prefixed version numbers to determine the version number of a release. If tag_prefix = "" (the default), only version tags will trigger deployment; with a non-empty tag_prefix, only version tags with that prefix will trigger deployment. See manual sections on Documentation Versions and Deploying from a monorepo for more details.
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, as well as the tag_prefix (if present). 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.doctest — Function
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.DocMeta — Module
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.getdocmeta — Function
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 it gets rewritten.
source
DocumenterTools
DocumenterTools.generate — Function
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
+)
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.
Note
The index.html will be created at the branch root if and only if one of the following two conditions hold:
  1. No such file already exists.
  2. The file exists and starts with the HTML comment
    html  <!--This file is automatically generated by Documenter.jl-->
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".
dirname is a subdirectory of branch that the docs should be added to. By default, it is "", which will add the docs to the root directory.
devbranch is the branch that "tracks" the in-development version of the generated documentation. By default Documenter tries to figure this out using git. Can be set explicitly as a string (typically "master" or "main").
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. On GitHub Actions, GITHUB_TOKEN must be present for previews to work, even if DOCUMENTER_KEY ise being used to deploy.
deps can be set to a function or a callable object and gets called during deployment, and is usually used to install additional dependencies. By default, nothing gets executed.
make can be set to a function or a callable object and gets called during deployment, and is usually used to specify additional build steps. By default, nothing gets executed.
tag_prefix can be set to allow prefixed version numbers to determine the version number of a release. If tag_prefix = "" (the default), only version tags will trigger deployment; with a non-empty tag_prefix, only version tags with that prefix will trigger deployment. See manual sections on Documentation Versions and Deploying from a monorepo for more details.
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, as well as the tag_prefix (if present). 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.doctest — Function
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.DocMeta — Module
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.getdocmeta — Function
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 it gets rewritten.
source
DocumenterTools
DocumenterTools.generate — Function
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
@@ -127,4 +127,4 @@
 
 [ 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==
source
DocumenterTools.OutdatedWarning.generate — Function
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.
source

+LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBNnpiRkdXQVZpYlIy...QkVBRWFjY3BxaW9uNjFLaVdOcDU5T2YrUkdmCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==
source
DocumenterTools.OutdatedWarning.generate — Function
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.

source
diff --git a/dev/lib/remote-links/index.html b/dev/lib/remote-links/index.html index 16399a8db3..b6b46f6ff4 100644 --- a/dev/lib/remote-links/index.html +++ b/dev/lib/remote-links/index.html @@ -3,7 +3,7 @@ function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'UA-136089579-2', {'page_path': location.pathname + location.search + location.hash}); -
GitHub

Remote repository links

Documenter, if set up appropriately, can automatically generate links to publicly hosted Git repositories (such as source and edit links to e.g. repositories hosted on GitHub). Usually this is for linking back to the main package repository or the project source code.

The Remotes API is used to specify remote repositories and generate the URLs. It is also designed to be extended, to support additional Git repository hosting services.

There are two categories of remote repositories that (may) need to be configured for Documenter to be able to determine remote URLs:

  1. Project repository remote, specified with the repo keyword to makedocs. This refers to the project as a whole (rather than specific files), and is used for the repository landing page link, issue references etc.

  2. File link remotes, specified by the remotes keyword to makedocs. These are used to link a file system file to the corresponding file in the remote repository. In particular, these are used to generate the edit links for manual pages, and Julia source file links for docstrings.

For the most common case – a repository of a simple Julia package – there is usually only one remote repository that one links to, and the distinction between file links and repository links is not relevant. However, in more complex setups it may be necessary to distinguish between the two cases. The defaults to the two keywords try to cater for the most common use case, and as is explained below, this means that there has to be some interaction between these two arguments.

Remotes for files

When Documenter has to determine the URL of a file in the hosted repository, it gets a local filesystem absolute path as an input.[1] In the case of Markdown files, those local paths are determined by makedocs when it reads them. The links to Julia files are determined from the docsystem, and point to where the code was loaded from (e.g. for a development dependency of the environment, they come from the Pkg.developed path; but for normal Pkg.add dependencies the source files are usually in ~/.julia/packages).

In most cases, for both Markdown and Julia files, the files Documenter is concerned about are located in the currently checked out Git repository that contains the Documenter make.jl script (e.g. the locally checked out package repository). However, sometimes they may also be in a different repository (either in a subdirectory of or outside of the primary repository), or even in a non-Git directory outside of the primary repository (e.g. if you're trying to build the documentation of a release tarball).

To handle those cases, the remotes keyword to makedocs can be used to set up a local directory => remote repository mapping for local file system paths. The local directory is assumed to correspond to the root of the Git repository, and any subpath within that directory is then resolved to the corresponding path in the remote repository. If there are nested remotes configured, Documenter will use the one that matches first as it walks up the directory tree from the original path.

As the common case is a locally checked out Git repository cloned from GitHub, Documenter will also try to determine such remotes automatically. This is done regardless whether any additional remotes have been specified with remotes or not.

  • When Documenter walks up the directory tree, it checks whether the directory is a root of a Git repository (by looking for the presence of a .git directory or file). Once it finds a valid local repository root, it tries to read its origin remote URL.
    • If that matches a GitHub repository[2], Documenter automatically sets up a mapping from that directory, and then uses that to determine the remote URLs.
    • If Documenter is unable to determine the remote from the repository's origin (e.g. origin is not set up, or it is hosted somewhere else), it will error, as it will not be able to determine the remote URLs. In this case, the remote should be configured explicitly with remotes.

You can think of it as Documenter automatically populating remotes with any cloned GitHub repositories it finds.[3]

Note

The Remotes API can be used to implement the methods to compute the remote URLs (for now, Documenter only supports GitHub natively).

repo & remotes interaction

Since Documenter is primarily used to generate documentation for Julia packages, there is some interaction between the repo and remotes keyword arguments, to automagically determine their defaults. This means that usually it is not necessary to specify either explicitly in the make.jl script.

The rules are as follows:

  • If repo is not specified, it is essentially determined like any other remote link, by trying to figure out the repository that contains the root path argument of makedocs (defaulting to the directory of the make.jl script; usually the docs/ directory). The Remote object will one of the remotes, which in turn may have been determined automatically via the origin URL of the containing Git repository.

  • If repo is specified, but the remotes for the repository root is not, repo will function as a remotes entry for the repository root. This is so that it would not be necessary to specify the same argument twice (i.e. once for general repository links, once for file links).

  • If both repo and a remotes for the repository root are configured, Documenter will throw an error, as it does not really make sense for them to point to two different remotes.[4]

Remotes API

Documenter.Remotes.GitHub — Type
GitHub(user :: AbstractString, repo :: AbstractString)
+
GitHub
Remote repository links
Documenter, if set up appropriately, can automatically generate links to publicly hosted Git repositories (such as source and edit links to e.g. repositories hosted on GitHub). Usually this is for linking back to the main package repository or the project source code.
The Remotes API is used to specify remote repositories and generate the URLs. It is also designed to be extended, to support additional Git repository hosting services.
There are two categories of remote repositories that (may) need to be configured for Documenter to be able to determine remote URLs:
  1. Project repository remote, specified with the repo keyword to makedocs. This refers to the project as a whole (rather than specific files), and is used for the repository landing page link, issue references etc.
  2. File link remotes, specified by the remotes keyword to makedocs. These are used to link a file system file to the corresponding file in the remote repository. In particular, these are used to generate the edit links for manual pages, and Julia source file links for docstrings.
For the most common case – a repository of a simple Julia package – there is usually only one remote repository that one links to, and the distinction between file links and repository links is not relevant. However, in more complex setups it may be necessary to distinguish between the two cases. The defaults to the two keywords try to cater for the most common use case, and as is explained below, this means that there has to be some interaction between these two arguments.
Remotes for files
When Documenter has to determine the URL of a file in the hosted repository, it gets a local filesystem absolute path as an input.[1] In the case of Markdown files, those local paths are determined by makedocs when it reads them. The links to Julia files are determined from the docsystem, and point to where the code was loaded from (e.g. for a development dependency of the environment, they come from the Pkg.developed path; but for normal Pkg.add dependencies the source files are usually in ~/.julia/packages).
In most cases, for both Markdown and Julia files, the files Documenter is concerned about are located in the currently checked out Git repository that contains the Documenter make.jl script (e.g. the locally checked out package repository). However, sometimes they may also be in a different repository (either in a subdirectory of or outside of the primary repository), or even in a non-Git directory outside of the primary repository (e.g. if you're trying to build the documentation of a release tarball).
To handle those cases, the remotes keyword to makedocs can be used to set up a local directory => remote repository mapping for local file system paths. The local directory is assumed to correspond to the root of the Git repository, and any subpath within that directory is then resolved to the corresponding path in the remote repository. If there are nested remotes configured, Documenter will use the one that matches first as it walks up the directory tree from the original path.
As the common case is a locally checked out Git repository cloned from GitHub, Documenter will also try to determine such remotes automatically. This is done regardless whether any additional remotes have been specified with remotes or not.
  • When Documenter walks up the directory tree, it checks whether the directory is a root of a Git repository (by looking for the presence of a .git directory or file). Once it finds a valid local repository root, it tries to read its origin remote URL.
    • If that matches a GitHub repository[2], Documenter automatically sets up a mapping from that directory, and then uses that to determine the remote URLs.
    • If Documenter is unable to determine the remote from the repository's origin (e.g. origin is not set up, or it is hosted somewhere else), it will error, as it will not be able to determine the remote URLs. In this case, the remote should be configured explicitly with remotes.
You can think of it as Documenter automatically populating remotes with any cloned GitHub repositories it finds.[3]
Note
The Remotes API can be used to implement the methods to compute the remote URLs (for now, Documenter only supports GitHub natively).
repo & remotes interaction
Since Documenter is primarily used to generate documentation for Julia packages, there is some interaction between the repo and remotes keyword arguments, to automagically determine their defaults. This means that usually it is not necessary to specify either explicitly in the make.jl script.
The rules are as follows:
  • If repo is not specified, it is essentially determined like any other remote link, by trying to figure out the repository that contains the root path argument of makedocs (defaulting to the directory of the make.jl script; usually the docs/ directory). The Remote object will one of the remotes, which in turn may have been determined automatically via the origin URL of the containing Git repository.
  • If repo is specified, but the remotes for the repository root is not, repo will function as a remotes entry for the repository root. This is so that it would not be necessary to specify the same argument twice (i.e. once for general repository links, once for file links).
  • If both repo and a remotes for the repository root are configured, Documenter will throw an error, as it does not really make sense for them to point to two different remotes.[4]
Remotes API
Documenter.Remotes.GitHub — Type
GitHub(user :: AbstractString, repo :: AbstractString)
 GitHub(remote :: AbstractString)
Represents a remote Git repository hosted on GitHub. The repository is identified by the names of the user (or organization) and the repository: GitHub(user, repository). E.g.:
makedocs(
     repo = GitHub("JuliaDocs", "Documenter.jl")
-)
The single-argument constructor assumes that the user and repository parts are separated by a slash (e.g. JuliaDocs/Documenter.jl).
source
The following types and functions and relevant when creating custom Remote types:
Documenter.Remotes.Remote — Type
abstract type Remote
Abstract supertype for implementing additional remote repositories that Documenter can use when generating links to files hosted on Git hosting service (such as GitHub, GitLab etc). For custom or less common Git hosting services, the user can create their own Remote subtype and pass that as the repo argument to makedocs.
When implementing a new type T <: Remote, the following functions must be extended for that type:
Additionally, it may also extend the following functions:
source
Documenter.Remotes.repourl — Function
Remotes.repourl(remote::T) -> String
An internal Documenter function that must be extended when implementing a user-defined Remote. It should return a string pointing to the landing page of the remote repository. E.g. for GitHub it returns "https://github.com/USER/REPO/".
source
Documenter.Remotes.fileurl — Function
Remotes.fileurl(remote::T, ref, filename, linerange) -> String
An internal Documenter function that must be extended when implementing a user-defined Remote. Should return the full remote URL to the source file filename, optionally including the line numbers.
  • ref is string containing the Git reference, such as a commit SHA, branch name or a tag name.
  • filename is a string containing the full path of the file in the repository without any leading / characters.
  • linerange either specifies a range of integers or is nothing. In the former case it either specifies a line number (if first(linerange) == last(linerange)) or a range of lines (first(linerange) < last(linerange)). The line information should be accessed only with the first and last functions (no other interface guarantees are made).
    If linerange is nothing, the line numbers should be omitted and the returned URL should refer to the full file.
    It is also acceptable for an implementation to completely ignore the value of the linerange argument, e.g. when the remote repository does not support direct links to particular line numbers.
E.g. for GitHub, depending on the input arguments, it would return the following strings:
reffilenamelinerangereturned string
"master""foo/bar.jl"nothing"https://github.com/USER/REPO/blob/master/foo/bar.jl"
"v1.2.3""foo/bar.jl"12:12"https://github.com/USER/REPO/blob/v1.2.3/foo/bar.jl#L12"
"xyz/foo""README.md"10:15"https://github.com/USER/REPO/blob/xyz/foo/README.md#L10-L15"
source
Documenter.Remotes.issueurl — Function
Remotes.issueurl(remote::T, issuenumber)
An internal Documenter function that can be extended when implementing a user-defined Remote. It should return a string with the full URL to an issue referenced by issuenumber, or nothing if it is not possible to determine such a URL.
  • issuenumber is a string containing the issue number.
It is not mandatory to define this method for a custom Remote. In this case it just falls back to always returning nothing.
E.g. for GitHub when issuenumber = "123", it would return "https://github.com/USER/REPO/issues/123".
source
  • 1There is an exception to this: links to Julia Base module source files.   But Documenter already known how to handle those correctly, and they are really only relevant to the Julia main manual build.
  • 2GitHub is the most common case, but this could be extended to cover other Git hosting services in the future (as long as the remote can reliably determined from the origin URL).
  • 3One thing to be aware here is that Documenter builds up a cache of the Git repositories it finds on every makedocs call.   This is for performance reasons, to reduce the number of file system accesses and, in particular, git calls, which are relatively slow.
  • 4If there is a use case for this, this limitation could be relaxed in the future.

+)

The single-argument constructor assumes that the user and repository parts are separated by a slash (e.g. JuliaDocs/Documenter.jl).

source

The following types and functions and relevant when creating custom Remote types:

Documenter.Remotes.Remote — Type
abstract type Remote

Abstract supertype for implementing additional remote repositories that Documenter can use when generating links to files hosted on Git hosting service (such as GitHub, GitLab etc). For custom or less common Git hosting services, the user can create their own Remote subtype and pass that as the repo argument to makedocs.

When implementing a new type T <: Remote, the following functions must be extended for that type:

Additionally, it may also extend the following functions:

source
Documenter.Remotes.repourl — Function
Remotes.repourl(remote::T) -> String

An internal Documenter function that must be extended when implementing a user-defined Remote. It should return a string pointing to the landing page of the remote repository. E.g. for GitHub it returns "https://github.com/USER/REPO/".

source
Documenter.Remotes.fileurl — Function
Remotes.fileurl(remote::T, ref, filename, linerange) -> String

An internal Documenter function that must be extended when implementing a user-defined Remote. Should return the full remote URL to the source file filename, optionally including the line numbers.

  • ref is string containing the Git reference, such as a commit SHA, branch name or a tag name.

  • filename is a string containing the full path of the file in the repository without any leading / characters.

  • linerange either specifies a range of integers or is nothing. In the former case it either specifies a line number (if first(linerange) == last(linerange)) or a range of lines (first(linerange) < last(linerange)). The line information should be accessed only with the first and last functions (no other interface guarantees are made).

    If linerange is nothing, the line numbers should be omitted and the returned URL should refer to the full file.

    It is also acceptable for an implementation to completely ignore the value of the linerange argument, e.g. when the remote repository does not support direct links to particular line numbers.

E.g. for GitHub, depending on the input arguments, it would return the following strings:

reffilenamelinerangereturned string
"master""foo/bar.jl"nothing"https://github.com/USER/REPO/blob/master/foo/bar.jl"
"v1.2.3""foo/bar.jl"12:12"https://github.com/USER/REPO/blob/v1.2.3/foo/bar.jl#L12"
"xyz/foo""README.md"10:15"https://github.com/USER/REPO/blob/xyz/foo/README.md#L10-L15"
source
Documenter.Remotes.issueurl — Function
Remotes.issueurl(remote::T, issuenumber)

An internal Documenter function that can be extended when implementing a user-defined Remote. It should return a string with the full URL to an issue referenced by issuenumber, or nothing if it is not possible to determine such a URL.

  • issuenumber is a string containing the issue number.

It is not mandatory to define this method for a custom Remote. In this case it just falls back to always returning nothing.

E.g. for GitHub when issuenumber = "123", it would return "https://github.com/USER/REPO/issues/123".

source
  • 1There is an exception to this: links to Julia Base module source files. But Documenter already known how to handle those correctly, and they are really only relevant to the Julia main manual build.
  • 2GitHub is the most common case, but this could be extended to cover other Git hosting services in the future (as long as the remote can reliably determined from the origin URL).
  • 3One thing to be aware here is that Documenter builds up a cache of the Git repositories it finds on every makedocs call. This is for performance reasons, to reduce the number of file system accesses and, in particular, git calls, which are relatively slow.
  • 4If there is a use case for this, this limitation could be relaxed in the future.
diff --git a/dev/man/doctests/index.html b/dev/man/doctests/index.html index 494d2ef6af..317be0967d 100644 --- a/dev/man/doctests/index.html +++ b/dev/man/doctests/index.html @@ -110,4 +110,4 @@ doctest(MyPackage; manual = false) ... # other tests & testsets end

Note that you still need to make sure that all the necessary Module-level metadata for the doctests is set up before doctest is called. Also, you need to add Documenter and all the other packages you are loading in the doctests as test dependencies.

Fixing Outdated Doctests

To fix outdated doctests, the doctest function can be called with fix = true. This will run the doctests, and overwrite the old results with the new output. This can be done just in the REPL:

julia> using Documenter, MyPackage
-julia> doctest(MyPackage, fix=true)

Alternatively, you can also pass the doctest = :fix keyword to makedocs.

Note

Skipping Doctests

Doctesting can be disabled by setting the makedocs keyword doctest = false. This should only be done when initially laying out the structure of a package's documentation, after which it's encouraged to always run doctests when building docs.

+julia> doctest(MyPackage, fix=true)

Alternatively, you can also pass the doctest = :fix keyword to makedocs.

Note

Skipping Doctests

Doctesting can be disabled by setting the makedocs keyword doctest = false. This should only be done when initially laying out the structure of a package's documentation, after which it's encouraged to always run doctests when building docs.

diff --git a/dev/man/examples/index.html b/dev/man/examples/index.html index 14627d329a..0b0e5f6def 100644 --- a/dev/man/examples/index.html +++ b/dev/man/examples/index.html @@ -3,4 +3,4 @@ function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'UA-136089579-2', {'page_path': location.pathname + location.search + location.hash}); -
GitHub

Examples

Sometimes the best way to learn how to use a new package is to look for examples of what others have already built with it.

The following packages use Documenter to build their documentation and so should give a good overview of what this package is currently able to do.

Note

Packages are listed alphabetically. If you have a package that uses Documenter then please open a PR that adds it to the appropriate list below; a simple way to do so is to navigate to https://github.com/JuliaDocs/Documenter.jl/edit/master/docs/src/man/examples.md.

The make.jl file for all listed packages will be tested to check for potential regressions prior to tagging new Documenter releases whenever possible.

Registered

Packages that have tagged versions available in the general Registry:

Documentation repositories

Some projects or organizations maintain dedicated documentation repositories that are separate from specific packages.

+
GitHub

Examples

Sometimes the best way to learn how to use a new package is to look for examples of what others have already built with it.

The following packages use Documenter to build their documentation and so should give a good overview of what this package is currently able to do.

Note

Packages are listed alphabetically. If you have a package that uses Documenter then please open a PR that adds it to the appropriate list below; a simple way to do so is to navigate to https://github.com/JuliaDocs/Documenter.jl/edit/master/docs/src/man/examples.md.

The make.jl file for all listed packages will be tested to check for potential regressions prior to tagging new Documenter releases whenever possible.

Registered

Packages that have tagged versions available in the general Registry:

Documentation repositories

Some projects or organizations maintain dedicated documentation repositories that are separate from specific packages.

diff --git a/dev/man/guide/index.html b/dev/man/guide/index.html index 7bf4d7da97..ae8e4ea796 100644 --- a/dev/man/guide/index.html +++ b/dev/man/guide/index.html @@ -108,4 +108,4 @@ ... ] ] -)

Using the pages argument you can organize your pages into subsections and hide some pages from the sidebar with the help of the hide functions.

Adding a logo or icon

You can easily add a logo or icon to your documentation which will be automatically displayed in the navigation sidebar.

During the build process, Documenter looks for suitable graphic images in the src/assets/ directory and automatically copies them to /build/assets/.

You can use SVG, PNG, WEBP, GIF, or JPEG images.

Documenter looks for files logo.svg, logo.png, logo.webp, logo.gif, logo.jpg, or logo.jpeg, in that order. The first suitable image found is used.

This image will be used for both light and dark themes. If you want to create a separate design for the dark theme, add a file called logo-dark.svg (or PNG/WEBP/GIF/JPEG).

Files don't need to be square. Images with transparent backgrounds can look better, particularly for dark themes.

There's a sidebar_sitename keyword option for Documenter.HTML that lets you hide the sitename that's usually displayed below a logo. This is useful if the logo already contains the name.

+)

Using the pages argument you can organize your pages into subsections and hide some pages from the sidebar with the help of the hide functions.

Adding a logo or icon

You can easily add a logo or icon to your documentation which will be automatically displayed in the navigation sidebar.

During the build process, Documenter looks for suitable graphic images in the src/assets/ directory and automatically copies them to /build/assets/.

You can use SVG, PNG, WEBP, GIF, or JPEG images.

Documenter looks for files logo.svg, logo.png, logo.webp, logo.gif, logo.jpg, or logo.jpeg, in that order. The first suitable image found is used.

This image will be used for both light and dark themes. If you want to create a separate design for the dark theme, add a file called logo-dark.svg (or PNG/WEBP/GIF/JPEG).

Files don't need to be square. Images with transparent backgrounds can look better, particularly for dark themes.

There's a sidebar_sitename keyword option for Documenter.HTML that lets you hide the sitename that's usually displayed below a logo. This is useful if the logo already contains the name.

diff --git a/dev/man/hosting/index.html b/dev/man/hosting/index.html index f63b8e5bbb..17b1924f89 100644 --- a/dev/man/hosting/index.html +++ b/dev/man/hosting/index.html @@ -170,8 +170,8 @@ https://USER_NAME.github.io/PACKAGE_NAME.jl/PackageB/vX.Y.Z https://USER_NAME.github.io/PACKAGE_NAME.jl/PackageB/dev -https://USER_NAME.github.io/PACKAGE_NAME.jl/PackageB/stable # Links to most recent PackageB version

While they won't automatically reference one another, such referencing can be added manually (e.g. by linking to https://USERNAME.github.io/PACKAGENAME.jl/PackageA/stable from the docs built for PackageB).

Warning

When building multiple subpackages in the same repo, unique dirnames must be specified in each package's deploydocs; otherwise, only the most recently built package for a given version over the entire monorepo will be present at https://USERNAME.github.io/PACKAGENAME.jl/PackageB/vX.Y.Z, and the rest of the subpackages' documentation will be unavailable.

Final Remarks

That should be all that is needed to enable automatic documentation building. Pushing new commits to your master branch should trigger doc builds. Note that other branches do not trigger these builds and neither do pull requests by potential contributors.

If you would like to see a more complete example of how this process is setup then take a look at this package's repository for some inspiration.

Deployment systems

It is possible to customize Documenter to use other systems then the ones described in the sections above. This is done by passing a configuration (a DeployConfig) to deploydocs by the deploy_config keyword argument. Documenter supports Travis, GitHubActions, GitLab, and Buildkite natively, but it is easy to define your own by following the simple interface described below.

Documenter.DeployConfig — Type
DeployConfig

Abstract type which new deployment configs should be subtypes of.

source
Documenter.deploy_folder — Function
Documenter.deploy_folder(cfg::DeployConfig; repo, devbranch, push_preview, devurl, 
-                         tag_prefix, kwargs...)

Return a DeployDecision. This function is called with the repo, devbranch, push_preview, tag_prefix, and devurl arguments from deploydocs.

Note

Implementations of this functions should accept trailing kwargs... for compatibility with future Documenter releases which may pass additional keyword arguments.

source
Documenter.DeployDecision — Type
DeployDecision(; kwargs...)

Struct containing information about the decision to deploy or not deploy.

Arguments

  • all_ok::Bool - Should documentation be deployed?
  • branch::String - The branch to which documentation should be pushed
  • is_preview::Bool - Is this documentation build a pull request?
  • repo::String - The repo to which documentation should be pushed
  • subfolder::String - The subfolder to which documentation should be pushed
source
Documenter.authentication_method — Function
Documenter.authentication_method(::DeployConfig)

Return enum instance SSH or HTTPS depending on push method to be used.

Configs returning SSH should support Documenter.documenter_key. Configs returning HTTPS should support Documenter.authenticated_repo_url.

source
Documenter.authenticated_repo_url — Function
Documenter.authenticated_repo_url(cfg::DeployConfig)

Return an authenticated URL to the upstream repository.

This method must be supported by configs that push with HTTPS, see Documenter.authentication_method.

source
Documenter.documenter_key — Function
Documenter.documenter_key(cfg::DeployConfig)

Return the Base64-encoded SSH private key for the repository. Defaults to reading the DOCUMENTER_KEY environment variable.

This method must be supported by configs that push with SSH, see Documenter.authentication_method.

source
Documenter.documenter_key_previews — Function
Documenter.documenter_key_previews(cfg::DeployConfig)

Return the Base64-encoded SSH private key for the repository. Uses the DOCUMENTER_KEY_PREVIEWS environment variable if it is defined, otherwise uses the DOCUMENTER_KEY environment variable.

This method must be supported by configs that push with SSH, see Documenter.authentication_method.

source
Documenter.Travis — Type
Travis <: DeployConfig

Default implementation of DeployConfig.

The following environment variables influences the build when using the Travis configuration:

  • DOCUMENTER_KEY: must contain the Base64-encoded SSH private key for the repository. This variable should be set in the Travis settings for the repository. Make sure this variable is marked NOT to be displayed in the build log.

  • TRAVIS_PULL_REQUEST: must be set to false. This avoids deployment on pull request builds.

  • TRAVIS_REPO_SLUG: must match the value of the repo keyword to deploydocs.

  • TRAVIS_EVENT_TYPE: may not be set to cron. This avoids re-deployment of existing docs on builds that were triggered by a Travis cron job.

  • TRAVIS_BRANCH: unless TRAVIS_TAG is non-empty, this must have the same value as the devbranch keyword to deploydocs. This makes sure that only the development branch (commonly, the master branch) will deploy the "dev" documentation (deployed into a directory specified by the devurl keyword to deploydocs).

  • TRAVIS_TAG: if set, a tagged version deployment is performed instead; the value must be a valid version number (i.e. match Base.VERSION_REGEX). The documentation for a package version tag gets deployed to a directory named after the version number in TRAVIS_TAG instead.

The TRAVIS_* variables are set automatically on Travis. More information on how Travis sets the TRAVIS_* variables can be found in the Travis documentation.

source
Documenter.GitHubActions — Type
GitHubActions <: DeployConfig

Implementation of DeployConfig for deploying from GitHub Actions.

The following environment variables influences the build when using the GitHubActions configuration:

  • GITHUB_EVENT_NAME: must be set to push, workflow_dispatch, or schedule. This avoids deployment on pull request builds.

  • GITHUB_REPOSITORY: must match the value of the repo keyword to deploydocs.

  • GITHUB_REF: must match the devbranch keyword to deploydocs, alternatively correspond to a git tag.

  • GITHUB_TOKEN or DOCUMENTER_KEY: used for authentication with GitHub, see the manual section for GitHub Actions for more information.

The GITHUB_* variables are set automatically on GitHub Actions, see the documentation.

source
Documenter.GitLab — Type
GitLab <: DeployConfig

GitLab implementation of DeployConfig.

The following environment variables influence the build when using the GitLab configuration:

  • DOCUMENTER_KEY: must contain the Base64-encoded SSH private key for the repository. This variable should be set in the GitLab settings. Make sure this variable is marked NOT to be displayed in the build log.

  • CI_COMMIT_BRANCH: the name of the commit branch.

  • CI_EXTERNAL_PULL_REQUEST_IID: Pull Request ID from GitHub if the pipelines are for external pull requests.

  • CI_PROJECT_PATH_SLUG: The namespace with project name. All letters lowercased and non-alphanumeric characters replaced with -.

  • CI_COMMIT_TAG: The commit tag name. Present only when building tags.

  • CI_PIPELINE_SOURCE: Indicates how the pipeline was triggered.

The CI_* variables are set automatically on GitLab. More information on how GitLab sets the CI_* variables can be found in the GitLab documentation.

source
Documenter.Buildkite — Type
Buildkite <: DeployConfig

Buildkite implementation of DeployConfig.

The following environment variables influence the build when using the Buildkite configuration:

  • DOCUMENTER_KEY: must contain the Base64-encoded SSH private key for the repository. This variable should be somehow set in the CI environment, e.g., provisioned by an agent environment plugin.

  • BUILDKITE_BRANCH: the name of the commit branch.

  • BUILDKITE_PULL_REQUEST: Pull Request ID from GitHub if the pipelines are for external pull requests.

  • BUILDKITE_TAG: The commit tag name. Present only when building tags.

The BUILDKITE_* variables are set automatically on GitLab. More information on how Buildkite sets the BUILDKITE_* variables can be found in the Buildkite documentation.

source
Documenter.Woodpecker — Type
Woodpecker <: DeployConfig

Implementation of DeployConfig for deploying from Woodpecker CI.

The following environmental variables are built-in from the Woodpecker pipeline influences how Documenter works:

  • CI_REPO: must match the full name of the repository <owner>/<name> e.g. JuliaDocs/Documenter.jl
  • CI_REPO_LINK: must match the full link to the project repo
  • CI_BUILD_EVENT: must be set to push, tag, pull_request, and deployment
  • CI_COMMIT_REF: must match the devbranch keyword to deploydocs, alternatively correspond to a git tag.
  • CI_COMMIT_TAG: must match to a tag.
  • CI_COMMIT_PULL_REQUEST: must return the PR number.
  • CI_REPO_OWNER: must return the value of the repo owner. Real names are not necessary.

The following user-defined environmental variables influences how Documenter works:

  • PROJECT_ACCESS_TOKEN: user generated access token from a forge e.g. GitHub, GitLab, Codeberg to be used as a secret.
  • FORGE_URL: user-defined env var to be used for authentication. Optional.

User can define the FORGE_URL variable and add it to their Woodpecker pipeline definition:

Example .woodpecker.yml

pipeline:
+https://USER_NAME.github.io/PACKAGE_NAME.jl/PackageB/stable  # Links to most recent PackageB version

While they won't automatically reference one another, such referencing can be added manually (e.g. by linking to https://USERNAME.github.io/PACKAGENAME.jl/PackageA/stable from the docs built for PackageB).

Warning

When building multiple subpackages in the same repo, unique dirnames must be specified in each package's deploydocs; otherwise, only the most recently built package for a given version over the entire monorepo will be present at https://USERNAME.github.io/PACKAGENAME.jl/PackageB/vX.Y.Z, and the rest of the subpackages' documentation will be unavailable.

Final Remarks

That should be all that is needed to enable automatic documentation building. Pushing new commits to your master branch should trigger doc builds. Note that other branches do not trigger these builds and neither do pull requests by potential contributors.

If you would like to see a more complete example of how this process is setup then take a look at this package's repository for some inspiration.

Deployment systems

It is possible to customize Documenter to use other systems then the ones described in the sections above. This is done by passing a configuration (a DeployConfig) to deploydocs by the deploy_config keyword argument. Documenter supports Travis, GitHubActions, GitLab, and Buildkite natively, but it is easy to define your own by following the simple interface described below.

Documenter.deploy_folder — Function
Documenter.deploy_folder(cfg::DeployConfig; repo, devbranch, push_preview, devurl, 
+                         tag_prefix, kwargs...)

Return a DeployDecision. This function is called with the repo, devbranch, push_preview, tag_prefix, and devurl arguments from deploydocs.

Note

Implementations of this functions should accept trailing kwargs... for compatibility with future Documenter releases which may pass additional keyword arguments.

source
Documenter.DeployDecision — Type
DeployDecision(; kwargs...)

Struct containing information about the decision to deploy or not deploy.

Arguments

  • all_ok::Bool - Should documentation be deployed?
  • branch::String - The branch to which documentation should be pushed
  • is_preview::Bool - Is this documentation build a pull request?
  • repo::String - The repo to which documentation should be pushed
  • subfolder::String - The subfolder to which documentation should be pushed
source
Documenter.documenter_key_previews — Function
Documenter.documenter_key_previews(cfg::DeployConfig)

Return the Base64-encoded SSH private key for the repository. Uses the DOCUMENTER_KEY_PREVIEWS environment variable if it is defined, otherwise uses the DOCUMENTER_KEY environment variable.

This method must be supported by configs that push with SSH, see Documenter.authentication_method.

source
Documenter.Travis — Type
Travis <: DeployConfig

Default implementation of DeployConfig.

The following environment variables influences the build when using the Travis configuration:

  • DOCUMENTER_KEY: must contain the Base64-encoded SSH private key for the repository. This variable should be set in the Travis settings for the repository. Make sure this variable is marked NOT to be displayed in the build log.

  • TRAVIS_PULL_REQUEST: must be set to false. This avoids deployment on pull request builds.

  • TRAVIS_REPO_SLUG: must match the value of the repo keyword to deploydocs.

  • TRAVIS_EVENT_TYPE: may not be set to cron. This avoids re-deployment of existing docs on builds that were triggered by a Travis cron job.

  • TRAVIS_BRANCH: unless TRAVIS_TAG is non-empty, this must have the same value as the devbranch keyword to deploydocs. This makes sure that only the development branch (commonly, the master branch) will deploy the "dev" documentation (deployed into a directory specified by the devurl keyword to deploydocs).

  • TRAVIS_TAG: if set, a tagged version deployment is performed instead; the value must be a valid version number (i.e. match Base.VERSION_REGEX). The documentation for a package version tag gets deployed to a directory named after the version number in TRAVIS_TAG instead.

The TRAVIS_* variables are set automatically on Travis. More information on how Travis sets the TRAVIS_* variables can be found in the Travis documentation.

source
Documenter.GitHubActions — Type
GitHubActions <: DeployConfig

Implementation of DeployConfig for deploying from GitHub Actions.

The following environment variables influences the build when using the GitHubActions configuration:

  • GITHUB_EVENT_NAME: must be set to push, workflow_dispatch, or schedule. This avoids deployment on pull request builds.

  • GITHUB_REPOSITORY: must match the value of the repo keyword to deploydocs.

  • GITHUB_REF: must match the devbranch keyword to deploydocs, alternatively correspond to a git tag.

  • GITHUB_TOKEN or DOCUMENTER_KEY: used for authentication with GitHub, see the manual section for GitHub Actions for more information.

The GITHUB_* variables are set automatically on GitHub Actions, see the documentation.

source
Documenter.GitLab — Type
GitLab <: DeployConfig

GitLab implementation of DeployConfig.

The following environment variables influence the build when using the GitLab configuration:

  • DOCUMENTER_KEY: must contain the Base64-encoded SSH private key for the repository. This variable should be set in the GitLab settings. Make sure this variable is marked NOT to be displayed in the build log.

  • CI_COMMIT_BRANCH: the name of the commit branch.

  • CI_EXTERNAL_PULL_REQUEST_IID: Pull Request ID from GitHub if the pipelines are for external pull requests.

  • CI_PROJECT_PATH_SLUG: The namespace with project name. All letters lowercased and non-alphanumeric characters replaced with -.

  • CI_COMMIT_TAG: The commit tag name. Present only when building tags.

  • CI_PIPELINE_SOURCE: Indicates how the pipeline was triggered.

The CI_* variables are set automatically on GitLab. More information on how GitLab sets the CI_* variables can be found in the GitLab documentation.

source
Documenter.Buildkite — Type
Buildkite <: DeployConfig

Buildkite implementation of DeployConfig.

The following environment variables influence the build when using the Buildkite configuration:

  • DOCUMENTER_KEY: must contain the Base64-encoded SSH private key for the repository. This variable should be somehow set in the CI environment, e.g., provisioned by an agent environment plugin.

  • BUILDKITE_BRANCH: the name of the commit branch.

  • BUILDKITE_PULL_REQUEST: Pull Request ID from GitHub if the pipelines are for external pull requests.

  • BUILDKITE_TAG: The commit tag name. Present only when building tags.

The BUILDKITE_* variables are set automatically on GitLab. More information on how Buildkite sets the BUILDKITE_* variables can be found in the Buildkite documentation.

source
Documenter.Woodpecker — Type
Woodpecker <: DeployConfig

Implementation of DeployConfig for deploying from Woodpecker CI.

The following environmental variables are built-in from the Woodpecker pipeline influences how Documenter works:

  • CI_REPO: must match the full name of the repository <owner>/<name> e.g. JuliaDocs/Documenter.jl
  • CI_REPO_LINK: must match the full link to the project repo
  • CI_BUILD_EVENT: must be set to push, tag, pull_request, and deployment
  • CI_COMMIT_REF: must match the devbranch keyword to deploydocs, alternatively correspond to a git tag.
  • CI_COMMIT_TAG: must match to a tag.
  • CI_COMMIT_PULL_REQUEST: must return the PR number.
  • CI_REPO_OWNER: must return the value of the repo owner. Real names are not necessary.

The following user-defined environmental variables influences how Documenter works:

  • PROJECT_ACCESS_TOKEN: user generated access token from a forge e.g. GitHub, GitLab, Codeberg to be used as a secret.
  • FORGE_URL: user-defined env var to be used for authentication. Optional.

User can define the FORGE_URL variable and add it to their Woodpecker pipeline definition:

Example .woodpecker.yml

pipeline:
    docs:
    image: julia
    environment:
@@ -181,4 +181,4 @@
    image: julia
    commands:
      - export FORGE_URL=github.com
-   ...

More about pipeline syntax is documented here: https://woodpecker-ci.org/docs/usage/pipeline-syntax

Lastly, another environment-variable used for authentication is the PROJECT_ACCESS_TOKEN which is an access token you defined by the forge you use e.g. GitHub, GitLab, Codeberg, and other gitea instances. Check their documentation on how to create an access token. This access token should be then added as a secret as documented in https://woodpecker-ci.org/docs/usage/secrets.

source
+ ...

More about pipeline syntax is documented here: https://woodpecker-ci.org/docs/usage/pipeline-syntax

Lastly, another environment-variable used for authentication is the PROJECT_ACCESS_TOKEN which is an access token you defined by the forge you use e.g. GitHub, GitLab, Codeberg, and other gitea instances. Check their documentation on how to create an access token. This access token should be then added as a secret as documented in https://woodpecker-ci.org/docs/usage/secrets.

source diff --git a/dev/man/hosting/walkthrough/index.html b/dev/man/hosting/walkthrough/index.html index b8a1e36585..124643b9d7 100644 --- a/dev/man/hosting/walkthrough/index.html +++ b/dev/man/hosting/walkthrough/index.html @@ -11,4 +11,4 @@ julia> read("path/to/private/key", String) |> base64encode |> println

If you are in a unix and unix-like system, you can just use openssl command with tr (for truncate) to generate your base64-encoded-key.

$ openssl enc -base64 -in path/to/your/private/key -out path/to/your/base/64/encoded/key
 $ # We need to truncate the newlines
-$ cat path/to/your/base/64/encoded/key | tr -d "\n"

Copy the resulting output.

Go to https://travis-ci.com/[YOUR_USER_NAME]/[YOUR_REPO_NAME]/settings. Scroll down to the "Environment Variables" section. It should look like this:

Now, add a new environment variable called DOCUMENTER_KEY, and set its value to the output from the Julia command above (make sure to remove the surrounding quotes).

Finally, make sure that the "Display value in build log" is left switched off and then click "Add". Congratulations! You've added the private key to Travis.

Security warning

To reiterate: make sure that the "Display value in build log" option is OFF for the variable, so that it does not get printed when the tests run. This base64-encoded string contains the unencrypted private key that gives full write access to your repository, so it must be kept safe. Also, make sure that you never expose this variable in your tests, nor merge any code that does. You can read more about Travis environment variables in Travis User Documentation.

Final Remarks

You should now be able to continue on with the Hosting Documentation.

+$ cat path/to/your/base/64/encoded/key | tr -d "\n"

Copy the resulting output.

Go to https://travis-ci.com/[YOUR_USER_NAME]/[YOUR_REPO_NAME]/settings. Scroll down to the "Environment Variables" section. It should look like this:

Now, add a new environment variable called DOCUMENTER_KEY, and set its value to the output from the Julia command above (make sure to remove the surrounding quotes).

Finally, make sure that the "Display value in build log" is left switched off and then click "Add". Congratulations! You've added the private key to Travis.

Security warning

To reiterate: make sure that the "Display value in build log" option is OFF for the variable, so that it does not get printed when the tests run. This base64-encoded string contains the unencrypted private key that gives full write access to your repository, so it must be kept safe. Also, make sure that you never expose this variable in your tests, nor merge any code that does. You can read more about Travis environment variables in Travis User Documentation.

Final Remarks

You should now be able to continue on with the Hosting Documentation.

diff --git a/dev/man/latex/index.html b/dev/man/latex/index.html index 8a3fccee1e..d840763560 100644 --- a/dev/man/latex/index.html +++ b/dev/man/latex/index.html @@ -81,4 +81,4 @@ "tags" => "ams", "packages" => ["base", "ams", "autoload", "physics"], ), -))

MathJax2, MathJax3 and KaTeX are available types for mathengine.

+))

MathJax2, MathJax3 and KaTeX are available types for mathengine.

diff --git a/dev/man/other-formats/index.html b/dev/man/other-formats/index.html index ee6d25c1a1..802e21b5fa 100644 --- a/dev/man/other-formats/index.html +++ b/dev/man/other-formats/index.html @@ -24,4 +24,4 @@ makedocs( format = LaTeX(platform = "none"), ... -)

Custom LaTeX style

The PDF/LaTeX backend works by generating a TeX file based on the input Markdown files. For users who need or want more control over the generated PDF, it is possible to customize the setup part of the generated TeX code.

Load custom packages

By default, the generated TeX file loads the documenter.sty style file, which loads several packages (such as fontspec, amsmath, listings, minted, tabulary, graphicx) and otherwise configures the TeX build.

Users can load additional packages and declare additional configuration by adding a custom.sty file to the assets/ source directory. The custom style file will be loaded right after the default style (documenter.sty).

Custom preamble

By default, Documenter uses the preamble.tex preamble, with only the dynamically generated declarations for the \DocMainTitle, \DocVersion, \DocAuthors, and \JuliaVersion variables preceding it.

For more control, it is possible to fully replace the preamble by adding a preamble.tex file into the assets/ source directory, which will then be used instead of the default one. The Documenter tests contain two examples of how a custom preamble can be used:

Markdown & MkDocs

Documenter no longer provides the Markdown/MkDocs output, and this functionality has moved to the DocumenterMarkdown package.

+)

Custom LaTeX style

The PDF/LaTeX backend works by generating a TeX file based on the input Markdown files. For users who need or want more control over the generated PDF, it is possible to customize the setup part of the generated TeX code.

Load custom packages

By default, the generated TeX file loads the documenter.sty style file, which loads several packages (such as fontspec, amsmath, listings, minted, tabulary, graphicx) and otherwise configures the TeX build.

Users can load additional packages and declare additional configuration by adding a custom.sty file to the assets/ source directory. The custom style file will be loaded right after the default style (documenter.sty).

Custom preamble

By default, Documenter uses the preamble.tex preamble, with only the dynamically generated declarations for the \DocMainTitle, \DocVersion, \DocAuthors, and \JuliaVersion variables preceding it.

For more control, it is possible to fully replace the preamble by adding a preamble.tex file into the assets/ source directory, which will then be used instead of the default one. The Documenter tests contain two examples of how a custom preamble can be used:

Markdown & MkDocs

Documenter no longer provides the Markdown/MkDocs output, and this functionality has moved to the DocumenterMarkdown package.

diff --git a/dev/man/syntax/index.html b/dev/man/syntax/index.html index 87d797b1a9..dba5b752b5 100644 --- a/dev/man/syntax/index.html +++ b/dev/man/syntax/index.html @@ -229,4 +229,4 @@ ```

It will show up as follows, with code having been copied over verbatim to the HTML file.

(SVG) - + diff --git a/dev/release-notes/index.html b/dev/release-notes/index.html index 30755b3b23..a34286492d 100644 --- a/dev/release-notes/index.html +++ b/dev/release-notes/index.html @@ -37,4 +37,4 @@ ... )

Note: It is technically possible to specify the same argument twice with different values by passing both variants. In that case the value to the deprecated `html*` variant takes precedence._

Added

Version v0.20.0 - 2018-10-27

Version changes

Breaking

Deprecated

Added

Fixed

+make = () -> run(`mkdocs build`)

  • Explicitly import DocumenterMarkdown in make.jl. See the MarkdownWriter deprecation below.

    • If you already specify any of the changed keywords, then you do not need to make any changes to those keywords you already set.

    However, if you are setting any of the values to the new defaults (e.g. when you are already using the HTML output), you may now rely on the new defaults.

  • "Pretty URLs" are enabled by default now for the HTML output. The default value of the html_prettyurls has been changed to true.

    For a page foo/page.md Documenter now generates foo/page/index.html, instead of foo/page.html. On GitHub pages deployments it means that your URLs look like foo/page/ instead of foo/page.html.

    For local builds you should explicitly set html_prettyurls = false.

    For upgrading: If you wish to retain the old behavior, set html_prettyurls = false in makedocs. If you already set html_prettyurls, you do not need to change anything.

  • The Travis.genkeys and Documenter.generate functions have been moved to a separate DocumenterTools.jl package. (#789)

    • Deprecated

    Added

    Fixed

    diff --git a/dev/search/index.html b/dev/search/index.html index 999f558d00..2c71a58817 100644 --- a/dev/search/index.html +++ b/dev/search/index.html @@ -3,4 +3,4 @@ function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'UA-136089579-2', {'page_path': location.pathname + location.search + location.hash}); -
    GitHub

    Loading search...

      +
      GitHub

      Loading search...

        diff --git a/dev/showcase/index.html b/dev/showcase/index.html index 84fba64742..58b6272fbf 100644 --- a/dev/showcase/index.html +++ b/dev/showcase/index.html @@ -9,9 +9,9 @@ end

        Mathematics

        For mathematics, both inline and display equations are available. Inline equations should be written as LaTeX between two backticks, e.g. ``A x^2 + B x + C = 0``. It will render as $A x^2 + B x + C = 0$.

        The LaTeX for display equations must be wrapped in a ```math code block and will render like

        \[x_{1,2} = \frac{-B \pm \sqrt{B^2 - 4 A C}}{2A}\]

        By default, the HTML output renders equations with KaTeX, but MathJax can optionally be used as well.

        Warning

        Similar to LaTeX, using $ and $$ to escape inline and display equations also works. However, doing so is deprecated and this functionality may be removed in a future release.

        Images

        Include images using basic Markdown syntax:

        Enter a descriptive caption for the image

        The path should be relative to the directory of the current file. Alternatively, use ./ to begin a path relative to the src of the documents, e.g., ./assets/logo.png.

        Admonitions

        Admonitions are colorful boxes used to highlight parts of the documentation.

        Each admonition begins with three !!!, and then the content is indented underneath with four spaces:

        !!! note "An optional title"
     Here is something you should pay attention to.

        Documenter supports a range of admonition types for different circumstances.

        Note admonition
        'note' admonition

        Admonitions look like this. This is a !!! note-type admonition.

        Note that admonitions themselves can contain other block-level elements too, such as code blocks. E.g.

        f(x) = x^2

        However, you can not have at-blocks, docstrings, doctests etc. in an admonition.

        Headings are OK though:

        Heading 1

        Heading 2

        Heading 3

        Heading 4

        Heading 5
        Heading 6
        Info admonition
        'info' admonition

        This is a !!! info-type admonition. This is the same as a !!! note-type.

        Tip admonition
        'tip' admonition

        This is a !!! tip-type admonition.

        Warning admonition
        'warning' admonition

        This is a !!! warning-type admonition.

        Danger admonition
        'danger' admonition

        This is a !!! danger-type admonition.

        Compat admonition
        'compat' admonition

        This is a !!! compat-type admonition.

        Details admonition

        Admonitions with type details is rendered as a collapsed <details> block in the HTML output, with the admonition title as the <summary>.

        'details' admonition

        This is a !!! details-type admonition.

        Unknown admonition class
        Unknown admonition class

        Admonition with an unknown admonition class. This is a code example.

        Lists

        Tight lists look as follows

        If the lists contain paragraphs or other block level elements, they look like this:

        Numbered lists are also supported

        1. Lorem ipsum dolor sit amet, consectetur adipiscing elit.
        2. Nulla quis venenatis justo.
        3. In non sodales eros.

        As are nested lists

        Lists can also be included in other blocks that can contain block level items

        Bulleted lists in admonitions
        Large lists in admonitions

        Tables

        objectimplementedvalue
        A✓10.00
        BB✓1000000.00

        With explicit alignment.

        objectimplementedvalue
        A✓10.00
        BB✓1000000.00

        Tables that are too wide should become scrollable.

        objectimplementedvalue
        A✓10.00
        BBBBBBBBBBBBBBBBBBBB✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓1000000000000000000000000000000000000000000000000000000.00

        Footnotes

        Footnote references can be added with the [^label] syntax.[1] The footnote definitions get collected at the bottom of the page.

        The footnote label can be an arbitrary string and even consist of block-level elements.[Clarke61]

        Headings

        Finally, headings render as follows

        Heading level 3

        Heading level 4

        Heading level 5
        Heading level 6

        To see an example of a level 1 heading see the page title and for level 2 heading, see the one just under this paragraph.

        Headings in sidebars

        Level 1 and 2 heading show up in the sidebar, for the current page.

        Docstrings

        The key feature of Documenter, of course, is the ability to automatically include docstrings from your package in the manual. The following example docstrings come from the demo DocumenterShowcase module, the source of which can be found in docs/DocumenterShowcase.jl.

        To include a docstrings into a manual page, you needs to use an @docs block

        ```@docs
 DocumenterShowcase
-```

        This will include a single docstring and it will look like this

        DocumenterShowcase — Module

        This is the DocumenterShowcase, which contains

        Documenter 0.24

        This showcase page is included in Documenter version 0.24.0 and above.

        Contents

        Docstrings can contain admonitions and other block-level nodes.

        Info

        This admonition is in a docstring. It itself can contain block levels nodes such as code blocks:

        println("Hello World")

        ... or block quotes:

        Lorem ipsum.

        In fact, while not recommended, you can actually have a matryoshka of admonitions:

        Danger
        Warning
        Tip
        Note

        Stack overflow.

        source

        You can include the docstrings corresponding to different function signatures one by one. E.g., the DocumenterShowcase.foo function has two signatures – (::Integer) and (::AbstractString).

        ```@docs
+```

        This will include a single docstring and it will look like this

        DocumenterShowcase — Module

        This is the DocumenterShowcase, which contains

        Documenter 0.24

        This showcase page is included in Documenter version 0.24.0 and above.

        Contents

        Docstrings can contain admonitions and other block-level nodes.

        Info

        This admonition is in a docstring. It itself can contain block levels nodes such as code blocks:

        println("Hello World")

        ... or block quotes:

        Lorem ipsum.

        In fact, while not recommended, you can actually have a matryoshka of admonitions:

        Danger
        Warning
        Tip
        Note

        Stack overflow.

        source

        You can include the docstrings corresponding to different function signatures one by one. E.g., the DocumenterShowcase.foo function has two signatures – (::Integer) and (::AbstractString).

        ```@docs
 DocumenterShowcase.foo(::Integer)
-```

        yielding the following docstring

        Main.DocumenterShowcase.foo — Method
        foo(::Integer)

        Docstring for foo(::Integer).

        source

        And now, by having DocumenterShowcase.foo(::AbstractString) in the @docs block will give the other docstring

        Main.DocumenterShowcase.foo — Method
        foo(::AbstractString)

        Docstring for foo(::AbstractString).

        source

        However, if you want, you can also combine multiple docstrings into a single docstring block. The DocumenterShowcase.bar function has the same signatures as

        If we just put DocumenterShowcase.bar in an @docs block, it will combine the docstrings as follows:

        Main.DocumenterShowcase.bar — Function
        bar(::Integer)

        Docstring for bar(::Integer).

        source
        bar(::AbstractString)

        Docstring for bar(::AbstractString).

        source

        If you have very many docstrings, you may also want to consider using the @autodocs block which can include a whole set of docstrings automatically based on certain filtering options

        An index of docstrings

        The @index block can be used to generate a list of all the docstrings on a page (or even across pages) and will look as follows

        Multiple uses of the same symbol

        Sometimes a symbol has multiple docstrings, for example a type definition, inner and outer constructors. The example below shows how to use specific ones in the documentation.

        Main.DocumenterShowcase.Foo — Type

        The type definition.

        source
        Main.DocumenterShowcase.Foo — Method

        Constructor Foo() with no arguments.

        source
        Main.DocumenterShowcase.Foo — Method

        Constructor Foo{T}() with one parametric argument.

        source

        Doctesting example

        Often you want to write code example such as this:

        julia> f(x) = x^2
+```

        yielding the following docstring

        Main.DocumenterShowcase.foo — Method
        foo(::Integer)

        Docstring for foo(::Integer).

        source

        And now, by having DocumenterShowcase.foo(::AbstractString) in the @docs block will give the other docstring

        Main.DocumenterShowcase.foo — Method
        foo(::AbstractString)

        Docstring for foo(::AbstractString).

        source

        However, if you want, you can also combine multiple docstrings into a single docstring block. The DocumenterShowcase.bar function has the same signatures as

        If we just put DocumenterShowcase.bar in an @docs block, it will combine the docstrings as follows:

        Main.DocumenterShowcase.bar — Function
        bar(::Integer)

        Docstring for bar(::Integer).

        source
        bar(::AbstractString)

        Docstring for bar(::AbstractString).

        source

        If you have very many docstrings, you may also want to consider using the @autodocs block which can include a whole set of docstrings automatically based on certain filtering options

        An index of docstrings

        The @index block can be used to generate a list of all the docstrings on a page (or even across pages) and will look as follows

        Multiple uses of the same symbol

        Sometimes a symbol has multiple docstrings, for example a type definition, inner and outer constructors. The example below shows how to use specific ones in the documentation.

        Main.DocumenterShowcase.Foo — Type

        The type definition.

        source
        Main.DocumenterShowcase.Foo — Method

        Constructor Foo() with no arguments.

        source
        Main.DocumenterShowcase.Foo — Method

        Constructor Foo{T}() with one parametric argument.

        source

        Doctesting example

        Often you want to write code example such as this:

        julia> f(x) = x^2
 f (generic function with 1 method)
 
 julia> f(3)
@@ -69,4 +69,4 @@
  10
        julia> median(xs)5.5
        julia> sum(xs)55

        Doctest showcase

        Currently exists just so that there would be doctests to run in manual pages of Documenter's manual. This page does not show up in navigation.

        julia> 2 + 2
 4

        The following doctests needs doctestsetup:

        julia> Documenter.splitexpr(:(Foo.Bar.baz))
 (:(Foo.Bar), :(:baz))

        Let's also try @meta blocks:

        julia> f(2)
-4
        +4