Writers
Documenter.Writers
— Module.Provides a rendering function, render
, for writing each supported Formats.Format
to file.
Note that currently Formats.Markdown
is the only supported format.
Documenter.Writers.Writer
— Type.A parametric type that allows us to use multiple dispatch to pick the appropriate writer for each output format.
The parameter f
should be an instance of the Formats.Format
enumeration.
Documenter.Writers.render
— Method.Writes a Documents.Document
object to .user.build
directory in the format specified in .user.format
.
The method should be overloaded in each writer as
render(::Writer{format}, doc)
where format
is one of the values of the Formats.Format
enumeration.
Documenter.Writers.MarkdownWriter
— Module.Provides the render
methods to write the documentation as Markdown files (MIME"text/plain"
).
Documenter.Writers.HTMLWriter
— Module.Provides the render
methods to write the documentation as HTML files (MIME"text/html"
).
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, specfically a logo 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.png
. If that's present, it gets displayed in the navigation bar.
For scripts, every assets/*.js
gets a <script>
link in the <head>
tag of every page (except if it matches one of Documenter's default scripts; the filtering is done in user_scripts
).
Note that only javascript files are linked to the generated HTML. Any related CSS must be loaded by the script. With jQuery this could be done with the following snippet
$('head').append($('<link rel="stylesheet">').attr('href', documenterBaseURL + "/assets/<file>.css"))
HTMLWriter
-specific globals that are passed to domify
and other recursive functions.
Returns a list of tuples (anchor, text)
, corresponding to all level 2 headers.
Documenter.Writers.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
.
Documenter.Writers.HTMLWriter.domify
— Method.Converts recursively a Documents.Page
, Base.Markdown
or Documenter *Node
objects into HTML DOM.
Documenter.Writers.HTMLWriter.getpage
— Method.Returns a page (as a Documents.Page
object) using the HTMLContext
.
Documenter.Writers.HTMLWriter.mdconvert
— Method.Convert a markdown object to a DOM.Node
object.
The parent
argument is passed to allow for context-dependant conversions.
Documenter.Writers.HTMLWriter.navhref
— Method.Get the relative hyperlink between two Documents.NavNode
s. Assumes that both Documents.NavNode
s have an associated Documents.Page
(i.e. .page
is not null).
Documenter.Writers.HTMLWriter.navitem
— Method.navitem
returns the lists and list items of the navigation menu. It gets called recursively to construct the whole tree.
Documenter.Writers.HTMLWriter.pagetitle
— Method.Tries to guess the page title by looking at the <h1>
headers and returns the header contents as a Nullable
(nulled if the algorithm was unable to determine the header).
Documenter.Writers.HTMLWriter.relhref
— Method.Calculates a relative HTML link from one path to another.
Constructs and writes the page referred to by the navnode
to .build
.
Creates a list of .js
files provided by the user under assets
. Returns a list of paths relative to the site root.
Documenter.Writers.LaTeXWriter
— Module.Provides the render
methods to write the documentation as LaTeX files (MIME"text/latex"
).