diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index e0995e57e4..77ddeb92d2 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.11.1","generation_timestamp":"2024-11-12T23:36:14","documenter_version":"1.8.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.11.1","generation_timestamp":"2024-11-15T09:05:04","documenter_version":"1.8.0"}} \ No newline at end of file diff --git a/dev/checklists/index.html b/dev/checklists/index.html index e51da2059f..268bb0f776 100644 --- a/dev/checklists/index.html +++ b/dev/checklists/index.html @@ -23,4 +23,4 @@ Either of those should automatically publish a new version to the Julia registry. - Once registered, the `TagBot.yml` workflow should create a tag, and rebuild the documentation for this tag. - - These steps can take quite a bit of time (1 hour or more), so don't be surprised if the new documentation takes a while to appear. + - These steps can take quite a bit of time (1 hour or more), so don't be surprised if the new documentation takes a while to appear. diff --git a/dev/contributing/index.html b/dev/contributing/index.html index 7b202caf9f..99e956d894 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

Documenter uses Runic.jl for code formatting. In addition, the following style guidelines should be followed:

  • 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;
  • 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;
  • avoid dense expressions where possible e.g. prefer nested ifs over complex nested ?s;
  • 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.

Changelog

All pull requests that make user visible changes should have a changelog entry formatted according to the Keep a Changelog style

Tests

Unit tests

As is conventional for Julia packages, unit tests are located at test/*.jl with the entrypoint test/runtests.jl.

End to end testing

Tests that build example package docs from source and inspect the results (end to end tests) are located in /test/examples. The main entry points are test/examples/make.jl for building and test/examples/test.jl for doing some basic checks on the generated outputs.

+
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

Documenter uses Runic.jl for code formatting. In addition, the following style guidelines should be followed:

  • 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;
  • 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;
  • avoid dense expressions where possible e.g. prefer nested ifs over complex nested ?s;
  • 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.

Changelog

All pull requests that make user visible changes should have a changelog entry formatted according to the Keep a Changelog style

Tests

Unit tests

As is conventional for Julia packages, unit tests are located at test/*.jl with the entrypoint test/runtests.jl.

End to end testing

Tests that build example package docs from source and inspect the results (end to end tests) are located in /test/examples. The main entry points are test/examples/make.jl for building and test/examples/test.jl for doing some basic checks on the generated outputs.

diff --git a/dev/index.html b/dev/index.html index f9d471ba80..33c7799219 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 GitHub Actions to GitHub Pages, and also supports several other CI providers.

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 GitHub Actions to GitHub Pages, and also supports several other CI providers.

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 1db2ff7312..28141540ab 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 e57360d442..6ede4199b4 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/crossref/index.html b/dev/lib/internals/crossref/index.html index cd814dcf12..95ef7af379 100644 --- a/dev/lib/internals/crossref/index.html +++ b/dev/lib/internals/crossref/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

Crossrefs

Documenter.crossref — Method
crossref(doc)
-

Traverses a Documenter.Document and process internal links and references.

  • Links containing @ref URLs are replaced with their real URLs. This delegates to xref, which in turn delegates to the XRefResolvers.XRefResolverPipeline.
  • Links to local (.md) documents are rewritten to link to the corresponding path in the output build.
  • For links to local files or images, check that the linked files exist.
source
Documenter.find_object — Method
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.xref — Method
xref(node, meta, page, doc)
-

Resolve a MarkdownAST.Link node with an @ref URL.

This delegates to XRefResolvers.XRefResolverPipeline. In addition to forwarding the node, meta, page, and doc arguments, it also passes a slug to the pipeline that any pipeline step can use to easily resolve the link target. This slug is obtained as follows:

  • For, e.g, [`Documenter.makedocs`](@ref) or [text](@ref Documenter.makedocs), the slug is "Documenter.makedocs"
  • For, e.g, [Hosting Documentation](@ref) or [text](@ref "Hosting Documentation"), the slug is sluggified version of the given section title, "Hosting-Documentation" in this case.
source
Documenter.xrefname — Method

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

source
Documenter.XRefResolvers.Docs — Type

Resolve @ref links for docstrings.

This runs unconditionally (if no previous step was able to resolve the link), and tries to find a code binding for the given slug, linking to its docstring.

source
Documenter.XRefResolvers.Header — Type

Resolve @ref links for headers.

This runs if the slug corresponds to a known local section title, and resolves the node to link to that section.

source
Documenter.XRefResolvers.XRefResolverPipeline — Type

The default pipeline for resolving @ref links.

The steps for trying to resolve links are:

Each step may or may not be able to resolve the link. Processing continues until the link is resolved or the end of the pipeline is reached. If the link is still unresolved after the last step, Documenter.xref issues an error that includes any accumulated error messages from the steps. Failure to resolve an @ref link will fail Documenter.makedocs if it is not called with warnonly=true.

The default pipeline could be extended by plugins using the general Selectors machinery.

Each pipeline step receives the following arguments:

  • node: the MarkdownAST.Node representing the link. To resolve the @ref URL, any pipeline step can modify the node.
  • slug: the "slug" for the link, see Documenter.xref
  • meta: a dictionary of metadata, see @meta block
  • page: the Documenter.Page object containing the node
  • doc: the Documenter.Document instance representing the full site
  • errors: a list of strings of error messages accumulated in the XRefResolverPipeline. If a pipeline step indicates that it might be able to resolve a @ref link (Selectors.matcher is true), but then encounters an error in Selectors.runner that prevents resolution, it should push an error message to the list of errors to explain the failure. These accumulated errors will be shown if (and only if) the entire pipeline fails to resolve the link.

The Selectors.matcher of any custom pipeline step should use Documenter.xref_unresolved to check whether the link was already resolved in an earlier pipeline step.

source
+
GitHub

Crossrefs

Documenter.crossref — Method
crossref(doc)
+

Traverses a Documenter.Document and process internal links and references.

  • Links containing @ref URLs are replaced with their real URLs. This delegates to xref, which in turn delegates to the XRefResolvers.XRefResolverPipeline.
  • Links to local (.md) documents are rewritten to link to the corresponding path in the output build.
  • For links to local files or images, check that the linked files exist.
source
Documenter.find_object — Method
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.xref — Method
xref(node, meta, page, doc)
+

Resolve a MarkdownAST.Link node with an @ref URL.

This delegates to XRefResolvers.XRefResolverPipeline. In addition to forwarding the node, meta, page, and doc arguments, it also passes a slug to the pipeline that any pipeline step can use to easily resolve the link target. This slug is obtained as follows:

  • For, e.g, [`Documenter.makedocs`](@ref) or [text](@ref Documenter.makedocs), the slug is "Documenter.makedocs"
  • For, e.g, [Hosting Documentation](@ref) or [text](@ref "Hosting Documentation"), the slug is sluggified version of the given section title, "Hosting-Documentation" in this case.
source
Documenter.xrefname — Method

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

source
Documenter.XRefResolvers.Docs — Type

Resolve @ref links for docstrings.

This runs unconditionally (if no previous step was able to resolve the link), and tries to find a code binding for the given slug, linking to its docstring.

source
Documenter.XRefResolvers.Header — Type

Resolve @ref links for headers.

This runs if the slug corresponds to a known local section title, and resolves the node to link to that section.

source
Documenter.XRefResolvers.XRefResolverPipeline — Type

The default pipeline for resolving @ref links.

The steps for trying to resolve links are:

Each step may or may not be able to resolve the link. Processing continues until the link is resolved or the end of the pipeline is reached. If the link is still unresolved after the last step, Documenter.xref issues an error that includes any accumulated error messages from the steps. Failure to resolve an @ref link will fail Documenter.makedocs if it is not called with warnonly=true.

The default pipeline could be extended by plugins using the general Selectors machinery.

Each pipeline step receives the following arguments:

  • node: the MarkdownAST.Node representing the link. To resolve the @ref URL, any pipeline step can modify the node.
  • slug: the "slug" for the link, see Documenter.xref
  • meta: a dictionary of metadata, see @meta block
  • page: the Documenter.Page object containing the node
  • doc: the Documenter.Document instance representing the full site
  • errors: a list of strings of error messages accumulated in the XRefResolverPipeline. If a pipeline step indicates that it might be able to resolve a @ref link (Selectors.matcher is true), but then encounters an error in Selectors.runner that prevents resolution, it should push an error message to the list of errors to explain the failure. These accumulated errors will be shown if (and only if) the entire pipeline fails to resolve the link.

The Selectors.matcher of any custom pipeline step should use Documenter.xref_unresolved to check whether the link was already resolved in an earlier pipeline step.

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

Deploydocs

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
Deploydocs
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="",
     cname=nothing, devurl="dev",
     deploy_config, subfolder
-)
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

+)

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
diff --git a/dev/lib/internals/docchecks/index.html b/dev/lib/internals/docchecks/index.html index e642c35bd1..19ab0614d9 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 e4a2f2e6e9..37664691c3 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 2921092de6..13ca26279c 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(object; ...)
+
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(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.getdocs — Function
getdocs(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.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.getspecificdocs — Function
getspecificdocs(binding)
+
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.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) -> Markdown.MD
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) -> Markdown.MD

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 2d27151f5d..6fe8e7ac94 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/documentertools/index.html b/dev/lib/internals/documentertools/index.html index af35c88fa9..09157926ea 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 aab3cf7c17..5b49fbaf85 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
Documenter.getplugin(doc::Document, T) -> Plugin

Retrieves the object for the Plugin sub-type T stored in doc. If an object of type T was an element of the plugins list passed to makedocs, that object will be returned. Otherwise, a new T object will be created using the default constructor T(). Subsequent calls to getplugin(doc, T) return the same object.

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(doc, 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
Documenter.getplugin(doc::Document, T) -> Plugin

Retrieves the object for the Plugin sub-type T stored in doc. If an object of type T was an element of the plugins list passed to makedocs, that object will be returned. Otherwise, a new T object will be created using the default constructor T(). Subsequent calls to getplugin(doc, T) return the same object.

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(doc, 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 cb7dcc3e76..095701266f 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 f5ab0daddc..b82587b775 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 2893bef07d..b2dc4db82d 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 79eb38b4e6..10d6bb1a7e 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 7eb46a57e3..3fb48537c6 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 73115ae315..299ed493f6 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 de041f0b87..5708d2d9f1 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.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.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.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.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/-/tree/{commit}{path}#{line}
  • Azure DevOps:
    https://dev.azure.com/org/project/_git/repo?path={path}&version={commit}{line}&lineStartColumn=1&lineEndColumn=1
  • BitBucket:
    https://bitbucket.org/user/project/src/{commit}/{path}#lines-{line}
However, an explicit Remote object is preferred over using a template string when configuring Documenter.
source
Documenter.Remotes.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.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.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/-/tree/{commit}{path}#{line}
  • Azure DevOps:
    https://dev.azure.com/org/project/_git/repo?path={path}&version={commit}{line}&lineStartColumn=1&lineEndColumn=1
  • BitBucket:
    https://bitbucket.org/user/project/src/{commit}/{path}#lines-{line}

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

source
Documenter.Remotes.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 4dfb72ea34..e9468384a0 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. It is also written into the inventory (see below). 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 object 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.

Inventory

The HTMLWriter automatically generates an objects.inv "inventory" file in the output build folder. This file contains a list of all pages, headers and docstrings in the documentation, and a relative URL that can be used to link to those items from an external source.

Other projects that build their documentation with Documenter can use the DocumenterInterLinks plugin to link to any other project with an inventory file, see External Cross-References.

The format of the objects.inv file is borrowed from the Sphinx project. It consists of a plain text header that includes the project name, taken from the sitename argument to Documenter.makedocs, and a project version taken from the inventory_version argument of the HTML options, or automatically determined by deploydocs for tagged releases. The bulk of the file is a list of plain text records, compressed with gzip. See Inventory Generation for details on these records.

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 via src/foo/ in the browser). This structure is preferred when publishing the generated HTML files as a website (e.g., on GitHub Pages), which is Documenter's primary use case. However, when building locally, viewing the resulting pages requires a running webserver. It is recommended to use the LiveServer package for this.

If prettyurls = false, then Documenter generates src/foo.html instead.

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 remotes 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", where sitename is defined as an argument to makedocs.

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.

example_size_threshold specifies the size threshold above which the @example and other block outputs get written to files, rather than being included in the HTML page. This mechanism is present to reduce the size of the generated HTML files that contain a lot of figures etc. Setting it to nothing will disable writing to files, and setting to 0 means that all examples will be written to files. Defaults to 8 KiB.

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.

size_threshold_ignore can be passed a list of pages for which the size thresholds are completely ignored (silently). The arguments should be the same file paths as for the pages argument of makedocs. Using this argument to ignore a few specific pages is preferred over setting a high general limit, or disabling the size checking altogether.

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.

inventory_version a version string to write to the header of the objects.inv inventory file. This should be a valid version number without a v prefix. Defaults to the version defined in the Project.toml file in the parent folder of the documentation root. Setting this to an empty string leaves the version in the inventory unspecified until deploydocs runs and automatically sets the version for any tagged release.

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

Returns the first limit characters of the hex SHA1 of the data bytes.

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

Calculates and converts bytes to appropriate format.

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

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

Generates a unique file for the output of an at-example block if it goes over the configured size threshold, and returns the filename (that should be in the same directory are the corresponding HTML file). If the data is under the threshold, no file is created, and the function returns nothing.

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

Generate the objects.inv inventory file.

Write the file objects.inv to the root of the HTML build folder, containing an inventory of all linkable targets in the documentation (pages, headings, and docstrings).

The objects.inv file is compatible with Sphinx See DocInventories for a description. The file can be used by Intersphinx and the DocumenterInterLinks plugin to link into the documentation from other projects.

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. It is also written into the inventory (see below). 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 object 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.

Inventory

The HTMLWriter automatically generates an objects.inv "inventory" file in the output build folder. This file contains a list of all pages, headers and docstrings in the documentation, and a relative URL that can be used to link to those items from an external source.

Other projects that build their documentation with Documenter can use the DocumenterInterLinks plugin to link to any other project with an inventory file, see External Cross-References.

The format of the objects.inv file is borrowed from the Sphinx project. It consists of a plain text header that includes the project name, taken from the sitename argument to Documenter.makedocs, and a project version taken from the inventory_version argument of the HTML options, or automatically determined by deploydocs for tagged releases. The bulk of the file is a list of plain text records, compressed with gzip. See Inventory Generation for details on these records.

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 via src/foo/ in the browser). This structure is preferred when publishing the generated HTML files as a website (e.g., on GitHub Pages), which is Documenter's primary use case. However, when building locally, viewing the resulting pages requires a running webserver. It is recommended to use the LiveServer package for this.

If prettyurls = false, then Documenter generates src/foo.html instead.

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 remotes 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", where sitename is defined as an argument to makedocs.

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.

example_size_threshold specifies the size threshold above which the @example and other block outputs get written to files, rather than being included in the HTML page. This mechanism is present to reduce the size of the generated HTML files that contain a lot of figures etc. Setting it to nothing will disable writing to files, and setting to 0 means that all examples will be written to files. Defaults to 8 KiB.

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.

size_threshold_ignore can be passed a list of pages for which the size thresholds are completely ignored (silently). The arguments should be the same file paths as for the pages argument of makedocs. Using this argument to ignore a few specific pages is preferred over setting a high general limit, or disabling the size checking altogether.

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.

inventory_version a version string to write to the header of the objects.inv inventory file. This should be a valid version number without a v prefix. Defaults to the version defined in the Project.toml file in the parent folder of the documentation root. Setting this to an empty string leaves the version in the inventory unspecified until deploydocs runs and automatically sets the version for any tagged release.

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

Returns the first limit characters of the hex SHA1 of the data bytes.

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

Calculates and converts bytes to appropriate format.

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

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

Generates a unique file for the output of an at-example block if it goes over the configured size threshold, and returns the filename (that should be in the same directory are the corresponding HTML file). If the data is under the threshold, no file is created, and the function returns nothing.

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

Generate the objects.inv inventory file.

Write the file objects.inv to the root of the HTML build folder, containing an inventory of all linkable targets in the documentation (pages, headings, and docstrings).

The objects.inv file is compatible with Sphinx See DocInventories for a description. The file can be used by Intersphinx and the DocumenterInterLinks plugin to link into the documentation from other projects.

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, i.e., T <: DocumenterPlugin.

Initialized objects of type T can be elements of the list of plugins passed as a keyword argument to makedocs.

A plugin may retrieve the existing object holding its state via the Documenter.getplugin function. Alternatively, getplugin can also instantiate T() on demand, if there is no existing object. This requires that T implements an empty constructor T().

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, i.e., T <: DocumenterPlugin.

Initialized objects of type T can be elements of the list of plugins passed as a keyword argument to makedocs.

A plugin may retrieve the existing object holding its state via the Documenter.getplugin function. Alternatively, getplugin can also instantiate T() on demand, if there is no existing object. This requires that T implements an empty constructor T().

source
diff --git a/dev/lib/public/index.html b/dev/lib/public/index.html index 10516204ee..b52da99c26 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",
@@ -33,9 +33,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 or checkdocs_ignored_modules keywords.
checkdocs_ignored_modules prevents checkdocs from checking modules supplied as a list of module objects. It will also cause all submodules of these module to be ignored. It can be useful for completely private modules including modules which have been vendored from elsewhere.
Note that checkdocs_ignored_modules does not conversely verify that these docstrings are not included in the documentation.
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.
linkcheck_useragent can be used to override the user agent string used by the HTTP and HTTPS requests made when checking for broken links. If set to nothing, it uses the default user agent string of the library/tool used to actually perform the requests (currently, the system's curl binary).
If unset, Documenter uses the following user agent string:
Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36
This is set to mimic a realistic web browser. However, the exact user agent string is subject to change. As such, it is possible that breakages can occur when Documenter's version changes, but the goal is to set the user agent such that it would be accepted by as many web servers as possible.
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.
plugins is a list of Documenter.Plugin objects. Use as directed by the documentation of a third-party plugin. For any subtype T <: Plugin, the plugins list may contain at most a single object of type T.
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 or checkdocs_ignored_modules keywords.
checkdocs_ignored_modules prevents checkdocs from checking modules supplied as a list of module objects. It will also cause all submodules of these module to be ignored. It can be useful for completely private modules including modules which have been vendored from elsewhere.
Note that checkdocs_ignored_modules does not conversely verify that these docstrings are not included in the documentation.
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.
linkcheck_useragent can be used to override the user agent string used by the HTTP and HTTPS requests made when checking for broken links. If set to nothing, it uses the default user agent string of the library/tool used to actually perform the requests (currently, the system's curl binary).
If unset, Documenter uses the following user agent string:
Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36
This is set to mimic a realistic web browser. However, the exact user agent string is subject to change. As such, it is possible that breakages can occur when Documenter's version changes, but the goal is to set the user agent such that it would be accepted by as many web servers as possible.
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.
plugins is a list of Documenter.Plugin objects. Use as directed by the documentation of a third-party plugin. For any subtype T <: Plugin, the plugins list may contain at most a single object of type T.
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_remotes, :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_remotes, :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 = [
@@ -43,7 +43,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 = [
@@ -54,7 +54,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)
@@ -63,7 +63,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 = "",
@@ -87,7 +87,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
    <!--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.
cname is the CNAME where the documentation will be hosted, which is equivalent to the GitHub Pages "Custom domain" setting in the repository settings. If set, it will be used to generate the CNAME file, which has a higher priority than the GitHub Pages settings.
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.
Note
Previews generated are NOT automatically cleaned up. This can be done manually or automated. A GitHub Actions workflow for automating the same can be found here.
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).
plugins is a list of Documenter.Plugin objects to be forwarded to makedocs. Use as directed by the documentation of a third-party plugin.
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
    <!--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.
cname is the CNAME where the documentation will be hosted, which is equivalent to the GitHub Pages "Custom domain" setting in the repository settings. If set, it will be used to generate the CNAME file, which has a higher priority than the GitHub Pages settings.
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.
Note
Previews generated are NOT automatically cleaned up. This can be done manually or automated. A GitHub Actions workflow for automating the same can be found here.
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).
plugins is a list of Documenter.Plugin objects to be forwarded to makedocs. Use as directed by the documentation of a third-party plugin.
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
@@ -129,4 +129,4 @@
 
 [ Info: add a secure 'Repository secret' named 'DOCUMENTER_KEY' to https://travis-ci.com/JuliaDocs/DocumenterTools.jl/settings (if you deploy using Travis CI) or https://github.com/JuliaDocs/DocumenterTools.jl/settings/secrets (if you deploy using GitHub Actions) with value:
 
-LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBNnpiRkdXQVZpYlIy...QkVBRWFjY3BxaW9uNjFLaVdOcDU5T2YrUkdmCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==
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 bfff6e949b..5026adecec 100644 --- a/dev/lib/remote-links/index.html +++ b/dev/lib/remote-links/index.html @@ -3,11 +3,11 @@ 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 cases are a locally checked out Git repository (added with Pkg.develop to the docs environment), or a released package which is hosted on GitHub (Pkg.added to the environment), Documenter will also try to determine such remotes automatically.

  • 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]

For released packages (those added using Pkg.add(...) rather than Pkg.develop(...)), the version and repository can be determined from the package metadata, but a commit hash is not readily available. In this case, Documenter will guess that a tag v$VERSION exists in the repository on GitHub. Note that these tags are created automatically by the widely used JuliaRegistries/TagBot action. Since this is sometimes not the case, and could cause dead or incorrect links, setting the linkcheck keyword to true to makedocs will check these guessed links have an existing target and that the existing target matches the published package. (Note this will also all other external links from your documentation.) Note that enabling this option can cause documentation builds to fail due to network errors or intermittent downtime of external services.

Note

The Remotes API can be used to implement the methods to compute the remote URLs (for now, Documenter only supports GitHub and GitLab 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 cases are a locally checked out Git repository (added with Pkg.develop to the docs environment), or a released package which is hosted on GitHub (Pkg.added to the environment), Documenter will also try to determine such remotes automatically.
  • 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]
For released packages (those added using Pkg.add(...) rather than Pkg.develop(...)), the version and repository can be determined from the package metadata, but a commit hash is not readily available. In this case, Documenter will guess that a tag v$VERSION exists in the repository on GitHub. Note that these tags are created automatically by the widely used JuliaRegistries/TagBot action. Since this is sometimes not the case, and could cause dead or incorrect links, setting the linkcheck keyword to true to makedocs will check these guessed links have an existing target and that the existing target matches the published package. (Note this will also all other external links from your documentation.) Note that enabling this option can cause documentation builds to fail due to network errors or intermittent downtime of external services.
Note
The Remotes API can be used to implement the methods to compute the remote URLs (for now, Documenter only supports GitHub and GitLab 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
Documenter.Remotes.GitLab — Type
GitLab(host, user, repo)
+)
The single-argument constructor assumes that the user and repository parts are separated by a slash (e.g. JuliaDocs/Documenter.jl).
source
Documenter.Remotes.GitLab — Type
GitLab(host, user, repo)
 GitLab(user, repo)
 GitLab(remote)
Represents a remote Git repository hosted on GitLab. The repository is identified by the host, name of the user (or organization), and the repository. For example:
makedocs(
     repo = GitLab("JuliaDocs", "Documenter.jl")
-)
The single argument constructor assumes that the end 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 end 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/lib/semver/index.html b/dev/lib/semver/index.html index e8bcdb523d..4bd1c72030 100644 --- a/dev/lib/semver/index.html +++ b/dev/lib/semver/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 & semantic versioning

Documenter, like any good Julia package, follows semantic versioning (SemVer). As such, and as the package is currently in the v1.x era of its lifecycle, any changes in Documenter should not break existing uses of the package that rely on documented behaviors.[1]

However, Documenter is relatively complex, and it can sometimes be unclear what constitutes a breaking change. For example, is changing the CSS classes in the HTML themes allowed? What if the user relied on a CSS class in an @raw html-block? If their HTML is no longer rendered correctly, is that a breaking change? Is completely changing the LaTeX compiler a breaking change? What if it breaks a PDF build somewhere due to some math block using a feature that only works with pdflatex?

This page aims to clarify what is and is not covered by the Documenter SemVer guarantees, both as information for users, and as guidance for developers.

This page is not complete!

If you need to rely on something that is currently an internal API or undocumented behavior, open an issue or a pull request to get it documented! There is a good chance that the behavior is already a de factor SemVer guarantee, or can easily be cleaned up and made public API. The goal is to add and document additional SemVer guarantees over time.

Documenter's API guarantees

The following APIs and behaviors are guaranteed not to change:

  • Standard promises about the Julia APIs (public Documenter functions and their documented arguments). In a nutshell, any make.jl making use of just public, documented parts of the Documenter API should always continue working (i.e. builds should complete). The public APIs include all exported functions and types, but is not limited to that –- see the "Reference" section of the manual for a list of public Julia APIs.

  • All documented Documenter behaviors. E.g. the way Documenter determines remote repository links is documented, or what files and with what structure get generated by the HTML builds. The behavior of undocumented edge cases may change, but only in accordance with what is documented.

Experimental APIs

Note that some APIs may explicitly marked experimental. In that case, you can only rely on them within a minor version. The next minor version release may completely change or remove experimental features and APIs.

When relying on an experimental API (either in a Documenter extension package, or in a documentation build environment), you should fix Documenter to the specific compatible minor version(s) with a "tilde specifier" in the Project.toml file.

What is not covered by SemVer

In principle, anything that is not covered by the previous section is, by definition, not part of the public API and is not guaranteed to keep working the way it is working right now.

However, it is worth mentioning a few things explicitly. In particular, this includes things that are currently not part of the API, but should be added (in some way) in the future, but probably need a careful consideration before we commit to them as public APIs.

  • Any time you hook into Documenter's internals in some way. This includes hooking into the seemingly extensible parts of the internals, such as adding additional build steps, or renderers. The long-term aim here is to create clean plugin APIs, but it is unlikely we'll be able to keep the current internals for that.

  • The HTML, TeX, or file structure of the generated documents (unless explicitly documented). This includes the CSS of the HTML themes, and as such any custom CSS overrides may stop working at any point. However, there are many de facto guarantees here that should get documented over time (e.g. for custom themes).

  • The look and feel of the HTML UI and the generated PDF may change considerably from one minor version to another.

  • Anything explicitly marked experimental is not guaranteed to remain stable (see the note above).

Patch versions are probably okay

If you are relying on some non-SemVer behaviors, features, or internals, it probably fine to expect things not to break within a patch release. In this case, you should add a [compat] entry to your Project.toml files with a tilde specifier fixing Documenter's to a specific minor version, e.g.

Documenter = "~1.X"

where X is the minor version you are developing against.

Alternatively, if this is for package documentation, and your docs/make.jl script is relying on some non-SemVer behavior, you can also check in a docs/Manifest.toml file to fully fix the Documenter version. However, it may still be a good idea to include the version bound in the docs/Project.toml file, just as documentation for maintainers.

  • 1Eventually, of course, Documenter 2.0 may break everything. But we don't expect a breaking release in the very near future.
+
GitHub

Documenter & semantic versioning

Documenter, like any good Julia package, follows semantic versioning (SemVer). As such, and as the package is currently in the v1.x era of its lifecycle, any changes in Documenter should not break existing uses of the package that rely on documented behaviors.[1]

However, Documenter is relatively complex, and it can sometimes be unclear what constitutes a breaking change. For example, is changing the CSS classes in the HTML themes allowed? What if the user relied on a CSS class in an @raw html-block? If their HTML is no longer rendered correctly, is that a breaking change? Is completely changing the LaTeX compiler a breaking change? What if it breaks a PDF build somewhere due to some math block using a feature that only works with pdflatex?

This page aims to clarify what is and is not covered by the Documenter SemVer guarantees, both as information for users, and as guidance for developers.

This page is not complete!

If you need to rely on something that is currently an internal API or undocumented behavior, open an issue or a pull request to get it documented! There is a good chance that the behavior is already a de factor SemVer guarantee, or can easily be cleaned up and made public API. The goal is to add and document additional SemVer guarantees over time.

Documenter's API guarantees

The following APIs and behaviors are guaranteed not to change:

  • Standard promises about the Julia APIs (public Documenter functions and their documented arguments). In a nutshell, any make.jl making use of just public, documented parts of the Documenter API should always continue working (i.e. builds should complete). The public APIs include all exported functions and types, but is not limited to that –- see the "Reference" section of the manual for a list of public Julia APIs.

  • All documented Documenter behaviors. E.g. the way Documenter determines remote repository links is documented, or what files and with what structure get generated by the HTML builds. The behavior of undocumented edge cases may change, but only in accordance with what is documented.

Experimental APIs

Note that some APIs may explicitly marked experimental. In that case, you can only rely on them within a minor version. The next minor version release may completely change or remove experimental features and APIs.

When relying on an experimental API (either in a Documenter extension package, or in a documentation build environment), you should fix Documenter to the specific compatible minor version(s) with a "tilde specifier" in the Project.toml file.

What is not covered by SemVer

In principle, anything that is not covered by the previous section is, by definition, not part of the public API and is not guaranteed to keep working the way it is working right now.

However, it is worth mentioning a few things explicitly. In particular, this includes things that are currently not part of the API, but should be added (in some way) in the future, but probably need a careful consideration before we commit to them as public APIs.

  • Any time you hook into Documenter's internals in some way. This includes hooking into the seemingly extensible parts of the internals, such as adding additional build steps, or renderers. The long-term aim here is to create clean plugin APIs, but it is unlikely we'll be able to keep the current internals for that.

  • The HTML, TeX, or file structure of the generated documents (unless explicitly documented). This includes the CSS of the HTML themes, and as such any custom CSS overrides may stop working at any point. However, there are many de facto guarantees here that should get documented over time (e.g. for custom themes).

  • The look and feel of the HTML UI and the generated PDF may change considerably from one minor version to another.

  • Anything explicitly marked experimental is not guaranteed to remain stable (see the note above).

Patch versions are probably okay

If you are relying on some non-SemVer behaviors, features, or internals, it probably fine to expect things not to break within a patch release. In this case, you should add a [compat] entry to your Project.toml files with a tilde specifier fixing Documenter's to a specific minor version, e.g.

Documenter = "~1.X"

where X is the minor version you are developing against.

Alternatively, if this is for package documentation, and your docs/make.jl script is relying on some non-SemVer behavior, you can also check in a docs/Manifest.toml file to fully fix the Documenter version. However, it may still be a good idea to include the version bound in the docs/Project.toml file, just as documentation for maintainers.

  • 1Eventually, of course, Documenter 2.0 may break everything. But we don't expect a breaking release in the very near future.
diff --git a/dev/man/doctests/index.html b/dev/man/doctests/index.html index aa2af5a939..3164ef0579 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 f6f2aed930..8159ad89f4 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 56bb670e82..324485e4f6 100644 --- a/dev/man/guide/index.html +++ b/dev/man/guide/index.html @@ -113,4 +113,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 cd48b82207..193bab3b21 100644 --- a/dev/man/hosting/index.html +++ b/dev/man/hosting/index.html @@ -190,8 +190,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://USER_NAME.github.io/PACKAGE_NAME.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://USER_NAME.github.io/PACKAGE_NAME.jl/PackageB/vX.Y.Z, and the rest of the subpackages' documentation will be unavailable.

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.

Woodpecker 1.0.0 and onwards

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_PIPELINE_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_FORGE_URL: env var to build the url to be used for authentication.

Woodpecker 0.15.x and pre-1.0.0

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.

Documenter Specific Environmental Variables

  • 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.

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.

Example Pipeline Syntax

1.0.0 and onwards

labels:
+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://USER_NAME.github.io/PACKAGE_NAME.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://USER_NAME.github.io/PACKAGE_NAME.jl/PackageB/vX.Y.Z, and the rest of the subpackages' documentation will be unavailable.

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.

Woodpecker 1.0.0 and onwards

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_PIPELINE_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_FORGE_URL: env var to build the url to be used for authentication.

Woodpecker 0.15.x and pre-1.0.0

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.

Documenter Specific Environmental Variables

  • 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.

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.

Example Pipeline Syntax

1.0.0 and onwards

labels:
   platform: linux/amd64
 
 steps:
@@ -216,4 +216,4 @@
       - zypper --non-interactive install openssh juliaup git
       - /usr/bin/julia --project=docs/ --startup-file=no --history-file=no -e "import Pkg; Pkg.instantiate()"
       - /usr/bin/julia --project=docs/ --startup-file=no --history-file=no -e docs/make.jl
-    secrets: [ documenter_key, project_access_token ]

More about pipeline syntax is documented here:

source
+ secrets: [ documenter_key, project_access_token ]

More about pipeline syntax is documented here:

source diff --git a/dev/man/hosting/walkthrough/index.html b/dev/man/hosting/walkthrough/index.html index fe5edaa20c..83c96e4eaf 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 28976ed6a0..9dad7f9b0f 100644 --- a/dev/man/latex/index.html +++ b/dev/man/latex/index.html @@ -98,4 +98,4 @@ ) ) ) -)

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 70a8ed5b7a..f86f8fc475 100644 --- a/dev/man/other-formats/index.html +++ b/dev/man/other-formats/index.html @@ -24,4 +24,4 @@ makedocs( format = Documenter.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 0952051231..eeec5dbb92 100644 --- a/dev/man/syntax/index.html +++ b/dev/man/syntax/index.html @@ -231,4 +231,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 de0c6d622a..09afe488d6 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/showcase/index.html b/dev/showcase/index.html index 2a8d625ba8..e1ca8bb672 100644 --- a/dev/showcase/index.html +++ b/dev/showcase/index.html @@ -7,13 +7,13 @@ ... Rendered in monospace.

    When the language is specified for the block, e.g. by starting the block with ```julia, the contents gets highlighted appropriately (for the language that are supported by the highlighter).

    function foo(x::Integer)
     @show x + 1
 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.

    TODO admonition
    'todo' admonition

    This is a !!! todo-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.

    Note that in docstrings, the headings get rewritten as just bold text right now:

    Main.DocumenterShowcase.baz — Function
    baz(x, f, k)

    Function with a more complex docstring. Headings that are part of docstrings are not rendered as headings but rather as bold text:

    Arguments

    • x::Integer: the first argument

    • f: a function with multiple allowable arguments itself

      Pattern

      • f(a::Integer)
      • f(a::Real)
      • f(a::Real, b::Real)

    • k::Integer: the third argument

    See also bar.

    source

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

    TODO admonition
    'todo' admonition

    This is a !!! todo-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.

    Note that in docstrings, the headings get rewritten as just bold text right now:

    Main.DocumenterShowcase.baz — Function
    baz(x, f, k)

    Function with a more complex docstring. Headings that are part of docstrings are not rendered as headings but rather as bold text:

    Arguments

    • x::Integer: the first argument

    • f: a function with multiple allowable arguments itself

      Pattern

      • f(a::Integer)
      • f(a::Real)
      • f(a::Real, b::Real)

    • k::Integer: the third argument

    See also bar.

    source

    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

    Both @docs and @autodocs support the canonical=false keyword argument. This can be used to include a docstring more than once

    ```@docs; canonical=false
+```

    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

    Both @docs and @autodocs support the canonical=false keyword argument. This can be used to include a docstring more than once

    ```@docs; canonical=false
 DocumenterShowcase.bar
-```

    We then see the same docstring as above

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

    Docstring for bar(::Integer).

    source
    bar(::AbstractString)

    Docstring for bar(::AbstractString).

    source

    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
+```

    We then see the same docstring as above

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

    Docstring for bar(::Integer).

    source
    bar(::AbstractString)

    Docstring for bar(::AbstractString).

    source

    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)
@@ -94,4 +94,4 @@
 ```
    julia> x42
    julia> yERROR: UndefVarError: `y` not defined in `Main.var"Main"`
 Suggestion: check for spelling errors or missing imports.

    Another @example block with the same name will, however, finish evaluating it. So a block like

    ```@example block-name
 (x, y)
-```

    will lead to

    (x, y)
    (42, 99)
    +```

    will lead to

    (x, y)
    (42, 99)