Skip to content

Instantly share code, notes, and snippets.

@visr

visr/master.json Secret

Created February 18, 2019 11:51
Show Gist options
  • Save visr/fffcfb3d62c9a5d99f86104d3ac62ac5 to your computer and use it in GitHub Desktop.
Save visr/fffcfb3d62c9a5d99f86104d3ac62ac5 to your computer and use it in GitHub Desktop.
Download ZIP
Changes in generated search index between master and search branch of Documenter.jl
Raw
master.json
[
{
"category": "constant",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.MDBlockContext",
"page": "Writers",
"text": "MDBlockContext is a union of all the Markdown nodes whose children should be blocks. It can be used to dispatch on all the block-context nodes at once.\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.MDBlockContext"
},
{
"category": "function",
"location": "lib/internals/docsystem/#Documenter.DocSystem.getdocs",
"page": "DocSystem",
"text": "getdocs(binding)\ngetdocs(binding, typesig; compare, modules, aliases)\n\n\nFind all DocStr objects that match the provided arguments:\n\nbinding: the name of the object.\ntypesig: the signature of the object. Default: Union{}.\ncompare: how to compare signatures? Exact (==) or subtypes (<:). Default: <:.\nmodules: which modules to search through. Default: all modules.\naliases: check aliases of binding when nothing is found. Default: true.\n\nReturns a Vector{DocStr} ordered by definition order in 0.5 and by type_morespecific in 0.4.\n\n\n\n\n\n",
"title": "Documenter.DocSystem.getdocs"
},
{
"category": "function",
"location": "lib/internals/docsystem/#Documenter.DocSystem.getdocs",
"page": "DocSystem",
"text": "getdocs(object)\ngetdocs(object, typesig; kws...)\n\n\nAccepts objects of any type and tries to convert them to Bindings before searching for the Binding in the docsystem.\n\nNote that when conversion fails this method returns an empty Vector{DocStr}.\n\n\n\n\n\n",
"title": "Documenter.DocSystem.getdocs"
},
{
"category": "function",
"location": "lib/internals/docsystem/#Documenter.DocSystem.multidoc",
"page": "DocSystem",
"text": "Construct a MultiDoc object from the provided argument.\n\nValid inputs are:\n\nMarkdown.MD\nDocs.FuncDoc\nDocs.TypeDoc\n\n\n\n\n\n",
"title": "Documenter.DocSystem.multidoc"
},
{
"category": "function",
"location": "lib/internals/documenter/#Documenter.git_push",
"page": "Documenter",
"text": "git_push(\n root, tmp, repo;\n branch=\"gh-pages\", dirname=\"\", target=\"site\", tag=\"\", key=\"\", sha=\"\", devurl=\"dev\"\n)\n\nHandles pushing changes to the remote documentation branch. When tag is empty the docs are deployed to the devurl directory, and when building docs for a tag they are deployed to a vX.Y.Z directory.\n\n\n\n\n\n",
"title": "Documenter.git_push"
},
{
"category": "function",
"location": "lib/internals/documenter/#Documenter.gitrm_copy",
"page": "Documenter",
"text": "gitrm_copy(src, dst)\n\nUses 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.\n\nThis 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.\n\n\n\n\n\n",
"title": "Documenter.gitrm_copy"
},
{
"category": "function",
"location": "lib/internals/documentertools/#DocumenterTools.package_devpath",
"page": "DocumenterTools",
"text": "package_devpath(pkg)\n\n\nReturns the path to the top level directory of a devved out package source tree. The package is identified by its top level module pkg.\n\n\n\n\n\n",
"title": "DocumenterTools.package_devpath"
},
{
"category": "function",
"location": "lib/internals/selectors/#Documenter.Utilities.Selectors.matcher",
"page": "Selectors",
"text": "Define the matching test for each case in a selector, i.e.\n\nSelectors.matcher(::Type{First}, x) = x == 1\nSelectors.matcher(::Type{Second}, x) = true\n\nNote that the return type must be Bool.\n\nTo match against multiple cases use the Selectors.strict function.\n\n\n\n\n\n",
"title": "Documenter.Utilities.Selectors.matcher"
},
{
"category": "function",
"location": "lib/internals/selectors/#Documenter.Utilities.Selectors.order",
"page": "Selectors",
"text": "Define the precedence of each case in a selector, i.e.\n\nSelectors.order(::Type{First}) = 1.0\nSelectors.order(::Type{Second}) = 2.0\n\nNote that the return type must be Float64. Defining multiple case types to have the same order will result in undefined behaviour.\n\n\n\n\n\n",
"title": "Documenter.Utilities.Selectors.order"
},
{
"category": "function",
"location": "lib/internals/selectors/#Documenter.Utilities.Selectors.runner",
"page": "Selectors",
"text": "Define the code that will run when a particular Selectors.matcher test returns true, i.e.\n\nSelectors.runner(::Type{First}, x) = println(\"`x` is equal to `1`.\")\nSelectors.runner(::Type{Second}, x) = println(\"`x` is not equal to `1`.\")\n\n\n\n\n\n",
"title": "Documenter.Utilities.Selectors.runner"
},
{
"category": "function",
"location": "lib/internals/utilities/#Documenter.Utilities.docs",
"page": "Utilities",
"text": "docs(ex, str)\n\nReturns an expression that, when evaluated, returns the docstrings associated with ex.\n\n\n\n\n\n",
"title": "Documenter.Utilities.docs"
},
{
"category": "function",
"location": "lib/public/#Documenter.Deps.pip",
"page": "Public",
"text": "pip(deps)\n\n\nInstalls (as non-root user) all python packages listed in deps.\n\nExamples\n\nusing Documenter\n\nmakedocs(\n # ...\n)\n\ndeploydocs(\n deps = Deps.pip(\"pygments\", \"mkdocs\", \"mkdocs-material\"),\n # ...\n)\n\n\n\n\n\n",
"title": "Documenter.Deps.pip"
},
{
"category": "function",
"location": "lib/public/#Documenter.deploydocs",
"page": "Public",
"text": "deploydocs(\n root = \"<current-directory>\",\n target = \"build\",\n repo = \"<required>\",\n branch = \"gh-pages\",\n deps = nothing | <Function>,\n make = nothing | <Function>,\n devbranch = \"master\",\n devurl = \"dev\",\n versions = [\"stable\" => \"v^\", \"v#.#\", devurl => devurl]\n)\n\nConverts markdown files generated by makedocs to HTML and pushes them to repo. This function should be called from within a package's docs/make.jl file after the call to makedocs, like so\n\nusing Documenter, PACKAGE_NAME\nmakedocs(\n # options...\n)\ndeploydocs(\n repo = \"github.com/...\"\n)\n\nWhen 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.\n\nRequired keyword arguments\n\nrepo 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:\n\nrepo = \"github.com/JuliaDocs/Documenter.jl.git\"\n\nOptional keyword arguments\n\nroot has the same purpose as the root keyword for makedocs.\n\ntarget is the directory, relative to root, where generated content that should be deployed to gh-pages is written to. written to. It should generally be the same as makedocs's build and defaults to \"build\".\n\nbranch 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\".\n\ndeps is the function used to install any additional dependencies needed to build the documentation. By default nothing is installed.\n\nIt can be used e.g. for a Markdown build. The following example installed the pygments and mkdocs Python packages using the Deps.pip function:\n\ndeps = Deps.pip(\"pygments\", \"mkdocs\")\n\nmake is the function used to specify an additonal build phase. By default, nothing gets executed.\n\ndevbranch is the branch that \"tracks\" the in-development version of the generated documentation. By default this value is set to \"master\".\n\ndevurl the folder that in-development version of the docs will be deployed. Defaults to \"dev\".\n\nforcepush 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.\n\nversions determines content and order of the resulting version selector in the generated html. The following entries are valied in the versions vector:\n\n\"v#\": includes links to the latest documentation for each major release cycle (i.e. v2.0, v1.1).\n\"v#.#\": includes links to the latest documentation for each minor release cycle (i.e. v2.0, v1.1, v1.0, v0.1).\n\"v#.#.#\": includes links to all released versions.\n\"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).\nA 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^\").\n\nEnvironment variables\n\ndeploydocs's behavior is influenced by the following environment variables, many of which are specific to the Travis CI platform.\n\nDOCUMENTER_KEY: must contain the Base64-encoded SSH private key for the repository.\nTRAVIS_PULL_REQUEST: must be set to false.\nThis avoids deployment on pull request builds. Note that there is no way to safely enable builds on pull requests, since that would expose the SSH private key (DOCUMENTER_KEY), giving anyone opening a pull request full write access to the repository.\nTRAVIS_REPO_SLUG: must match the value of the repo keyword.\nTRAVIS_EVENT_TYPE: may not be set to cron.\nThis avoids the re-deployment of existing docs on builds that were triggered by a Travis cron job.\nTRAVIS_BRANCH: unless TRAVIS_TAG is non-empty, this must have the same value as the devbranch keyword.\nThis 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).\nTRAVIS_TAG: if set, a tagged version deployment is performed instead; the value must be a valid version number (i.e. match Base.VERSION_REGEX).\nThe documentation for a package version tag gets deployed to a directory named after the version number in TRAVIS_TAG instead.\n\nThe TRAVIS_* variables are set automatically on Travis, but could be set manually to appropriate values as well to run deploydocs locally or on other CI platforms. More information on how Travis sets the TRAVIS_* variables can be found in the Travis documentation.\n\nSee Also\n\nThe 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.\n\n\n\n\n\n",
"title": "Documenter.deploydocs"
},
{
"category": "function",
"location": "lib/public/#Documenter.hide",
"page": "Public",
"text": "hide(page)\n\n\nAllows 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 overriden using the => operator as usual.\n\nUsage\n\nmakedocs(\n ...,\n pages = [\n ...,\n hide(\"page1.md\"),\n hide(\"Title\" => \"page2.md\")\n ]\n)\n\n\n\n\n\nhide(root, children)\n\n\nAllows 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).\n\nUsage\n\nmakedocs(\n ...,\n pages = [\n ...,\n hide(\"Hidden section\" => \"hidden_index.md\", [\n \"hidden1.md\",\n \"Hidden 2\" => \"hidden2.md\"\n ]),\n hide(\"hidden_index.md\", [...])\n ]\n)\n\n\n\n\n\n",
"title": "Documenter.hide"
},
{
"category": "function",
"location": "lib/public/#Documenter.makedocs",
"page": "Public",
"text": "makedocs(\n root = \"<current-directory>\",\n source = \"src\",\n build = \"build\",\n clean = true,\n doctest = true,\n modules = Module[],\n repo = \"\",\n)\n\nCombines markdown files and inline docstrings into an interlinked document. In most cases makedocs should be run from a make.jl file:\n\nusing Documenter\nmakedocs(\n # keywords...\n)\n\nwhich is then run from the command line with:\n\n$ julia make.jl\n\nThe folder structure that makedocs expects looks like:\n\ndocs/\n build/\n src/\n make.jl\n\nKeywords\n\nroot is the directory from which makedocs should run. When run from a make.jl file this keyword does not need to be set. It is, for the most part, needed when repeatedly running makedocs from the Julia REPL like so:\n\njulia> makedocs(root = joinpath(pathof(MyModule), \"..\", \"..\", \"docs\"))\n\nsource is the directory, relative to root, where the markdown source files are read from. By convention this folder is called src. Note that any non-markdown files stored in source are copied over to the build directory when makedocs is run.\n\nbuild is the directory, relative to root, into which generated files and folders are written when makedocs is run. The name of the build directory is, by convention, called build, though, like with source, users are free to change this to anything else to better suit their project needs.\n\nclean tells makedocs whether to remove all the content from the build folder prior to generating new content from source. By default this is set to true.\n\ndoctest instructs makedocs on whether to try to test Julia code blocks that are encountered in the generated document. By default this keyword is set to true. Doctesting should only ever be disabled when initially setting up a newly developed package where the developer is just trying to get their package and documentation structure correct. After that, it's encouraged to always make sure that documentation examples are runnable and produce the expected results. See the Doctests manual section for details about running doctests.\n\nmodules specifies a vector of modules that should be documented in source. If any inline docstrings from those modules are seen to be missing from the generated content then a warning will be printed during execution of makedocs. By default no modules are passed to modules and so no warnings will appear. This setting can be used as an indicator of the \"coverage\" of the generated documentation. For example Documenter's make.jl file contains:\n\nmakedocs(\n modules = [Documenter],\n # ...\n)\n\nand so any docstring from the module Documenter that is not spliced into the generated documentation in build will raise a warning.\n\nrepo specifies a template for the \"link to source\" feature. If you are using GitHub, this is automatically generated from the remote. If you are using a different host, you can use this option to tell Documenter how URLs should be generated. The following placeholders will be replaced with the respective value of the generated link:\n\n{commit} Git branch or tag name, or commit hash\n{path} Path to the file in the repository\n{line} Line (or range of lines) in the source file\n\nFor example if you are using GitLab.com, you could use\n\nmakedocs(repo = \"https://gitlab.com/user/project/blob/{commit}{path}#{line}\")\n\nExperimental keywords\n\nIn addition to standard arguments there is a set of non-finalized experimental keyword arguments. The behaviour of these may change or they may be removed without deprecation when a minor version changes (i.e. except in patch releases).\n\ncheckdocs 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 blocks with that docstring). Possible values are :all (check all names) and :exports (check only exported names). The default value is :none, in which case no checks are performed. If strict is also enabled then the build will fail if any missing docstrings are encountered.\n\nlinkcheck – 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. If strict is also enabled then the build will fail if there are any broken (400+ status code) links. Default: false.\n\nlinkcheck_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.\n\nstrict – makedocs fails the build right before rendering if it encountered any errors with the document in the previous build phases.\n\nOutput formats\n\nformat allows the output format to be specified. The default format is Documenter.HTML which creates a set of HTML files.\n\nThere are other possible formats that are enabled by using other addon-packages. For examples, the DocumenterMarkdown package define the DocumenterMarkdown.Markdown() format for use with e.g. MkDocs, and the DocumenterLaTeX package define the DocumenterLaTeX.LaTeX() format for LaTeX / PDF output. See the Other Output Formats for more information.\n\nSee Also\n\nA guide detailing how to document a package using Documenter's makedocs is provided in the setup guide in the manual.\n\n\n\n\n\n",
"title": "Documenter.makedocs"
},
{
"category": "function",
"location": "lib/public/#DocumenterTools.Travis.genkeys",
"page": "Public",
"text": "genkeys(; user=\"$USER\", repo=\"$REPO\")\n\nGenerates the SSH keys necessary for the automatic deployment of documentation with Documenter from Travis to GitHub Pages.\n\nBy default the links in the instructions need to be modified to correspond to actual URLs. The optional user and repo keyword arguments can be specified so that the URLs in the printed instructions could be copied directly. They should be the name of the GitHub user or organization where the repository is hosted and the full name of the repository, respectively.\n\nThis method of genkeys requires the following command lines programs to be installed:\n\nwhich\nssh-keygen\n\nExamples\n\njulia> using DocumenterTools\n\njulia> Travis.genkeys()\n[ Info: add the public key below to https://github.com/$USER/$REPO/settings/keys with read/write access:\n\nssh-rsa AAAAB3NzaC2yc2EAAAaDAQABAAABAQDrNsUZYBWJtXYUk21wxZbX3KxcH8EqzR3ZdTna0Wgk...jNmUiGEMKrr0aqQMZEL2BG7 username@hostname\n\n[ Info: add a secure environment variable named 'DOCUMENTER_KEY' to https://travis-ci.org/$USER/$REPO/settings with value:\n\nLS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBNnpiRkdXQVZpYlIy...QkVBRWFjY3BxaW9uNjFLaVdOcDU5T2YrUkdmCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==\n\n\njulia> Travis.genkeys(user=\"JuliaDocs\", repo=\"DocumenterTools.jl\")\n[Info: add the public key below to https://github.com/JuliaDocs/DocumenterTools.jl/settings/keys with read/write access:\n\nssh-rsa AAAAB3NzaC2yc2EAAAaDAQABAAABAQDrNsUZYBWJtXYUk21wxZbX3KxcH8EqzR3ZdTna0Wgk...jNmUiGEMKrr0aqQMZEL2BG7 username@hostname\n\n[ Info: add a secure environment variable named 'DOCUMENTER_KEY' to https://travis-ci.org/JuliaDocs/DocumenterTools.jl/settings with value:\n\nLS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBNnpiRkdXQVZpYlIy...QkVBRWFjY3BxaW9uNjFLaVdOcDU5T2YrUkdmCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==\n\n\n\n\n\ngenkeys(package::Module; remote=\"origin\")\n\nLike the other method, this generates the SSH keys necessary for the automatic deployment of documentation with Documenter from Travis to GitHub Pages, but attempts to guess the package URLs from the Git remote.\n\npackage needs to be the top level module of the package. The remote keyword argument can be used to specify which Git remote is used for guessing the repository's GitHub URL.\n\nThis method requires the following command lines programs to be installed:\n\nwhich\ngit\nssh-keygen\n\nnote: Note\nThe package must be in development mode. Make sure you run pkg> develop pkg from the Pkg REPL, or Pkg.develop(\"pkg\") before generating the SSH keys.\n\nExamples\n\njulia> using DocumenterTools\n\njulia> Travis.genkeys(DocumenterTools)\n[Info: add the public key below to https://github.com/JuliaDocs/DocumenterTools.jl/settings/keys with read/write access:\n\nssh-rsa AAAAB3NzaC2yc2EAAAaDAQABAAABAQDrNsUZYBWJtXYUk21wxZbX3KxcH8EqzR3ZdTna0Wgk...jNmUiGEMKrr0aqQMZEL2BG7 username@hostname\n\n[ Info: add a secure environment variable named 'DOCUMENTER_KEY' to https://travis-ci.org/JuliaDocs/DocumenterTools.jl/settings with value:\n\nLS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBNnpiRkdXQVZpYlIy...QkVBRWFjY3BxaW9uNjFLaVdOcDU5T2YrUkdmCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==\n\n\n\n\n\n",
"title": "DocumenterTools.Travis.genkeys"
},
{
"category": "function",
"location": "lib/public/#DocumenterTools.generate",
"page": "Public",
"text": "DocumenterTools.generate(path::String; name = nothing, format = :html)\n\nCreate 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.\n\ngenerate creates the following files in path:\n\n.gitignore\nsrc/index.md\nmake.jl\nmkdocs.yml\nProject.toml\n\nArguments\n\npath file path to the documentation directory.\n\nKeywords Arguments\n\nname is the name of the package (without .jl). If name is not given generate tries to detect it automatically.\n\nformat can be either :html (default), :markdown or :pdf corresponding to the format keyword to Documenter's makedocs function, see Documenter's manual.\n\nExamples\n\njulia> using DocumenterTools\n\njulia> Documenter.generate(\"path/to/MyPackage/docs\")\n[ ... output ... ]\n\n\n\n\n\nDocumenterTools.generate(pkg::Module; dir = \"docs\", format = :html)\n\nSame as generate(path::String) but the path and name is determined automatically from the module.\n\nnote: Note\nThe package must be in development mode. Make sure you run pkg> develop pkg from the Pkg REPL, or Pkg.develop(\"pkg\") before generating docs.\n\nExamples\n\njulia> using DocumenterTools\n\njulia> using MyPackage\n\njulia> DocumenterTools.generate(MyPackage)\n[ ... output ... ]\n\n\n\n\n\n",
"title": "DocumenterTools.generate"
},
{
"category": "macro",
"location": "lib/internals/dom/#Documenter.Utilities.DOM.@tags-Tuple",
"page": "DOM",
"text": "Define a collection of Tag objects and bind them to constants with the same names.\n\nExamples\n\nDefined globally within a module:\n\n@tags div ul li\n\nDefined within the scope of a function to avoid cluttering the global namespace:\n\nfunction template(args...)\n @tags div ul li\n # ...\nend\n\n\n\n\n\n",
"title": "Documenter.Utilities.DOM.@tags"
},
{
"category": "method",
"location": "lib/internals/anchors/#Documenter.Anchors.add!-Tuple{Documenter.Anchors.AnchorMap,Documenter.Anchors.Anchor,Any,Any}",
"page": "Anchors",
"text": "add!(m, anchor, id, file)\n\n\nAdds a new Anchor to the AnchorMap for a given id and file.\n\nEither an actual Anchor object may be provided or any other object which is automatically wrapped in an Anchor before being added to the AnchorMap.\n\n\n\n\n\n",
"title": "Documenter.Anchors.add!"
},
{
"category": "method",
"location": "lib/internals/anchors/#Documenter.Anchors.anchor-Tuple{Documenter.Anchors.AnchorMap,Any}",
"page": "Anchors",
"text": "anchor(m, id)\n\n\nReturns the Anchor object matching id. file and n may also be provided. An Anchor is returned, or nothing in case of no match.\n\n\n\n\n\n",
"title": "Documenter.Anchors.anchor"
},
{
"category": "method",
"location": "lib/internals/anchors/#Documenter.Anchors.exists-Tuple{Documenter.Anchors.AnchorMap,Any,Any,Any}",
"page": "Anchors",
"text": "exists(m, id, file, n)\n\n\nDoes the given id exist within the AnchorMap? A file and integer n may also be provided to narrow the search for existance.\n\n\n\n\n\n",
"title": "Documenter.Anchors.exists"
},
{
"category": "method",
"location": "lib/internals/anchors/#Documenter.Anchors.isunique-Tuple{Documenter.Anchors.AnchorMap,Any}",
"page": "Anchors",
"text": "isunique(m, id)\n\n\nIs the id unique within the given AnchorMap? May also specify the file.\n\n\n\n\n\n",
"title": "Documenter.Anchors.isunique"
},
{
"category": "method",
"location": "lib/internals/builder/#Documenter.Builder.walk_navpages-NTuple{6,Any}",
"page": "Builder",
"text": "walk_navpages(visible, title, src, children, parent, doc)\n\n\nRecursively walks through the Documents.Document's .user.pages field, generating Documents.NavNodes and related data structures in the process.\n\nThis implementation is the de facto specification for the .user.pages field.\n\n\n\n\n\n",
"title": "Documenter.Builder.walk_navpages"
},
{
"category": "method",
"location": "lib/internals/cross-references/#Documenter.CrossReferences.crossref-Tuple{Documenter.Documents.Document}",
"page": "CrossReferences",
"text": "crossref(doc)\n\n\nTraverses a Documents.Document and replaces links containg @ref URLs with their real URLs.\n\n\n\n\n\n",
"title": "Documenter.CrossReferences.crossref"
},
{
"category": "method",
"location": "lib/internals/cross-references/#Documenter.CrossReferences.find_object-Tuple{Documenter.Documents.Document,Any,Any}",
"page": "CrossReferences",
"text": "find_object(doc, binding, typesig)\n\n\nFind 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.\n\n\n\n\n\n",
"title": "Documenter.CrossReferences.find_object"
},
{
"category": "method",
"location": "lib/internals/docchecks/#Documenter.DocChecks.footnotes-Tuple{Documenter.Documents.Document}",
"page": "DocChecks",
"text": "footnotes(doc)\n\n\nChecks footnote links in a Documents.Document.\n\n\n\n\n\n",
"title": "Documenter.DocChecks.footnotes"
},
{
"category": "method",
"location": "lib/internals/docchecks/#Documenter.DocChecks.linkcheck-Tuple{Documenter.Documents.Document}",
"page": "DocChecks",
"text": "linkcheck(doc)\n\n\nChecks external links using curl.\n\n\n\n\n\n",
"title": "Documenter.DocChecks.linkcheck"
},
{
"category": "method",
"location": "lib/internals/docchecks/#Documenter.DocChecks.missingdocs-Tuple{Documenter.Documents.Document}",
"page": "DocChecks",
"text": "missingdocs(doc)\n\n\nChecks that a Documents.Document contains all available docstrings that are defined in the modules keyword passed to Documenter.makedocs.\n\nPrints out the name of each object that has not had its docs spliced into the document.\n\n\n\n\n\n",
"title": "Documenter.DocChecks.missingdocs"
},
{
"category": "method",
"location": "lib/internals/docsystem/#Documenter.DocSystem.binding-Tuple{Any}",
"page": "DocSystem",
"text": "Converts an object to a Base.Docs.Binding object.\n\nbinding(any)\n\n\nSupported inputs are:\n\nBinding\nDataType\nFunction\nModule\nSymbol\n\nNote that unsupported objects will throw an ArgumentError.\n\n\n\n\n\n",
"title": "Documenter.DocSystem.binding"
},
{
"category": "method",
"location": "lib/internals/docsystem/#Documenter.DocSystem.convertmeta-Tuple{IdDict{Any,Any}}",
"page": "DocSystem",
"text": "convertmeta(meta)\n\n\nConverts a 0.4-style docstring cache into a 0.5 one.\n\nThe original docstring cache is not modified.\n\n\n\n\n\n",
"title": "Documenter.DocSystem.convertmeta"
},
{
"category": "method",
"location": "lib/internals/docsystem/#Documenter.DocSystem.docstr-Tuple{Markdown.MD}",
"page": "DocSystem",
"text": "docstr(md; kws...)\n\n\nConstruct a DocStr object from a Markdown.MD object.\n\nThe optional keyword arguments are used to add new data to the DocStr's .data dictionary.\n\n\n\n\n\n",
"title": "Documenter.DocSystem.docstr"
},
{
"category": "method",
"location": "lib/internals/doctests/#Documenter.DocTests.doctest-Tuple{Documenter.Documents.Document}",
"page": "DocTests",
"text": "doctest(doc)\n\n\nTraverses the document tree and tries to run each Julia code block encountered. Will abort the document generation when an error is thrown. Use doctest = false keyword in Documenter.makedocs to disable doctesting.\n\n\n\n\n\n",
"title": "Documenter.DocTests.doctest"
},
{
"category": "method",
"location": "lib/internals/documentertools/#DocumenterTools.Generator.gitignore-Tuple{}",
"page": "DocumenterTools",
"text": "gitignore()\n\n\nContents of the default .gitignore file.\n\n\n\n\n\n",
"title": "DocumenterTools.Generator.gitignore"
},
{
"category": "method",
"location": "lib/internals/documentertools/#DocumenterTools.Generator.index-Tuple{Any}",
"page": "DocumenterTools",
"text": "index(pkgname)\n\n\nContents of the default src/index.md file.\n\n\n\n\n\n",
"title": "DocumenterTools.Generator.index"
},
{
"category": "method",
"location": "lib/internals/documentertools/#DocumenterTools.Generator.make-Tuple{Any}",
"page": "DocumenterTools",
"text": "make(pkgname; format)\n\n\nContents of the default make.jl file.\n\n\n\n\n\n",
"title": "DocumenterTools.Generator.make"
},
{
"category": "method",
"location": "lib/internals/documentertools/#DocumenterTools.Generator.mkdocs-Tuple{Any}",
"page": "DocumenterTools",
"text": "mkdocs(pkgname; description, author, url)\n\n\nContents of the default mkdocs.yml file.\n\n\n\n\n\n",
"title": "DocumenterTools.Generator.mkdocs"
},
{
"category": "method",
"location": "lib/internals/documentertools/#DocumenterTools.Generator.project-Tuple{}",
"page": "DocumenterTools",
"text": "project(; format)\n\n\nContents of the default Project.toml file.\n\n\n\n\n\n",
"title": "DocumenterTools.Generator.project"
},
{
"category": "method",
"location": "lib/internals/documentertools/#DocumenterTools.Generator.savefile-Tuple{Any,Any,Any}",
"page": "DocumenterTools",
"text": "savefile(f, root, filename)\n\n\nAttempts to save a file at $(root)/$(filename). f will be called with file stream (see open).\n\nfilename can also be a file in a subdirectory (e.g. src/index.md), and then then subdirectories will be created automatically.\n\n\n\n\n\n",
"title": "DocumenterTools.Generator.savefile"
},
{
"category": "method",
"location": "lib/internals/documents/#Documenter.Documents.getplugin-Union{Tuple{T}, Tuple{Document,Type{T}}} where T<:Documenter.Plugin",
"page": "Documents",
"text": "getplugin(doc::Document, T)\n\nRetrieves the Plugin type for T stored in doc. If T was passed to makedocs, the passed type will be returned. Otherwise, a new T object will be created using the default constructor T().\n\n\n\n\n\n",
"title": "Documenter.Documents.getplugin"
},
{
"category": "method",
"location": "lib/internals/documents/#Documenter.Documents.navpath-Tuple{Documenter.Documents.NavNode}",
"page": "Documents",
"text": "Constructs a list of the ancestors of the navnode (inclding the navnode itself), ordered so that the root of the navigation tree is the first and navnode itself is the last item.\n\n\n\n\n\n",
"title": "Documenter.Documents.navpath"
},
{
"category": "method",
"location": "lib/internals/documents/#Documenter.Documents.populate!-Tuple{Documenter.Documents.Document}",
"page": "Documents",
"text": "populate!(document)\n\n\nPopulates the ContentsNodes and IndexNodes of the document with links.\n\nThis 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.\n\n\n\n\n\n",
"title": "Documenter.Documents.populate!"
},
{
"category": "method",
"location": "lib/internals/documents/#Documenter.Documents.walk-Tuple{Any,Any,Any}",
"page": "Documents",
"text": "walk(f, meta, element)\n\n\nCalls f on element and any of its child elements. meta is a Dict containing metadata such as current module.\n\n\n\n\n\n",
"title": "Documenter.Documents.walk"
},
{
"category": "method",
"location": "lib/internals/dom/#Documenter.Utilities.DOM.escapehtml-Tuple{AbstractString}",
"page": "DOM",
"text": "Escape characters in the provided string. This converts the following characters:\n\n< to &lt;\n> to &gt;\n& to &amp;\n' to &#39;\n\" to &quot;\n\nWhen 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 ===.\n\n\n\n\n\n",
"title": "Documenter.Utilities.DOM.escapehtml"
},
{
"category": "method",
"location": "lib/internals/dom/#Documenter.Utilities.DOM.flatten!-Tuple{Any,Any,Union{AbstractString, Symbol, Node, Pair}}",
"page": "DOM",
"text": "Signatures\n\nflatten!(f!, out, x::Atom)\nflatten!(f!, out, xs)\n\nFlatten the contents the third argument into the second after applying the function f! to the element.\n\n\n\n\n\n",
"title": "Documenter.Utilities.DOM.flatten!"
},
{
"category": "method",
"location": "lib/internals/mdflatten/#Documenter.Utilities.MDFlatten.mdflatten-Tuple{Any}",
"page": "MDFlatten",
"text": "Convert a Markdown object to a String of only text (i.e. not formatting info).\n\nIt 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.\n\n\n\n\n\n",
"title": "Documenter.Utilities.MDFlatten.mdflatten"
},
{
"category": "method",
"location": "lib/internals/selectors/#Documenter.Utilities.Selectors.disable-Union{Tuple{T}, Tuple{Type{T}}} where T<:Documenter.Utilities.Selectors.AbstractSelector",
"page": "Selectors",
"text": "Disable a particular case in a selector so that it is never used.\n\nSelectors.disable(::Type{Debug}) = true\n\n\n\n\n\n",
"title": "Documenter.Utilities.Selectors.disable"
},
{
"category": "method",
"location": "lib/internals/selectors/#Documenter.Utilities.Selectors.dispatch-Union{Tuple{T}, Tuple{Type{T},Vararg{Any,N} where N}} where T<:Documenter.Utilities.Selectors.AbstractSelector",
"page": "Selectors",
"text": "Call Selectors.runner(T, args...) where T is a subtype of MySelector for which matcher(T, args...) is true.\n\nSelectors.dispatch(MySelector, args...)\n\n\n\n\n\n",
"title": "Documenter.Utilities.Selectors.dispatch"
},
{
"category": "method",
"location": "lib/internals/selectors/#Documenter.Utilities.Selectors.strict-Union{Tuple{T}, Tuple{Type{T}}} where T<:Documenter.Utilities.Selectors.AbstractSelector",
"page": "Selectors",
"text": "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.\n\n# Adding a debugging selector case.\nabstract type Debug <: MySelector end\n\n# Insert prior to all other cases.\nSelectors.order(::Type{Debug}) = 0.0\n\n# Fallthrough to the next case on success.\nSelectors.strict(::Type{Debug}) = false\n\n# We always match, regardless of the value of `x`.\nSelectors.matcher(::Type{Debug}, x) = true\n\n# Print some debugging info.\nSelectors.runner(::Type{Debug}, x) = @show x\n\n\n\n\n\n",
"title": "Documenter.Utilities.Selectors.strict"
},
{
"category": "method",
"location": "lib/internals/textdiff/#Documenter.Utilities.TextDiff.splitby-Tuple{Regex,AbstractString}",
"page": "TextDiff",
"text": "splitby(reg, text)\n\n\nSplits 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.\n\n\n\n\n\n",
"title": "Documenter.Utilities.TextDiff.splitby"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.assetsdir-Tuple{}",
"page": "Utilities",
"text": "Returns the path to the Documenter assets directory.\n\n\n\n\n\n",
"title": "Documenter.Utilities.assetsdir"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.check_kwargs-Tuple{Any}",
"page": "Utilities",
"text": "Prints a formatted warning to the user listing unrecognised keyword arguments.\n\n\n\n\n\n",
"title": "Documenter.Utilities.check_kwargs"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.currentdir-Tuple{}",
"page": "Utilities",
"text": "Returns the current directory.\n\n\n\n\n\n",
"title": "Documenter.Utilities.currentdir"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.doccat-Tuple{Documenter.Utilities.Object}",
"page": "Utilities",
"text": "Returns the category name of the provided Object.\n\n\n\n\n\n",
"title": "Documenter.Utilities.doccat"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.filterdocs-Tuple{Markdown.MD,Set{Module}}",
"page": "Utilities",
"text": "filterdocs(doc, modules)\n\nRemove docstrings from the markdown object, doc, that are not from one of modules.\n\n\n\n\n\n",
"title": "Documenter.Utilities.filterdocs"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.get_commit_short-Tuple{Any}",
"page": "Utilities",
"text": "get_commit_short(dir)\n\n\nReturns the first 5 characters of the current git commit hash of the directory dir.\n\n\n\n\n\n",
"title": "Documenter.Utilities.get_commit_short"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.isabsurl-Tuple{Any}",
"page": "Utilities",
"text": "isabsurl(url)\n\nChecks whether url is an absolute URL (as opposed to a relative one).\n\n\n\n\n\n",
"title": "Documenter.Utilities.isabsurl"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.issubmodule-Tuple{Any,Any}",
"page": "Utilities",
"text": "issubmodule(sub, mod)\n\nChecks whether sub is a submodule of mod. A module is also considered to be its own submodule.\n\nE.g. A.B.C is a submodule of A, A.B and A.B.C, but it is not a submodule of D, A.D nor A.B.C.D.\n\n\n\n\n\n",
"title": "Documenter.Utilities.issubmodule"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.mdparse-Tuple{AbstractString}",
"page": "Utilities",
"text": "mdparse(s::AbstractString; mode=:single)\n\nParses 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.\n\nThe mode keyword argument can be one of the following:\n\n:single (default) – returns a single block-level object (e.g. Markdown.Paragraph or Markdown.Admonition) and errors if the string parses into multiple blocks.\n:blocks – the function returns a Vector{Any} of Markdown blocks.\n: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.\n\n\n\n\n\n",
"title": "Documenter.Utilities.mdparse"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.nodocs-Tuple{Any}",
"page": "Utilities",
"text": "Does the given docstring represent actual documentation or a no docs error message?\n\n\n\n\n\n",
"title": "Documenter.Utilities.nodocs"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.object-Tuple{Union{Expr, Symbol},AbstractString}",
"page": "Utilities",
"text": "object(ex, str)\n\nReturns a expression that, when evaluated, returns an Object representing ex.\n\n\n\n\n\n",
"title": "Documenter.Utilities.object"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.parseblock-Tuple{AbstractString,Any,Any}",
"page": "Utilities",
"text": "Returns a vector of parsed expressions and their corresponding raw strings.\n\nReturns 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.\n\nThe keyword argument skip = N drops the leading N lines from the input string.\n\n\n\n\n\n",
"title": "Documenter.Utilities.parseblock"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.relpath_from_repo_root-Tuple{Any}",
"page": "Utilities",
"text": "relpath_from_repo_root(file)\n\n\nReturns the path of file, relative to the root of the Git repository, or nothing if the file is not in a Git repository.\n\n\n\n\n\n",
"title": "Documenter.Utilities.relpath_from_repo_root"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.repo_root-Tuple{Any}",
"page": "Utilities",
"text": "repo_root(file; dbdir=\".git\")\n\nTries to determine the root directory of the repository containing file. If the file is not in a repository, the function returns nothing.\n\nThe dbdir keyword argument specifies the name of the directory we are searching for to determine if this is a repostory or not. If there is a file called dbdir, then it's contents is checked under the assumption that it is a Git worktree.\n\n\n\n\n\n",
"title": "Documenter.Utilities.repo_root"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.slugify-Tuple{AbstractString}",
"page": "Utilities",
"text": "Slugify a string into a suitable URL.\n\n\n\n\n\n",
"title": "Documenter.Utilities.slugify"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.srcpath-Tuple{Any,Any,Any}",
"page": "Utilities",
"text": "Find the path of a file relative to the source directory. root is the path to the directory containing the file file.\n\nIt is meant to be used with walkdir(source).\n\n\n\n\n\n",
"title": "Documenter.Utilities.srcpath"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.submodules-Tuple{Array{Module,1}}",
"page": "Utilities",
"text": "Returns the set of submodules of a given root module/s.\n\n\n\n\n\n",
"title": "Documenter.Utilities.submodules"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.withoutput-Tuple{Any}",
"page": "Utilities",
"text": "Call a function and capture all stdout and stderr output.\n\nwithoutput(f) --> (result, success, backtrace, output)\n\nwhere\n\nresult is the value returned from calling function f.\nsuccess signals whether f has thrown an error, in which case result stores the Exception that was raised.\nbacktrace a Vector{Ptr{Cvoid}} produced by catch_backtrace() if an error is thrown.\noutput is the combined output of stdout and stderr during execution of f.\n\n\n\n\n\n",
"title": "Documenter.Utilities.withoutput"
},
{
"category": "method",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.collect_subsections-Tuple{Documenter.Documents.Page}",
"page": "Writers",
"text": "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.\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.collect_subsections"
},
{
"category": "method",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.copy_asset-Tuple{Any,Any}",
"page": "Writers",
"text": "Copies an asset from Documenters assets/html/ directory to doc.user.build. Returns the path of the copied asset relative to .build.\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.copy_asset"
},
{
"category": "method",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.domify-Tuple{Any,Any}",
"page": "Writers",
"text": "Converts recursively a Documents.Page, Markdown or Documenter *Node objects into HTML DOM.\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.domify"
},
{
"category": "method",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.fixlinks!-Tuple{Any,Any,Markdown.Link}",
"page": "Writers",
"text": "Replaces URLs in Markdown.Link elements (if they point to a local .md page) with the actual URLs.\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.fixlinks!"
},
{
"category": "method",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.get_url-Tuple{Any,AbstractString}",
"page": "Writers",
"text": "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/.\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.get_url"
},
{
"category": "method",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.get_url-Tuple{Any,Documenter.Documents.NavNode}",
"page": "Writers",
"text": "Returns the full path of a Documents.NavNode relative to src/.\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.get_url"
},
{
"category": "method",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.getpage-Tuple{Any,Any}",
"page": "Writers",
"text": "Returns a page (as a Documents.Page object) using the HTMLContext.\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.getpage"
},
{
"category": "method",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.jsescape-Tuple{Any}",
"page": "Writers",
"text": "Replaces some of the characters in the string with escape sequences so that the strings would be valid JS string literals, as per the ECMAScript® 2017 standard.\n\nNote that it always escapes both potential \" and ' closing quotes.\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.jsescape"
},
{
"category": "method",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.mdconvert-Tuple{Any}",
"page": "Writers",
"text": "Convert a markdown object to a DOM.Node object.\n\nThe parent argument is passed to allow for context-dependant conversions.\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.mdconvert"
},
{
"category": "method",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.navhref-Tuple{Any,Any,Any}",
"page": "Writers",
"text": "Get the relative hyperlink between two Documents.NavNodes. Assumes that both Documents.NavNodes have an associated Documents.Page (i.e. .page is not nothing).\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.navhref"
},
{
"category": "method",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.navitem-Tuple{Any,Any}",
"page": "Writers",
"text": "navitem returns the lists and list items of the navigation menu. It gets called recursively to construct the whole tree.\n\nIt 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(\"\")).\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.navitem"
},
{
"category": "method",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.open_output-Tuple{Any,Any,Any}",
"page": "Writers",
"text": "Opens the output file of the navnode in write node. If necessary, the path to the output file is created before opening the file.\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.open_output"
},
{
"category": "method",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.pagetitle-Tuple{Documenter.Documents.Page}",
"page": "Writers",
"text": "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).\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.pagetitle"
},
{
"category": "method",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.pretty_url-Tuple{Any,AbstractString}",
"page": "Writers",
"text": "If html_prettyurls is enabled, returns a \"pretty\" version of the path which can then be used in links in the resulting HTML file.\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.pretty_url"
},
{
"category": "method",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.relhref-Tuple{Any,Any}",
"page": "Writers",
"text": "Calculates a relative HTML link from one path to another.\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.relhref"
},
{
"category": "method",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.render_page-Tuple{Any,Any}",
"page": "Writers",
"text": "Constructs and writes the page referred to by the navnode to .build.\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.render_page"
},
{
"category": "method",
"location": "lib/internals/writers/#Documenter.Writers.render-Tuple{Documenter.Documents.Document}",
"page": "Writers",
"text": "Writes a Documents.Document object to .user.build directory in the formats specified in the .user.format vector.\n\nAdding additional formats requires adding new Selector definitions as follows:\n\nabstract type CustomFormat <: FormatSelector end\n\nSelectors.order(::Type{CustomFormat}) = 4.0 # or a higher number.\nSelectors.matcher(::Type{CustomFormat}, fmt, _) = fmt === :custom\nSelectors.runner(::Type{CustomFormat}, _, doc) = CustomWriter.render(doc)\n\n# Definition of `CustomWriter` module below...\n\n\n\n\n\n",
"title": "Documenter.Writers.render"
},
{
"category": "module",
"location": "lib/internals/anchors/#Documenter.Anchors",
"page": "Anchors",
"text": "Defines the Anchor and AnchorMap types.\n\nAnchors and AnchorMaps are used to represent links between objects within a document.\n\n\n\n\n\n",
"title": "Documenter.Anchors"
},
{
"category": "module",
"location": "lib/internals/builder/#Documenter.Builder",
"page": "Builder",
"text": "Defines the Documenter.jl build \"pipeline\" named DocumentPipeline.\n\nEach stage of the pipeline performs an action on a Documents.Document object. These actions may involve creating directory structures, expanding templates, running doctests, etc.\n\n\n\n\n\n",
"title": "Documenter.Builder"
},
{
"category": "module",
"location": "lib/internals/cross-references/#Documenter.CrossReferences",
"page": "CrossReferences",
"text": "Provides the crossref function used to automatically calculate link URLs.\n\n\n\n\n\n",
"title": "Documenter.CrossReferences"
},
{
"category": "module",
"location": "lib/internals/docchecks/#Documenter.DocChecks",
"page": "DocChecks",
"text": "Provides the missingdocs, footnotes and linkcheck functions for checking docs.\n\n\n\n\n\n",
"title": "Documenter.DocChecks"
},
{
"category": "module",
"location": "lib/internals/docsystem/#Documenter.DocSystem",
"page": "DocSystem",
"text": "Provides a consistent interface to retreiving DocStr objects from the Julia docsystem in both 0.4 and 0.5.\n\n\n\n\n\n",
"title": "Documenter.DocSystem"
},
{
"category": "module",
"location": "lib/internals/doctests/#Documenter.DocTests",
"page": "DocTests",
"text": "Provides the doctest function that makes sure that the jldoctest code blocks in the documents and docstrings run and are up to date.\n\n\n\n\n\n",
"title": "Documenter.DocTests"
},
{
"category": "module",
"location": "lib/internals/documentertools/#DocumenterTools.Generator",
"page": "DocumenterTools",
"text": "Provides the functions related to generating documentation stubs.\n\n\n\n\n\n",
"title": "DocumenterTools.Generator"
},
{
"category": "module",
"location": "lib/internals/documents/#Documenter.Documents",
"page": "Documents",
"text": "Defines Document and its supporting types\n\nPage\nUser\nInternal\nGlobals\n\n\n\n\n\n",
"title": "Documenter.Documents"
},
{
"category": "module",
"location": "lib/internals/dom/#Documenter.Utilities.DOM",
"page": "DOM",
"text": "Provides a domain specific language for representing HTML documents.\n\nExamples\n\nusing Documenter.Utilities.DOM\n\n# `DOM` does not export any HTML tags. Define the ones we actually need.\n@tags div p em strong ul li\n\ndiv(\n p(\"This \", em(\"is\"), \" a \", strong(\"paragraph.\"),\n p(\"And this is \", strong(\"another\"), \" one\"),\n ul(\n li(\"and\"),\n li(\"an\"),\n li(\"unordered\"),\n li(\"list\")\n )\n)\n\nNotes\n\nAll the arguments passed to a node are flattened into a single vector rather than preserving any nested structure. This means that passing two vectors of nodes to a div will result in a div node with a single vector of children (the concatenation of the two vectors) rather than two vector children. The only arguments that are not flattened are nested nodes.\n\nString arguments are automatically converted into text nodes. Text nodes do not have any children or attributes and when displayed the string is escaped using escapehtml.\n\nAttributes\n\nAs well as plain nodes shown in the previous example, nodes can have attributes added to them using the following syntax.\n\ndiv[\".my-class\"](\n img[:src => \"foo.jpg\"],\n input[\"#my-id\", :disabled]\n)\n\nIn the above example we add a class = \"my-class\" attribute to the div node, a src = \"foo.jpg\" to the img, and id = \"my-id\" disabled attributes to the input node.\n\nThe following syntax is supported within [...]:\n\ntag[\"#id\"]\ntag[\".class\"]\ntag[\".class#id\"]\ntag[:disabled]\ntag[:src => \"foo.jpg\"]\n# ... or any combination of the above arguments.\n\nInternal Representation\n\nThe @tags macro defines named Tag objects as follows\n\n@tags div p em strong\n\nexpands to\n\nconst div, p, em, strong = Tag(:div), Tag(:p), Tag(:em), Tag(:strong)\n\nThese 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.\n\ntag(...) # No attributes.\ntag[...] # No children.\ntag[...](...) # Has both attributes and children.\n\nAll 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 nessesary text escaped.\n\n\n\n\n\n",
"title": "Documenter.Utilities.DOM"
},
{
"category": "module",
"location": "lib/internals/expanders/#Documenter.Expanders",
"page": "Expanders",
"text": "Defines node \"expanders\" that transform nodes from the parsed markdown files.\n\n\n\n\n\n",
"title": "Documenter.Expanders"
},
{
"category": "module",
"location": "lib/internals/mdflatten/#Documenter.Utilities.MDFlatten",
"page": "MDFlatten",
"text": "Provides the mdflatten function that can \"flatten\" Markdown objects into a string, with formatting etc. stripped.\n\nNote that the tests in test/mdflatten.jl should be considered to be the spec for the output (number of newlines, indents, formatting, etc.).\n\n\n\n\n\n",
"title": "Documenter.Utilities.MDFlatten"
},
{
"category": "module",
"location": "lib/internals/selectors/#Documenter.Utilities.Selectors",
"page": "Selectors",
"text": "An extensible code selection interface.\n\nThe Selectors module provides an extensible way to write code that has to dispatch on different predicates without hardcoding the control flow into a single chain of if statements.\n\nIn the following example a selector for a simple condition is implemented and the generated selector code is described:\n\nabstract type MySelector <: Selectors.AbstractSelector end\n\n# The different cases we want to test.\nabstract type One <: MySelector end\nabstract type NotOne <: MySelector end\n\n# The order in which to test the cases.\nSelectors.order(::Type{One}) = 0.0\nSelectors.order(::Type{NotOne}) = 1.0\n\n# The predicate to test against.\nSelectors.matcher(::Type{One}, x) = x === 1\nSelectors.matcher(::Type{NotOne}, x) = x !== 1\n\n# What to do when a test is successful.\nSelectors.runner(::Type{One}, x) = println(\"found one\")\nSelectors.runner(::Type{NotOne}, x) = println(\"not found\")\n\n# Test our selector with some numbers.\nfor i in 0:5\n Selectors.dispatch(MySelector, i)\nend\n\nSelectors.dispatch(Selector, i) will behave equivalent to the following:\n\nfunction dispatch(::Type{MySelector}, i::Int)\n if matcher(One, i)\n runner(One, i)\n elseif matcher(NotOne, i)\n runner(NotOne, i)\n end\nend\n\nand further to\n\nfunction dispatch(::Type{MySelector}, i::Int)\n if i === 1\n println(\"found one\")\n elseif i !== 1\n println(\"not found\")\n end\nend\n\nThe module provides the following interface for creating selectors:\n\norder\nmatcher\nrunner\nstrict\ndisable\ndispatch\n\n\n\n\n\n",
"title": "Documenter.Utilities.Selectors"
},
{
"category": "module",
"location": "lib/internals/utilities/#Documenter.Utilities",
"page": "Utilities",
"text": "Provides a collection of utility functions and types that are used in other submodules.\n\n\n\n\n\n",
"title": "Documenter.Utilities"
},
{
"category": "module",
"location": "lib/internals/writers/#Documenter.Writers",
"page": "Writers",
"text": "A module that provides several renderers for Document objects. The supported formats are currently:\n\n:markdown – the default format.\n:html – generates a complete HTML site with navigation and search included.\n:latex – generates a PDF using LuaLaTeX.\n\n\n\n\n\n",
"title": "Documenter.Writers"
},
{
"category": "module",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter",
"page": "Writers",
"text": "A module for rendering Document objects to HTML.\n\nKeywords\n\nHTMLWriter 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_branch and prettyurls.\n\nsitename is the site's title displayed in the title bar and at the top of the *navigation menu. This argument is mandatory for HTMLWriter.\n\npages defines the hierarchy of the navigation menu.\n\nExperimental keywords\n\nversion 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.\n\nHTML Plugin options\n\nThe HTML Documenter.Plugin provides additional customization options for the HTMLWriter. For more information, see the HTML documentation.\n\nPage outline\n\nThe 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:\n\nIt is then used to automatically determine the page title in the navigation menu and in the <title> tag, unless specified in the .pages option.\nIf the first heading is interpreted as being the page title, it is not displayed in the navigation sidebar.\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter"
},
{
"category": "module",
"location": "lib/internals/writers/#Documenter.Writers.LaTeXWriter",
"page": "Writers",
"text": "A module for rendering Document objects to LaTeX and PDF.\n\nKeywords\n\nLaTeXWriter uses the following additional keyword arguments that can be passed to Documenter.makedocs: authors, sitename.\n\nsitename 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.\n\nauthors can be used to specify the authors of. It goes into the \\author LaTeX command.\n\n\n\n\n\n",
"title": "Documenter.Writers.LaTeXWriter"
},
{
"category": "module",
"location": "lib/internals/writers/#Documenter.Writers.MarkdownWriter",
"page": "Writers",
"text": "A module for rendering Document objects to markdown.\n\n\n\n\n\n",
"title": "Documenter.Writers.MarkdownWriter"
},
{
"category": "module",
"location": "lib/public/#Documenter",
"page": "Public",
"text": "Main module for Documenter.jl – a documentation generation package for Julia.\n\nTwo functions are exported from this module for public use:\n\nmakedocs. Generates documentation from docstrings and templated markdown files.\ndeploydocs. Deploys generated documentation from Travis-CI to GitHub Pages.\n\nExports\n\nDeps\ndeploydocs\nhide\nmakedocs\n\n\n\n\n\n",
"title": "Documenter"
},
{
"category": "module",
"location": "lib/public/#Documenter.Deps",
"page": "Public",
"text": "Exported module that provides build and deploy dependencies and related functions.\n\nCurrently only pip is implemented.\n\n\n\n\n\n",
"title": "Documenter.Deps"
},
{
"category": "module",
"location": "lib/public/#DocumenterTools.Travis",
"page": "Public",
"text": "Package functions for interacting with Travis.\n\ngenkeys\n\n\n\n\n\n",
"title": "DocumenterTools.Travis"
},
{
"category": "page",
"location": "#",
"page": "Home",
"text": "",
"title": "Home"
},
{
"category": "page",
"location": "contributing/#",
"page": "Contributing",
"text": "",
"title": "Contributing"
},
{
"category": "page",
"location": "lib/internals/#",
"page": "Internals",
"text": "",
"title": "Internals"
},
{
"category": "page",
"location": "lib/internals/anchors/#",
"page": "Anchors",
"text": "",
"title": "Anchors"
},
{
"category": "page",
"location": "lib/internals/builder/#",
"page": "Builder",
"text": "",
"title": "Builder"
},
{
"category": "page",
"location": "lib/internals/cross-references/#",
"page": "CrossReferences",
"text": "",
"title": "CrossReferences"
},
{
"category": "page",
"location": "lib/internals/docchecks/#",
"page": "DocChecks",
"text": "",
"title": "DocChecks"
},
{
"category": "page",
"location": "lib/internals/docsystem/#",
"page": "DocSystem",
"text": "",
"title": "DocSystem"
},
{
"category": "page",
"location": "lib/internals/doctests/#",
"page": "DocTests",
"text": "",
"title": "DocTests"
},
{
"category": "page",
"location": "lib/internals/documenter/#",
"page": "Documenter",
"text": "",
"title": "Documenter"
},
{
"category": "page",
"location": "lib/internals/documentertools/#",
"page": "DocumenterTools",
"text": "",
"title": "DocumenterTools"
},
{
"category": "page",
"location": "lib/internals/documents/#",
"page": "Documents",
"text": "",
"title": "Documents"
},
{
"category": "page",
"location": "lib/internals/dom/#",
"page": "DOM",
"text": "",
"title": "DOM"
},
{
"category": "page",
"location": "lib/internals/expanders/#",
"page": "Expanders",
"text": "",
"title": "Expanders"
},
{
"category": "page",
"location": "lib/internals/mdflatten/#",
"page": "MDFlatten",
"text": "",
"title": "MDFlatten"
},
{
"category": "page",
"location": "lib/internals/selectors/#",
"page": "Selectors",
"text": "",
"title": "Selectors"
},
{
"category": "page",
"location": "lib/internals/textdiff/#",
"page": "TextDiff",
"text": "",
"title": "TextDiff"
},
{
"category": "page",
"location": "lib/internals/utilities/#",
"page": "Utilities",
"text": "",
"title": "Utilities"
},
{
"category": "page",
"location": "lib/internals/writers/#",
"page": "Writers",
"text": "",
"title": "Writers"
},
{
"category": "page",
"location": "lib/public/#",
"page": "Public",
"text": "",
"title": "Public"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "",
"title": "Doctests"
},
{
"category": "page",
"location": "man/examples/#",
"page": "Examples",
"text": "",
"title": "Examples"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "",
"title": "Guide"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/latex/#",
"page": "LaTeX Syntax",
"text": "",
"title": "LaTeX Syntax"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "",
"title": "Syntax"
},
{
"category": "section",
"location": "#Documenter.jl-1",
"page": "Home",
"text": "A documentation generator for Julia.A package for building documentation from docstrings and markdown files.note: Note\nPlease 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.",
"title": "Documenter.jl"
},
{
"category": "section",
"location": "#Library-Outline-1",
"page": "Home",
"text": "Pages = [\"lib/public.md\", \"lib/internals.md\"]",
"title": "Library Outline"
},
{
"category": "section",
"location": "#Manual-Outline-1",
"page": "Home",
"text": "Pages = [\n \"man/guide.md\",\n \"man/examples.md\",\n \"man/syntax.md\",\n \"man/doctests.md\",\n \"man/hosting.md\",\n \"man/latex.md\",\n \"man/contributing.md\",\n]\nDepth = 1",
"title": "Manual Outline"
},
{
"category": "section",
"location": "#Package-Features-1",
"page": "Home",
"text": "Write all your documentation in Markdown.\nMinimal configuration.\nSupports Julia 0.7 and 1.0.\nDoctests Julia code blocks.\nCross references for docs and section headers.\nLaTeX syntax support.\nChecks for missing docstrings and incorrect cross references.\nGenerates tables of contents and docstring indexes.\nAutomatically builds and deploys docs from Travis to GitHub Pages.The Package Guide provides a tutorial explaining how to get started using Documenter.Some examples of packages using Documenter can be found on the Examples page.See the Index for the complete list of documented functions and types.",
"title": "Package Features"
},
{
"category": "section",
"location": "#main-index-1",
"page": "Home",
"text": "Pages = [\"lib/public.md\"]",
"title": "Index"
},
{
"category": "section",
"location": "contributing/#Backports-1",
"page": "Contributing",
"text": "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.",
"title": "Backports"
},
{
"category": "section",
"location": "contributing/#Branches-1",
"page": "Contributing",
"text": "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.",
"title": "Branches"
},
{
"category": "section",
"location": "contributing/#Contributing-1",
"page": "Contributing",
"text": "This page details the some of the guidelines that should be followed when contributing to this package.",
"title": "Contributing"
},
{
"category": "section",
"location": "contributing/#Julia-1",
"page": "Contributing",
"text": "4-space indentation;\nmodules spanning entire files should not be indented, but modules that have surrounding code should;\nno blank lines at the start or end of files;\ndo not manually align syntax such as = or :: over adjacent lines;\nuse function ... end when a method definition contains more than one toplevel expression;\nrelated short-form method definitions don't need a new line between them;\nunrelated or long-form method definitions must have a blank line separating each one;\nsurround all binary operators with whitespace except for ::, ^, and :;\nfiles containing a single module ... end must be named after the module;\nmethod arguments should be ordered based on the amount of usage within the method body;\nmethods extended from other modules must follow their inherited argument order, not the above rule;\nexplicit return should be preferred except in short-form method definitions;\navoid dense expressions where possible e.g. prefer nested ifs over complex nested ?s;\ninclude a trailing , in vectors, tuples, or method calls that span several lines;\ndo not use multiline comments (#= and =#);\nwrap long lines as near to 92 characters as possible, this includes docstrings;\nfollow the standard naming conventions used in Base.",
"title": "Julia"
},
{
"category": "section",
"location": "contributing/#Markdown-1",
"page": "Contributing",
"text": "Use unbalanced # headers, i.e. no # on the right hand side of the header text;\ninclude a single blank line between toplevel blocks;\nunordered lists must use * bullets with two preceding spaces;\ndo not hard wrap lines;\nuse emphasis (*) and bold (**) sparingly;\nalways use fenced code blocks instead of indented blocks;\nfollow the conventions outlined in the Julia documentation page on documentation.",
"title": "Markdown"
},
{
"category": "section",
"location": "contributing/#Style-Guide-1",
"page": "Contributing",
"text": "Follow the style of the surrounding text when making changes. When adding new features please try to stick to the following points whenever applicable.",
"title": "Style Guide"
},
{
"category": "section",
"location": "contributing/#release-*-branches-1",
"page": "Contributing",
"text": "Each new minor version x.y.0 gets a branch called release-x.y (a protected branch).\nNew versions are usually tagged only from the release-x.y branches.\nFor 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).\nThe old release-* branches may be removed once they have outlived their usefulness.\nPatch version milestones are used to keep track of which PRs get backported etc.",
"title": "release-* branches"
},
{
"category": "section",
"location": "lib/internals/#Contents-1",
"page": "Internals",
"text": "Pages = [joinpath(\"internals\", f) for f in readdir(\"internals\")]",
"title": "Contents"
},
{
"category": "section",
"location": "lib/internals/#Index-1",
"page": "Internals",
"text": "A list of all internal documentation sorted by module.Pages = [joinpath(\"internals\", f) for f in readdir(\"internals\")]",
"title": "Index"
},
{
"category": "section",
"location": "lib/internals/#Internal-Documentation-1",
"page": "Internals",
"text": "This page lists all the documented internals of the Documenter module and submodules.",
"title": "Internal Documentation"
},
{
"category": "section",
"location": "lib/internals/anchors/#Anchors-1",
"page": "Anchors",
"text": "Modules = [Documenter.Anchors]",
"title": "Anchors"
},
{
"category": "section",
"location": "lib/internals/builder/#Builder-1",
"page": "Builder",
"text": "Modules = [Documenter.Builder]",
"title": "Builder"
},
{
"category": "section",
"location": "lib/internals/cross-references/#CrossReferences-1",
"page": "CrossReferences",
"text": "Modules = [Documenter.CrossReferences]",
"title": "CrossReferences"
},
{
"category": "section",
"location": "lib/internals/docchecks/#DocChecks-1",
"page": "DocChecks",
"text": "Modules = [Documenter.DocChecks]",
"title": "DocChecks"
},
{
"category": "section",
"location": "lib/internals/docsystem/#DocSystem-1",
"page": "DocSystem",
"text": "Modules = [Documenter.DocSystem]",
"title": "DocSystem"
},
{
"category": "section",
"location": "lib/internals/doctests/#DocTests-1",
"page": "DocTests",
"text": "Modules = [Documenter.DocTests]",
"title": "DocTests"
},
{
"category": "section",
"location": "lib/internals/documenter/#Documenter-1",
"page": "Documenter",
"text": "Documenter.gitrm_copy\nDocumenter.git_push",
"title": "Documenter"
},
{
"category": "section",
"location": "lib/internals/documentertools/#DocumenterTools-1",
"page": "DocumenterTools",
"text": "DocumenterTools.package_devpath",
"title": "DocumenterTools"
},
{
"category": "section",
"location": "lib/internals/documentertools/#Generator-1",
"page": "DocumenterTools",
"text": "Modules = [DocumenterTools.Generator]",
"title": "Generator"
},
{
"category": "section",
"location": "lib/internals/documents/#Documents-1",
"page": "Documents",
"text": "Modules = [Documenter.Documents]",
"title": "Documents"
},
{
"category": "section",
"location": "lib/internals/dom/#DOM-1",
"page": "DOM",
"text": "Modules = [Documenter.Utilities.DOM]",
"title": "DOM"
},
{
"category": "section",
"location": "lib/internals/expanders/#Expanders-1",
"page": "Expanders",
"text": "Modules = [Documenter.Expanders]",
"title": "Expanders"
},
{
"category": "section",
"location": "lib/internals/mdflatten/#MDFlatten-1",
"page": "MDFlatten",
"text": "Modules = [Documenter.Utilities.MDFlatten]",
"title": "MDFlatten"
},
{
"category": "section",
"location": "lib/internals/selectors/#Selectors-1",
"page": "Selectors",
"text": "Modules = [Documenter.Selectors]",
"title": "Selectors"
},
{
"category": "section",
"location": "lib/internals/textdiff/#TextDiff-1",
"page": "TextDiff",
"text": "Modules = [Documenter.Utilities.TextDiff]",
"title": "TextDiff"
},
{
"category": "section",
"location": "lib/internals/utilities/#Utilities-1",
"page": "Utilities",
"text": "Modules = [Documenter.Utilities]",
"title": "Utilities"
},
{
"category": "section",
"location": "lib/internals/writers/#Writers-1",
"page": "Writers",
"text": "Modules = [\n Documenter.Writers,\n Documenter.Writers.MarkdownWriter,\n Documenter.Writers.HTMLWriter,\n Documenter.Writers.LaTeXWriter,\n]Documenter.Plugin",
"title": "Writers"
},
{
"category": "section",
"location": "lib/public/#Contents-1",
"page": "Public",
"text": "Pages = [\"public.md\"]",
"title": "Contents"
},
{
"category": "section",
"location": "lib/public/#DocumenterTools-1",
"page": "Public",
"text": "DocumenterTools.generate\nDocumenterTools.Travis.genkeys\nDocumenterTools.Travis",
"title": "DocumenterTools"
},
{
"category": "section",
"location": "lib/public/#Index-1",
"page": "Public",
"text": "Pages = [\"public.md\"]",
"title": "Index"
},
{
"category": "section",
"location": "lib/public/#Public-Documentation-1",
"page": "Public",
"text": "Documentation for Documenter.jl's public interface.See Internal Documentation for internal package docs covering all submodules.",
"title": "Public Documentation"
},
{
"category": "section",
"location": "lib/public/#Public-Interface-1",
"page": "Public",
"text": "Documenter\nmakedocs\nhide\ndeploydocs\nDeps\nDeps.pip",
"title": "Public Interface"
},
{
"category": "section",
"location": "man/doctests/#Doctests-1",
"page": "Doctests",
"text": "Documenter will, by default, try to run jldoctest code blocks that it finds in the generated documentation. This can help to avoid documentation examples from becoming outdated, incorrect, or misleading. It's recommended that as many of a package's examples be runnable by Documenter's doctest.This section of the manual outlines how to go about enabling doctests for code blocks in your package's documentation.",
"title": "Doctests"
},
{
"category": "section",
"location": "man/doctests/#Exceptions-1",
"page": "Doctests",
"text": "Doctests can also test for thrown exceptions and their stacktraces. Comparing of the actual and expected results is done by checking whether the expected result matches the start of the actual result. Hence, both of the following errors will match the actual result.```jldoctest\njulia> div(1, 0)\nERROR: DivideError: integer division error\n in div(::Int64, ::Int64) at ./int.jl:115\n\njulia> div(1, 0)\nERROR: DivideError: integer division error\n```If instead the first div(1, 0) error was written as```jldoctest\njulia> div(1, 0)\nERROR: DivideError: integer division error\n in div(::Int64, ::Int64) at ./int.jl:114\n```where line 115 is replaced with 114 then the doctest will fail.In the second div(1, 0), where no stacktrace is shown, it may appear to the reader that it is expected that no stacktrace will actually be displayed when they attempt to try to recreate the error themselves. To indicate to readers that the output result is truncated and does not display the entire (or any of) the stacktrace you may write [...] at the line where checking should stop, i.e.```jldoctest\njulia> div(1, 0)\nERROR: DivideError: integer division error\n[...]\n```",
"title": "Exceptions"
},
{
"category": "section",
"location": "man/doctests/#Filtering-Doctests-1",
"page": "Doctests",
"text": "A part of the output of a doctest might be non-deterministic, e.g. pointer addresses and timings. It is therefore possible to filter a doctest so that the deterministic part can still be tested.A filter takes the form of a regular expression. In a doctest, each match in the expected output and the actual output is removed before the two outputs are compared. Filters are added globally, i.e. applied to all doctests in the documentation, by passing a list of regular expressions to makedocs with the keyword doctestfilters.For more fine grained control it is possible to define filters in @meta blocks by assigning them to the DocTestFilters variable, either as a single regular expression (DocTestFilters = [r\"foo\"]) or as a vector of several regex (DocTestFilters = [r\"foo\", r\"bar\"]).An example is given below where some of the non-deterministic output from @time is filtered.```@meta\nDocTestFilters = r\"[0-9\\.]+ seconds \\(.*\\)\"\n```\n\n```jldoctest\njulia> @time [1,2,3,4]\n 0.000003 seconds (5 allocations: 272 bytes)\n4-element Array{Int64,1}:\n 1\n 2\n 3\n 4\n```\n\n```@meta\nDocTestFilters = nothing\n```The DocTestFilters = nothing is not strictly necessary, but good practice nonetheless to help avoid unintentional filtering in following doctest blocks.Another option is to use the filter keyword argument. This defines a doctest-local filter which is only active for the specific doctest. Note that such filters are not shared between named doctests either. It is possible to define a filter by a single regex (filter = r\"foo\") or as a list of regex (filter = [r\"foo\", r\"bar\"]). Example:```jldoctest; filter = r\"[0-9\\.]+ seconds \\(.*\\)\"\njulia> @time [1,2,3,4]\n 0.000003 seconds (5 allocations: 272 bytes)\n4-element Array{Int64,1}:\n 1\n 2\n 3\n 4\n```note: Note\nThe global filters, filters defined in @meta blocks, and filters defined with the filter keyword argument are all applied to each doctest.",
"title": "Filtering Doctests"
},
{
"category": "section",
"location": "man/doctests/#Fixing-Outdated-Doctests-1",
"page": "Doctests",
"text": "To fix outdated doctests, the doctest flag to makedocs can be set to doctest = :fix. This will run the doctests, and overwrite the old results with the new output.note: Note\nThe :fix option currently only works for LF line endings ('\\n')note: Note\nIt is recommended to git commit any code changes before running the doctest fixing. That way it is simple to restore to the previous state if the fixing goes wrong.note: Note\nThere are some corner cases where the fixing algorithm may replace the wrong code snippet. It is therefore recommended to manually inspect the result of the fixing before committing.",
"title": "Fixing Outdated Doctests"
},
{
"category": "section",
"location": "man/doctests/#Preserving-Definitions-Between-Blocks-1",
"page": "Doctests",
"text": "Every doctest block is evaluated inside its own module. This means that definitions (types, variables, functions etc.) from a block can not be used in the next block. For example:```jldoctest\njulia> foo = 42\n42\n```The variable foo will not be defined in the next block:```jldoctest\njulia> println(foo)\nERROR: UndefVarError: foo not defined\n```To preserve definitions it is possible to label blocks in order to collect several blocks into the same module. All blocks with the same label (in the same file) will be evaluated in the same module, and hence share scope. This can be useful if the same definitions are used in more than one block, with for example text, or other doctest blocks, in between. Example:```jldoctest mylabel\njulia> foo = 42\n42\n```Now, since the block below has the same label as the block above, the variable foo can be used:```jldoctest mylabel\njulia> println(foo)\n42\n```note: Note\nLabeled doctest blocks does not need to be consecutive (as in the example above) to be included in the same module. They can be interspaced with unlabeled blocks or blocks with another label.",
"title": "Preserving Definitions Between Blocks"
},
{
"category": "section",
"location": "man/doctests/#REPL-Examples-1",
"page": "Doctests",
"text": "The other kind of doctest is a simulated Julia REPL session. The following format is detected by Documenter as a REPL doctest:```jldoctest\njulia> a = 1\n1\n\njulia> b = 2;\n\njulia> c = 3; # comment\n\njulia> a + b + c\n6\n```As with script doctests, the code block must have it's language set to jldoctest. When a code block contains one or more julia> at the start of a line then it is assumed to be a REPL doctest. Semi-colons, ;, at the end of a line works in the same way as in the Julia REPL and will suppress the output, although the line is still evaluated.Note that not all features of the REPL are supported such as shell and help modes.",
"title": "REPL Examples"
},
{
"category": "section",
"location": "man/doctests/#Setup-Code-1",
"page": "Doctests",
"text": "Doctests may require some setup code that must be evaluated prior to that of the actual example, but that should not be displayed in the final documentation. For this purpose a @meta block containing a DocTestSetup = ... value can be used. In the example below, the function foo is defined inside a @meta block. This block will be evaluated at the start of the following doctest blocks:```@meta\nDocTestSetup = quote\n function foo(x)\n return x^2\n end\nend\n```\n\n```jldoctest\njulia> foo(2)\n4\n```\n\n```@meta\nDocTestSetup = nothing\n```The DocTestSetup = nothing is not strictly necessary, but good practice nonetheless to help avoid unintentional definitions in following doctest blocks.Another option is to use the setup keyword argument, which is convenient for short definitions, and for setups needed in inline docstrings.```jldoctest; setup = :(foo(x) = x^2)\njulia> foo(2)\n4\n```note: Note\nThe DocTestSetup and the setup values are re-evaluated at the start of each doctest block and no state is shared between any code blocks. To preserve definitions see Preserving Definitions Between Blocks.note: Note\nIf you rely on setup-code for doctests inside docstrings, included in the document with @docs or @autodocs, the @meta block must be in the markdown file that calls these macros and not within the docstrings themselves, otherwise they will be ignored.",
"title": "Setup Code"
},
{
"category": "section",
"location": "man/doctests/#Skipping-Doctests-1",
"page": "Doctests",
"text": "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.",
"title": "Skipping Doctests"
},
{
"category": "section",
"location": "man/doctests/#\"Script\"-Examples-1",
"page": "Doctests",
"text": "The first, of two, types of doctests is the \"script\" code block. To make Documenter detect this kind of code block the following format must be used:```jldoctest\na = 1\nb = 2\na + b\n\n# output\n\n3\n```The code block's \"language\" must be jldoctest and must include a line containing the text # output. The text before this line is the contents of the script which is run. The text that appears after # output is the textual representation that would be shown in the Julia REPL if the script had been included.The actual output produced by running the \"script\" is compared to the expected result and any difference will result in makedocs throwing an error and terminating.Note that the amount of whitespace appearing above and below the # output line is not significant and can be increased or decreased if desired.It is possible to suppress the output from the doctest by setting the output keyword argument to false, for example```jldoctest; output = false\na = 1\nb = 2\na + b\n\n# output\n\n3\n```Note that the output of the script will still be compared to the expected result, i.e. what is # output section, but the # output section will be suppressed in the rendered documentation.",
"title": "\"Script\" Examples"
},
{
"category": "section",
"location": "man/examples/#Documentation-repositories-1",
"page": "Examples",
"text": "Some projects or organizations maintain dedicated documentation repositories that are separate from specific packages.DifferentialEquations.jl\nJuliaDocs landing page\nJuliaMusic\nPlots.jl",
"title": "Documentation repositories"
},
{
"category": "section",
"location": "man/examples/#Examples-1",
"page": "Examples",
"text": "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: Note\nPackages 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.",
"title": "Examples"
},
{
"category": "section",
"location": "man/examples/#Registered-1",
"page": "Examples",
"text": "Packages that have tagged versions available in METADATA.jl.Augmentor.jl\nBanditOpt.jl\nBeaData.jl\nBio.jl\nControlSystems.jl\nCurrencies.jl\nDiscretePredictors.jl\nDocumenter.jl\nEvolvingGraphs.jl\nExtractMacro.jl\nEzXML.jl\nFourierFlows.jl\nGadfly.jl\nGeoStats.jl\nHighlights.jl\nIntervalConstraintProgramming.jl\nLuxor.jl\nMergedMethods.jl\nMimi.jl\nNumericSuffixes.jl\nNLOptControl.jl\nOhMyREPL.jl\nOnlineStats.jl\nPOMDPs.jl\nPhyloNetworks.jl\nPrivateModules.jl\nQuery.jl\nTaylorSeries.jl\nWeave.jl",
"title": "Registered"
},
{
"category": "section",
"location": "man/guide/#Adding-Some-Docstrings-1",
"page": "Guide",
"text": "Next we'll splice a docstring defined in the Example module into the index.md file. To do this first document a function in that module:module Example\n\nexport func\n\n\"\"\"\n func(x)\n\nReturns double the number `x` plus `1`.\n\"\"\"\nfunc(x) = 2x + 1\n\nendThen in the src/index.md file add the following# Example.jl Documentation\n\n```@docs\nfunc(x)\n```When we next run make.jl the docstring for Example.func(x) should appear in place of the @docs block in build/index.md. Note that more than one object can be referenced inside a @docs block – just place each one on a separate line.Note that a @docs block is evaluated in the Main module. This means that each object listed in the block must be visible there. The module can be changed to something else on a per-page basis with a @meta block as in the following# Example.jl Documentation\n\n```@meta\nCurrentModule = Example\n```\n\n```@docs\nfunc(x)\n```",
"title": "Adding Some Docstrings"
},
{
"category": "section",
"location": "man/guide/#Building-an-Empty-Document-1",
"page": "Guide",
"text": "With our docs/ directory now setup we're going to build our first document. It'll just be a single empty file at the moment, but we'll be adding to it later on.Add the following to your make.jl fileusing Documenter, Example\n\nmakedocs(sitename=\"My Documentation\")This assumes you've installed Documenter as discussed in Installation and that your Example.jl package can be found by Julia.note: Note\nIf your source directory is not accessible through Julia's LOAD_PATH, you might wish to add the following line at the top of make.jlpush!(LOAD_PATH,\"../src/\")Now add an index.md file to the src/ directory.note: Note\nIf you use Documenter's default HTML output the name index.md is mandatory. This file will be the main page of the rendered HTML documentation.Leave the newly added file empty and then run the following command from the docs/ directory$ julia make.jlNote that $ just represents the prompt character. You don't need to type that.If you'd like to see the output from this command in color use$ julia --color=yes make.jlWhen you run that you should see the following outputDocumenter: setting up build directory.\nDocumenter: expanding markdown templates.\nDocumenter: building cross-references.\nDocumenter: running document checks.\n > checking for missing docstrings.\n > running doctests.\n > checking footnote links.\nDocumenter: populating indices.\nDocumenter: rendering document.The docs/ folder should contain a new directory – called build/. It's structure should look like the followingbuild/\n assets/\n arrow.svg\n documenter.css\n documenter.js\n search.js\n index.html\n search/index.html\n search_index.jsnote: Note\nBy default, Documenter has pretty URLs enabled, which means that src/foo.md is turned into src/foo/index.html, instead of simply src/foo.html, which is the preferred way when creating a set of HTML to be hosted on a web server.However, this can be a hindrance when browsing the documentation locally as browsers do not resolve directory URLs like foo/ to foo/index.html for local files. You have two options:You can run a local web server out of the docs/build directory. If you have Python installed, you can simple start one with python3 -m http.server --bind localhost (or python -m SimpleHTTPServer with Python 2).\nYou can disable the pretty URLs feature by passing prettyurls = false with the Documenter.HTML plugin:\nmakedocs(..., format = Documenter.HTML(prettyurls = false))\nAlternatively, if your goal is to eventually set up automatic documentation deployment with Travis CI (see Hosting Documentation), you can also use their environment variables to determine Documenter's behavior in make.jl on the fly:\nmakedocs(...,\n format = Documenter.HTML(\n prettyurls = get(ENV, \"CI\", nothing) == \"true\"\n )\n)warning: Warning\nNever git commit the contents of build (or any other content generated by Documenter) to your repository's master branch. Always commit generated files to the gh-pages branch of your repository. This helps to avoid including unnecessary changes for anyone reviewing commits that happen to include documentation changes.See the Hosting Documentation section for details regarding how you should go about setting this up correctly.At this point build/index.html should be an empty page since src/index.md is empty. You can try adding some text to src/index.md and re-running the make.jl file to see the changes.",
"title": "Building an Empty Document"
},
{
"category": "section",
"location": "man/guide/#Cross-Referencing-1",
"page": "Guide",
"text": "It may be necessary to refer to a particular docstring or section of your document from elsewhere in the document. To do this we can make use of Documenter's cross-referencing syntax which looks pretty similar to normal markdown link syntax. Replace the contents of src/index.md with the following# Example.jl Documentation\n\n```@docs\nfunc(x)\n```\n\n- link to [Example.jl Documentation](@ref)\n- link to [`func(x)`](@ref)So we just have to replace each link's url with @ref and write the name of the thing we'd link to cross-reference. For document headers it's just plain text that matches the name of the header and for docstrings enclose the object in backticks.This also works across different pages in the same way. Note that these sections and docstrings must be unique within a document.",
"title": "Cross Referencing"
},
{
"category": "section",
"location": "man/guide/#Filtering-included-docstrings-1",
"page": "Guide",
"text": "In some cases you may want to include a docstring for a Method that extends a Function from a different module – such as Base. In the following example we extend Base.length with a new definition for the struct T and also add a docstring:struct T\n # ...\nend\n\n\"\"\"\nCustom `length` docs for `T`.\n\"\"\"\nBase.length(::T) = 1When trying to include this docstring with```@docs\nlength\n```all the docs for length will be included – even those from other modules. There are two ways to solve this problem. Either include the type in the signature with```@docs\nlength(::T)\n```or declare the specific modules that makedocs should include withmakedocs(\n # options\n modules = [MyModule]\n)",
"title": "Filtering included docstrings"
},
{
"category": "section",
"location": "man/guide/#Installation-1",
"page": "Guide",
"text": "Documenter can be installed using the Julia package manager. From the Julia REPL, type ] to enter the Pkg REPL mode and runpkg> add Documenter",
"title": "Installation"
},
{
"category": "section",
"location": "man/guide/#Navigation-1",
"page": "Guide",
"text": "Documenter can auto-generate tables of contents and docstring indexes for your document with the following syntax. We'll illustrate these features using our index.md file from the previous sections. Add the following to that file# Example.jl Documentation\n\n```@contents\n```\n\n## Functions\n\n```@docs\nfunc(x)\n```\n\n## Index\n\n```@index\n```The @contents block will generate a nested list of links to all the section headers in the document. By default it will gather all the level 1 and 2 headers from every page in the document, but this can be adjusted using Pages and Depth settings as in the following```@contents\nPages = [\"foo.md\", \"bar.md\"]\nDepth = 3\n```The @index block will generate a flat list of links to all the docs that that have been spliced into the document using @docs blocks. As with the @contents block the pages to be included can be set with a Pages = [...] line. Since the list is not nested Depth is not supported for @index.",
"title": "Navigation"
},
{
"category": "section",
"location": "man/guide/#Package-Guide-1",
"page": "Guide",
"text": "Documenter is designed to do one thing – combine markdown files and inline docstrings from Julia's docsystem into a single inter-linked document. What follows is a step-by-step guide to creating a simple document.",
"title": "Package Guide"
},
{
"category": "section",
"location": "man/guide/#Pages-in-the-Sidebar-1",
"page": "Guide",
"text": "By default all the pages (.md files) in your source directory get added to the sidebar, sorted by their filenames. However, in most cases you want to use the pages argument to makedocs to control how the sidebar looks like. The basic usage is as follows:makedocs(\n ...,\n pages = [\n \"page.md\",\n \"Page title\" => \"page2.md\",\n \"Subsection\" => [\n ...\n ]\n ]\n)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.",
"title": "Pages in the Sidebar"
},
{
"category": "section",
"location": "man/guide/#Setting-up-the-Folder-Structure-1",
"page": "Guide",
"text": "note: Note\nThe function DocumenterTools.generate from the DocumenterTools package can generate the basic structure that Documenter expects.Firstly, we need a Julia module to document. This could be a package generated via PkgDev.generate or a single .jl script accessible via Julia's LOAD_PATH. For this guide we'll be using a package called Example.jl that has the following directory layout:Example/\n src/\n Example.jl\n ...Note that the ... just represent unimportant files and folders.We must decide on a location where we'd like to store the documentation for this package. It's recommended to use a folder named docs/ in the toplevel of the package, like soExample/\n docs/\n ...\n src/\n Example.jl\n ...Inside the docs/ folder we need to add two things. A source folder which will contain the markdown files that will be used to build the finished document and a Julia script that will be used to control the build process. The following names are recommendeddocs/\n src/\n make.jl",
"title": "Setting up the Folder Structure"
},
{
"category": "section",
"location": "man/hosting/#.gitignore-1",
"page": "Hosting Documentation",
"text": "Add the following to your package's .gitignore filedocs/build/These are needed to avoid committing generated content to your repository.",
"title": ".gitignore"
},
{
"category": "section",
"location": "man/hosting/#.travis.yml-Configuration-1",
"page": "Hosting Documentation",
"text": "To tell Travis that we want a new build stage we can add the following to the .travis.yml file:jobs:\n include:\n - stage: \"Documentation\"\n julia: 1.0\n os: linux\n script:\n - julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd()));\n Pkg.instantiate()'\n - julia --project=docs/ docs/make.jl\n after_success: skipwhere the julia: and os: entries decide the worker from which the docs are built and deployed. In the example above we will thus build and deploy the documentation from a linux worker running Julia 1.0. For more information on how to setup a build stage, see the Travis manual for Build Stages.The three lines in the script: section do the following:Instantiate the doc-building environment (i.e. docs/Project.toml, see below).\nInstall your package in the doc-build environment.\nRun the docs/make.jl script, which builds and deploys the documentation.note: Note\nIf your package has a build script you should call Pkg.build(\"PackageName\") after the call to Pkg.develop to make sure the package is built properly.The doc-build environment docs/Project.toml includes Documenter and other doc-build dependencies your package might have. If Documenter is the only dependency, then the Project.toml should include the following:[deps]\nDocumenter = \"e30172f5-a6a5-5a46-863b-614d45cd2de4\"\n\n[compat]\nDocumenter = \"~0.20\"Note that it is recommended that you have a [compat] section, like the one above, in your Project.toml file, which would restrict Documenter's version that gets installed when the build runs. This is to make sure that your builds do not start failing suddenly due to a new major release of Documenter, which may include breaking changes. However, it also means that you will not get updates to Documenter automatically, and hence need to upgrade Documenter's major version yourself.",
"title": ".travis.yml Configuration"
},
{
"category": "section",
"location": "man/hosting/#Documentation-Versions-1",
"page": "Hosting Documentation",
"text": "The documentation is deployed as follows:Documentation built for a tag vX.Y.Z will be stored in a folder vX.Y.Z.\nDocumentation built from the devbranch branch (master by default) is stored a folder determined by the devurl keyword to deploydocs (dev by default).Which versions that will show up in the version selector is determined by the versions argument to deploydocs.Unless a custom domain is being used, the pages are found at:https://USER_NAME.github.io/PACKAGE_NAME.jl/vX.Y.Z\nhttps://USER_NAME.github.io/PACKAGE_NAME.jl/devBy default Documenter will create a link called stable that points to the latest releasehttps://USER_NAME.github.io/PACKAGE_NAME.jl/stableIt is recommended to use this link, rather then the versioned links, since it will be updated with new releases.Once your documentation has been pushed to the gh-pages branch you should add links to your README.md pointing to the stable (and perhaps dev) documentation URLs. It is common practice to make use of \"badges\" similar to those used for Travis and AppVeyor build statuses or code coverage. Adding the following to your package README.md should be all that is necessary:[![](https://img.shields.io/badge/docs-stable-blue.svg)](https://USER_NAME.github.io/PACKAGE_NAME.jl/stable)\n[![](https://img.shields.io/badge/docs-dev-blue.svg)](https://USER_NAME.github.io/PACKAGE_NAME.jl/dev)PACKAGE_NAME and USER_NAME should be replaced with their appropriate values. The colour and text of the image can be changed by altering docs-stable-blue as described on shields.io, though it is recommended that package authors follow this standard to make it easier for potential users to find documentation links across multiple package README files.Final RemarksThat should be all that is needed to enable automatic documentation building. Pushing new commits to your master branch should trigger doc builds. Note that other branches do not trigger these builds and neither do pull requests by potential contributors.If you would like to see a more complete example of how this process is setup then take a look at this package's repository for some inspiration.",
"title": "Documentation Versions"
},
{
"category": "section",
"location": "man/hosting/#Hosting-Documentation-1",
"page": "Hosting Documentation",
"text": "After going through the Package Guide and Doctests page you will need to host the generated documentation somewhere for potential users to read. This guide will describe how to setup automatic updates for your package docs using the Travis build service and GitHub Pages. This is the same approach used by this package to host its own docs – the docs you're currently reading.note: Note\nFollowing this guide should be the final step you take after you are comfortable with the syntax and build process used by Documenter.jl. It is recommended that you only proceed with the steps outlined here once you have successfully managed to build your documentation locally with Documenter.This guide assumes that you already have GitHub and Travis accounts setup. If not then go set those up first and then return here.",
"title": "Hosting Documentation"
},
{
"category": "section",
"location": "man/hosting/#Overview-1",
"page": "Hosting Documentation",
"text": "Once set up correctly, the following will happen each time you push new updates to your package repository:Travis buildbots will start up and run your package tests in a \"Test\" stage.\nAfter the Test stage completes, a single bot will run a new \"Documentation\" stage, which will build the documentation.\nIf the documentation is built successfully, the bot will attempt to push the generated HTML pages back to GitHub.Note that the hosted documentation does not update when you make pull requests; you see updates only when you merge to master or push new tags.The following sections outline how to enable this for your own package.",
"title": "Overview"
},
{
"category": "section",
"location": "man/hosting/#SSH-Deploy-Keys-1",
"page": "Hosting Documentation",
"text": "Deploy keys provide push access to a single repository, to allow secure deployment of generated documentation from Travis to GitHub. The SSH keys can be generated with the Travis.genkeys from the DocumenterTools package.note: Note\nYou will need several command line programs (which, git and ssh-keygen) to be installed for the following steps to work. If DocumenterTools fails, please see the the SSH Deploy Keys Walkthrough section for instruction on how to generate the keys manually (including in Windows).Install and load DocumenterTools withpkg> add DocumenterToolsjulia> using DocumenterToolsThen call the Travis.genkeys function as follows:julia> using MyPackage\njulia> Travis.genkeys(user=\"MyUser\", repo=\"git@github.com:MyUser/MyPackage.jl.git\")where MyPackage is the name of the package you would like to create deploy keys for and MyUser is your GitHub username. Note that the keyword arguments are optional and can be omitted.If the package is checked out in development mode with ] dev MyPackage, you can also use Travis.genkeys as follows:julia> using MyPackage\njulia> Travis.genkeys(MyPackage)where MyPackage is the package you would like to create deploy keys for. The output will look similar to the text below:INFO: add the public key below to https://github.com/USER/REPO/settings/keys\n with read/write access:\n\n[SSH PUBLIC KEY HERE]\n\nINFO: add a secure environment variable named 'DOCUMENTER_KEY' to\n https://travis-ci.org/USER/REPO/settings with value:\n\n[LONG BASE64 ENCODED PRIVATE KEY]Follow the instructions that are printed out, namely:Add the public ssh key to your settings page for the GitHub repository that you are setting up by following the .../settings/key link provided. Click on Add deploy key, enter the name documenter as the title, and copy the public key into the Key field. Check Allow write access to allow Documenter to commit the generated documentation to the repo.\nNext add the long private key to the Travis settings page using the provided link. Again note that you should include no whitespace when copying the key. In the Environment Variables section add a key with the name DOCUMENTER_KEY and the value that was printed out. Do not set the variable to be displayed in the build log. Then click Add.\nwarning: Security warning\nTo 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.note: Note\nThere are more explicit instructions for adding the keys to GitHub and Travis in the SSH Deploy Keys Walkthrough section of the manual.",
"title": "SSH Deploy Keys"
},
{
"category": "section",
"location": "man/hosting/#The-deploydocs-Function-1",
"page": "Hosting Documentation",
"text": "At the moment your docs/make.jl file probably only containsusing Documenter, PACKAGE_NAME\n\nmakedocs()We'll need to add an additional function call to this file after makedocs which would perform the deployment of the docs to the gh-pages branch. Add the following at the end of the file:deploydocs(\n repo = \"github.com/USER_NAME/PACKAGE_NAME.jl.git\",\n)where USER_NAME and PACKAGE_NAME must be set to the appropriate names. Note that repo should not specify any protocol, i.e. it should not begin with https:// or git@.See the deploydocs function documentation for more details.",
"title": "The deploydocs Function"
},
{
"category": "section",
"location": "man/hosting/#gh-pages-Branch-1",
"page": "Hosting Documentation",
"text": "By default, Documenter pushes documentation to the gh-pages branch. If the branch does not exist it will be created automatically by deploydocs. If does exist then Documenter simply adds an additional commit with the built documentation. You should be aware that Documenter may overwrite existing content without warning.If you wish to create the gh-pages branch manually the that can be done following these instructions.",
"title": "gh-pages Branch"
},
{
"category": "section",
"location": "man/hosting/walkthrough/#Adding-the-Private-Key-to-Travis-1",
"page": "SSH Deploy Keys Walkthrough",
"text": "In this section, we explain how to upload a private SSH key to Travis. By this point, you should have generated a private key and saved it to a file. If you haven't done this, go read Generating an SSH Key.First, we need to Base64 encode the private key. Open Julia, and run the commandjulia> read(\"path/to/private/key\", String) |> Documenter.base64encode |> printlnCopy the resulting output.Next, go to https://travis-ci.org/[YOUR_USER_NAME]/[YOUR_REPO_NAME]/settings. Scroll down to the \"Environment Variables\" section. It should look like this:(Image: )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, check that the \"Display value in build log\" is switched off and then click \"Add\". Congratulations! You've added the private key to Travis.warning: Security warning\nTo 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 RemarksYou should now be able to continue on with the Hosting Documentation.",
"title": "Adding the Private Key to Travis"
},
{
"category": "section",
"location": "man/hosting/walkthrough/#Adding-the-Public-Key-to-GitHub-1",
"page": "SSH Deploy Keys Walkthrough",
"text": "In this section, we explain how to upload a public SSH key to GitHub. By this point, you should have generated a public key and saved it to a file. If you haven't done this, go read Generating an SSH Key.Go to https://github.com/[YOUR_USER_NAME]/[YOUR_REPO_NAME]/settings/keys and click \"Add deploy key\". You should get to a page that looks like:(Image: )Now we need to fill in three pieces of information.Have \"Title\" be e.g. \"Documenter\".\nCopy and paste the public key that we generated in the Generating an SSH Key step into the \"Key\" field.\nMake sure that the \"Allow write access\" box is checked.Once you're done, click \"Add key\". Congratulations! You've added the public key to GitHub. The next step is to add the private key to Travis.",
"title": "Adding the Public Key to GitHub"
},
{
"category": "section",
"location": "man/hosting/walkthrough/#Generating-an-SSH-Key-1",
"page": "SSH Deploy Keys Walkthrough",
"text": "The first step is to generate an SSH key. An SSH key is made up of two components: a public key, which can be shared publicly, and a private key, which you should ensure is never shared publicly.The public key usually looks something like thisssh-rsa [base64-encoded-key] [optional-comment]And the private key usually look something like this-----BEGIN RSA PRIVATE KEY-----\n ... base64-encoded key over several lines ...\n-----END RSA PRIVATE KEY-----",
"title": "Generating an SSH Key"
},
{
"category": "section",
"location": "man/hosting/walkthrough/#If-you-do-not-have-ssh-keygen-1",
"page": "SSH Deploy Keys Walkthrough",
"text": "If you're using Windows, you probably don't have ssh-keygen installed. Instead, we're going to use a program called PuTTY. The first step in the process to generate a new SSH key is to download PuTTY:Download and install PuTTYPuTTY is actually a collection of a few different programs. We need to use PuTTYgen. Open it, and you should get a window that looks like:(Image: )Now we need to generate a key.Click the \"Generate\" button, then follow the instructions and move the mouse around to create randomness.Once you've moved the mouse enough, the window should look like:(Image: )Now we need to save the public key somewhere.Copy the text in the box titled \"Public key for pasting into OpenSSH authorized_keys file\" and paste it somewhere for later. This is your public key and is required for the step Adding the Public Key to GitHubFinally, we need to save the private key somewhere.Click the \"Conversions\" tab, and then click \"Export OpenSSH key\". Save that file somewhere. That file is your private key and is required for the Adding the Private Key to Travis step.\n(Image: )\nnote: Note\nDon't save your key via the \"Save private key\" button as this will save the key in the wrong format.If you made it this far, congratulations! You now have the private and public keys needed to set up automatic deployment of your documentation. The next steps are to add the keys to GitHub and Travis.",
"title": "If you do not have ssh-keygen"
},
{
"category": "section",
"location": "man/hosting/walkthrough/#If-you-have-ssh-keygen-installed-1",
"page": "SSH Deploy Keys Walkthrough",
"text": "If you have ssh-keygen installed, but Travis.genkeys() didn't work, you can generate an SSH key as follows. First, generate a key using ssh-keygen and save it to the file privatekey:shell> ssh-keygen -N \"\" -f privatekeyNext, we need to encode the private key in Base64. Run the following command:julia> read(\"privatekey\", String) |> base64encode |> printlnCopy and paste the output somewhere. This is your private key and is required for the step Adding the Private Key to Travis.Now we need to get the public key. Run the following command:julia> read(\"privatekey.pub\", String) |> printlnCopy and paste the output somewhere. This is your public key and is required for the step Adding the Public Key to GitHub.",
"title": "If you have ssh-keygen installed"
},
{
"category": "section",
"location": "man/hosting/walkthrough/#SSH-Deploy-Keys-Walkthrough-1",
"page": "SSH Deploy Keys Walkthrough",
"text": "If the instructions in SSH Deploy Keys did not work for you (for example, ssh-keygen is not installed), don't worry! This walkthrough will guide you through the process. There are three main steps:Generating an SSH Key\nAdding the Public Key to GitHub\nAdding the Private Key to Travis",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "section",
"location": "man/latex/#Display-Equations-1",
"page": "LaTeX Syntax",
"text": "Here's an equation:\n\n```math\n\\frac{n!}{k!(n - k)!} = \\binom{n}{k}\n```\n\nThis is the binomial coefficient.which will be displayed asHere's an equation:fracnk(n - k) = binomnkThis is the binomial coefficient.",
"title": "Display Equations"
},
{
"category": "section",
"location": "man/latex/#Escaping-Characters-in-Docstrings-1",
"page": "LaTeX Syntax",
"text": "Since some characters used in LaTeX syntax, such as $ and \\, are treated differently in docstrings. They need to be escaped using a \\ character as in the following example:\"\"\"\nHere's some inline maths: ``\\\\sqrt[n]{1 + x + x^2 + \\\\ldots}``.\n\nHere's an equation:\n\n``\\\\frac{n!}{k!(n - k)!} = \\\\binom{n}{k}``\n\nThis is the binomial coefficient.\n\"\"\"\nfunc(x) = # ...To avoid needing to escape the special characters the raw\"\" string macro can be used, combined with @doc:@doc raw\"\"\"\nHere's some inline maths: ``\\sqrt[n]{1 + x + x^2 + \\ldots}``.\n\nHere's an equation:\n\n``\\frac{n!}{k!(n - k)!} = \\binom{n}{k}``\n\nThis is the binomial coefficient.\n\"\"\"\nfunc(x) = # ...A related issue is how to add dollar signs to a docstring. They need to be double-escaped as follows:\"\"\"\nThe cost was \\\\\\$1.\n\"\"\"",
"title": "Escaping Characters in Docstrings"
},
{
"category": "section",
"location": "man/latex/#Inline-Equations-1",
"page": "LaTeX Syntax",
"text": "Here's some inline maths: ``\\sqrt[n]{1 + x + x^2 + \\ldots}``.which will be displayed asHere's some inline maths: sqrtn1 + x + x^2 + ldots.",
"title": "Inline Equations"
},
{
"category": "section",
"location": "man/latex/#latex_syntax-1",
"page": "LaTeX Syntax",
"text": "The following section describes how to add equations written using LaTeX to your documentation.",
"title": "LaTeX Syntax"
},
{
"category": "section",
"location": "man/other-formats/#Compiling-using-docker-image-1",
"page": "Other Output Formats",
"text": "It is also possible to use a prebuilt docker image to compile the .tex file. The image contains all of the required installs described in the section above. The only requirement for using the image is that docker is installed and available for the builder to call. You also need to tell Documenter to use the docker image, instead of natively installed tex which is the default. This is done with the LaTeX specifier:using DocumenterLaTeX\nmakedocs(\n format = LaTeX(platform = \"docker\"),\n ...\n)If you build the documentation on Travis you need to addservices:\n - dockerto your .travis.yml file.",
"title": "Compiling using docker image"
},
{
"category": "section",
"location": "man/other-formats/#Compiling-using-natively-installed-latex-1",
"page": "Other Output Formats",
"text": "The following is required to build the documentation:You need pdflatex command to be installed and available to Documenter.\nYou need the minted LaTeX package and its backend source highlighter Pygments installed.\nYou need the Lato and Roboto Mono fonts installed.",
"title": "Compiling using natively installed latex"
},
{
"category": "section",
"location": "man/other-formats/#Deployment-with-MkDocs-1",
"page": "Other Output Formats",
"text": "To deploy MkDocs on Travis, you also need to provide additional keyword arguments to deploydocs. Your deploydocs call should look something likedeploydocs(\n repo = \"github.com/USER_NAME/PACKAGE_NAME.jl.git\",\n deps = Deps.pip(\"mkdocs\", \"pygments\", \"python-markdown-math\"),\n make = () -> run(`mkdocs build`)\n target = \"site\"\n)deps serves to provide the required Python dependencies to build the documentation\nmake specifies the function that calls mkdocs to perform the second build step\ntarget, which specified which files get copied to gh-pages, needs to point to the site/ directoryIn the example above we include the dependencies mkdocs and python-markdown-math. The former makes sure that MkDocs is installed to deploy the documentation, and the latter provides the mdx_math markdown extension to exploit MathJax rendering of latex equations in markdown. Other dependencies should be included here.",
"title": "Deployment with MkDocs"
},
{
"category": "section",
"location": "man/other-formats/#Markdown-and-MkDocs-1",
"page": "Other Output Formats",
"text": "Markdown output requires the DocumenterMarkdown package to be available and loaded. For Travis setups, add the package to the docs/Project.toml environment as a dependency. You also need to import the package in make.jl:using DocumenterMarkdownWhen DocumenterMarkdown is loaded, you can specify format = Markdown() in makedocs. Documenter will then output a set of Markdown files to the build directory that can then further be processed with MkDocs into HTML pages.MkDocs, of course, is not the only option you have – any markdown to HTML converter should work fine with some amount of setting up.note: Note\nMarkdown output used to be the default option (i.e. when leaving the format option unspecified). The default now is the HTML output.",
"title": "Markdown & MkDocs"
},
{
"category": "section",
"location": "man/other-formats/#Other-Output-Formats-1",
"page": "Other Output Formats",
"text": "In addition to the default native HTML output, plugin packages enable Documenter to generate output in other formats. Once the corresponding package is loaded, the output format can be specified using the format option in makedocs.",
"title": "Other Output Formats"
},
{
"category": "section",
"location": "man/other-formats/#PDF-Output-via-LaTeX-1",
"page": "Other Output Formats",
"text": "LaTeX/PDF output requires the DocumenterLaTeX package to be available and loaded in make.jl withusing DocumenterLaTeXWhen DocumenterLaTeX is loaded, you can set format = LaTeX() in makedocs, and Documenter will generate a PDF version of the documentation using LaTeX. The makedocs argument sitename will be used for the \\\\title field in the tex document, and if the build is for a release tag (i.e. when the \"TRAVIS_TAG\" environment variable is set) the version number will be appended to the title. The makedocs argument authors should also be specified, it will be used for the \\\\authors field in the tex document.",
"title": "PDF Output via LaTeX"
},
{
"category": "section",
"location": "man/other-formats/#The-MkDocs-mkdocs.yml-file-1",
"page": "Other Output Formats",
"text": "A MkDocs build is controlled by the mkdocs.yml configuration file. Add the file with the following content to the docs/ directory:site_name: PACKAGE_NAME.jl\nrepo_url: https://github.com/USER_NAME/PACKAGE_NAME.jl\nsite_description: Description...\nsite_author: USER_NAME\n\ntheme: readthedocs\n\nextra_css:\n - assets/Documenter.css\n\nextra_javascript:\n - https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS_HTML\n - assets/mathjaxhelper.js\n\nmarkdown_extensions:\n - extra\n - tables\n - fenced_code\n - mdx_math\n\ndocs_dir: 'build'\n\npages:\n - Home: index.mdIf you have run Documenter and it has generated a build/ directory, you can now try running mkdocs build – this should now generate the site/ directory. You should also add the docs/site/ directory into your .gitignore file, which should now look like:docs/build/\ndocs/site/This is only a basic skeleton. Read through the MkDocs documentation if you would like to know more about the available settings.",
"title": "The MkDocs mkdocs.yml file"
},
{
"category": "section",
"location": "man/other-formats/#\\LaTeX:-MkDocs-and-MathJax-1",
"page": "Other Output Formats",
"text": "To get MkDocs to display LaTeX equations correctly we need to update several of this configuration files described in the Package Guide.docs/make.jl should add the python-markdown-math dependency to allow for equations to be rendered correctly.# ...\n\ndeploydocs(\n deps = Deps.pip(\"pygments\", \"mkdocs\", \"python-markdown-math\"),\n # ...\n)This package should also be installed locally so that you can preview the generated documentation prior to pushing new commits to a repository.$ pip install python-markdown-mathThe docs/mkdocs.yml file must add the python-markdown-math extension, called mdx_math, as well as two MathJax JavaScript files:# ...\nmarkdown_extensions:\n - mdx_math\n # ...\n\nextra_javascript:\n - https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS_HTML\n - assets/mathjaxhelper.js\n# ...Final RemarksFollowing this guide and adding the necessary changes to the configuration files should enable properly rendered mathematical equations within your documentation both locally and when built and deployed using the Travis built service.",
"title": "LaTeX: MkDocs and MathJax"
},
{
"category": "section",
"location": "man/syntax/#@autodocs-block-1",
"page": "Syntax",
"text": "Automatically splices all docstrings from the provided modules in place of the code block. This is equivalent to manually adding all the docstrings in a @docs block.```@autodocs\nModules = [Foo, Bar]\nOrder = [:function, :type]\n```The above @autodocs block adds all the docstrings found in modules Foo and Bar that refer to functions or types to the document.Each module is added in order and so all docs from Foo will appear before those of Bar. Possible values for the Order vector are:module\n:constant\n:type\n:function\n:macroIf no Order is provided then the order listed above is used.When a potential docstring is found in one of the listed modules, but does not match any value from Order then it will be omitted from the document. Hence Order acts as a basic filter as well as sorter.In addition to Order, a Pages vector may be included in @autodocs to filter docstrings based on the source file in which they are defined:```@autodocs\nModules = [Foo]\nPages = [\"a.jl\", \"b.jl\"]\n```In the above example docstrings from module Foo found in source files that end in a.jl and b.jl are included. The page order provided by Pages is also used to sort the docstrings. Note that page matching is done using the end of the provided strings and so a.jl will be matched by any source file that ends in a.jl, i.e. src/a.jl or src/foo/a.jl.To filter out certain docstrings by your own criteria, you can provide function with them Filter keyword:```@autodocs\nModules = [Foo]\nFilter = t -> typeof(t) === DataType && t <: Foo.C\n```In the given example, only the docstrings of the subtypes of Foo.C are shown. Instead of an anonymous function you can give the name of a function you defined beforehand, too:```@autodocs\nModules = [Foo]\nFilter = myCustomFilterFunction\n```To include only the exported names from the modules listed in Modules use Private = false. In a similar way Public = false can be used to only show the unexported names. By default both of these are set to true so that all names will be shown.Functions exported from `Foo`:\n\n```@autodocs\nModules = [Foo]\nPrivate = false\nOrder = [:function]\n```\n\nPrivate types in module `Foo`:\n\n```@autodocs\nModules = [Foo]\nPublic = false\nOrder = [:type]\n```note: Note\nWhen more complex sorting is needed then use @docs to define it explicitly.",
"title": "@autodocs block"
},
{
"category": "section",
"location": "man/syntax/#@contents-block-1",
"page": "Syntax",
"text": "Generates a nested list of links to document sections. Valid settings are Pages and Depth.```@contents\nPages = [\"foo.md\"]\nDepth = 5\n```As with @index if Pages is not provided then all pages are included. The default Depth value is 2.",
"title": "@contents block"
},
{
"category": "section",
"location": "man/syntax/#@docs-block-1",
"page": "Syntax",
"text": "Splice one or more docstrings into a document in place of the code block, i.e.```@docs\nDocumenter\nmakedocs\ndeploydocs\n```This block type is evaluated within the CurrentModule module if defined, otherwise within Main, and so each object listed in the block should be visible from that module. Undefined objects will raise warnings during documentation generation and cause the code block to be rendered in the final document unchanged.Objects may not be listed more than once within the document. When duplicate objects are detected an error will be raised and the build process will be terminated.To ensure that all docstrings from a module are included in the final document the modules keyword for makedocs can be set to the desired module or modules, i.e.makedocs(\n modules = [Documenter],\n)which will cause any unlisted docstrings to raise warnings when makedocs is called. If modules is not defined then no warnings are printed, even if a document has missing docstrings.",
"title": "@docs block"
},
{
"category": "section",
"location": "man/syntax/#@eval-block-1",
"page": "Syntax",
"text": "Evaluates the contents of the block and inserts the resulting value into the final document.In the following example we use the PyPlot package to generate a plot and display it in the final document.```@eval\nusing PyPlot\n\nx = linspace(-π, π)\ny = sin(x)\n\nplot(x, y, color = \"red\")\nsavefig(\"plot.svg\")\n\nnothing\n```\n\n![](plot.svg)Another example is to generate markdown tables from machine readable data formats such as CSV or JSON.```@eval\nusing CSV\nusing Latexify\ndf = CSV.read(\"table.csv\")\nmdtable(df,latex=false)\n```Which will generate a markdown version of the CSV file table.csv and render it in the output format.Note that each @eval block evaluates its contents within a separate module. When evaluating each block the present working directory, pwd, is set to the directory in build where the file will be written to, and the paths in include calls are interpreted to be relative to pwd.Also, instead of returning nothing in the example above we could have returned a new Markdown.MD object through Markdown.parse. This can be more appropriate when the filename is not known until evaluation of the block itself.note: Note\nIn most cases @example is preferred over @eval. Just like in normal Julia code where eval should be only be considered as a last resort, @eval should be treated in the same way.",
"title": "@eval block"
},
{
"category": "section",
"location": "man/syntax/#@example-block-1",
"page": "Syntax",
"text": "Evaluates the code block and inserts the result into the final document along with the original source code.```@example\na = 1\nb = 2\na + b\n```The above @example block will splice the following into the final document```julia\na = 1\nb = 2\na + b\n```\n\n```\n3\n```Leading and trailing newlines are removed from the rendered code blocks. Trailing whitespace on each line is also removed.note: Note\nThe working directory, pwd, is set to the directory in build where the file will be written to, and the paths in include calls are interpreted to be relative to pwd.Hiding Source CodeCode blocks may have some content that does not need to be displayed in the final document. # hide comments can be appended to lines that should not be rendered, i.e.```@example\nimport Random # hide\nRandom.seed!(1) # hide\nA = rand(3, 3)\nb = [1, 2, 3]\nA \\ b\n```Note that appending # hide to every line in an @example block will result in the block being hidden in the rendered document. The results block will still be rendered though. @setup blocks are a convenient shorthand for hiding an entire block, including the output.stdout and stderrThe Julia output streams are redirected to the results block when evaluating @example blocks in the same way as when running doctest code blocks.nothing ResultsWhen the @example block evaluates to nothing then the second block is not displayed. Only the source code block will be shown in the rendered document. Note that if any output from either stdout or stderr is captured then the results block will be displayed even if nothing is returned.Named @example BlocksBy default @example blocks are run in their own anonymous Modules to avoid side-effects between blocks. To share the same module between different blocks on a page the @example can be named with the following syntax```@example 1\na = 1\n```\n\n```@example 1\nprintln(a)\n```The name can be any text, not just integers as in the example above, i.e. @example foo.Named @example blocks can be useful when generating documentation that requires intermediate explanation or multimedia such as plots as illustrated in the following exampleFirst we define some functions\n\n```@example 1\nusing PyPlot # hide\nf(x) = sin(2x) + 1\ng(x) = cos(x) - x\n```\n\nand then we plot `f` over the interval from ``-π`` to ``π``\n\n```@example 1\nx = linspace(-π, π)\nplot(x, f(x), color = \"red\")\nsavefig(\"f-plot.svg\"); nothing # hide\n```\n\n![](f-plot.svg)\n\nand then we do the same with `g`\n\n```@example 1\nplot(x, g(x), color = \"blue\")\nsavefig(\"g-plot.svg\"); nothing # hide\n```\n\n![](g-plot.svg)Note that @example blocks are evaluated within the directory of build where the file will be rendered . This means than in the above example savefig will output the .svg files into that directory. This allows the images to be easily referenced without needing to worry about relative paths.@example blocks automatically define ans which, as in the Julia REPL, is bound to the value of the last evaluated expression. This can be useful in situations such as the following one where where binding the object returned by plot to a named variable would look out of place in the final rendered documentation:```@example\nusing Gadfly # hide\nplot([sin, x -> 2sin(x) + x], -2π, 2π)\ndraw(SVG(\"plot.svg\", 6inch, 4inch), ans); nothing # hide\n```\n\n![](plot.svg)Delayed Execution of @example Blocks@example blocks accept a keyword argument continued which can be set to true or false (defaults to false). When continued = true the execution of the code is delayed until the next continued = false @example-block. This is needed for example when the expression in a block is not complete. Example:```@example half-loop; continued = true\nfor i in 1:3\n j = i^2\n```\nSome text explaining what we should do with `j`\n```@example half-loop\n println(j)\nend\n```Here the first block is not complete – the loop is missing the end. Thus, by setting continued = true here we delay the evaluation of the first block, until we reach the second block. A block with continued = true does not have any output.",
"title": "@example block"
},
{
"category": "section",
"location": "man/syntax/#@index-block-1",
"page": "Syntax",
"text": "Generates a list of links to docstrings that have been spliced into a document. Valid settings are Pages, Modules, and Order. For example:```@index\nPages = [\"foo.md\"]\nModules = [Foo, Bar]\nOrder = [:function, :type]\n```When Pages or Modules are not provided then all pages or modules are included. Order defaults to[:module, :constant, :type, :function, :macro]if not specified. Order and Modules behave the same way as in @autodocs blocks and filter out docstrings that do not match one of the modules or categories specified.Note that the values assigned to Pages, Modules, and Order may be any valid Julia code and thus can be something more complex that an array literal if required, i.e.```@index\nPages = map(file -> joinpath(\"man\", file), readdir(\"man\"))\n```It should be noted though that in this case Pages may not be sorted in the order that is expected by the user. Try to stick to array literals as much as possible.",
"title": "@index block"
},
{
"category": "section",
"location": "man/syntax/#@meta-block-1",
"page": "Syntax",
"text": "This block type is used to define metadata key/value pairs that can be used elsewhere in the page. Currently recognised keys:CurrentModule: module where Documenter evaluates, for example, @docs-block and @ref-links.\nDocTestSetup: code to be evaluated before a doctest, see the Setup Code section under Doctests.\nDocTestFilters: filters to deal with, for example, unpredictable output from doctests, see the Filtering Doctests section under Doctests.\nEditURL: link to where the page can be edited. This defaults to the .md page itself, but if the source is something else (for example if the .md page is generated as part of the doc build) this can be set, either as a local link, or an absolute url.Example:```@meta\nCurrentModule = FooBar\nDocTestSetup = quote\n using MyPackage\nend\nDocTestFilters = [r\"Stacktrace:[\\s\\S]+\"]\nEditURL = \"link/to/source/file\"\n```Note that @meta blocks are always evaluated in Main.",
"title": "@meta block"
},
{
"category": "section",
"location": "man/syntax/#@raw-format-block-1",
"page": "Syntax",
"text": "Allows code to be inserted into the final document verbatim. E.g. to insert custom HTML or LaTeX code into the output.The format argument is mandatory and Documenter uses it to determine whether a particular block should be copied over to the output or not. Currently supported formats are html and latex, used by the respective writers. A @raw block whose format is not recognized is usually ignored, so it is possible to have a raw block for each output format without the blocks being duplicated in the output.The following example shows how SVG code with custom styling can be included into documents using the @raw block.",
"title": "@raw <format> block"
},
{
"category": "section",
"location": "man/syntax/#@ref-link-1",
"page": "Syntax",
"text": "Used in markdown links as the URL to tell Documenter to generate a cross-reference automatically. The text part of the link can be a docstring, header name, or GitHub PR/Issue number.# Syntax\n\n... [`makedocs`](@ref) ...\n\n# Functions\n\n```@docs\nmakedocs\n```\n\n... [Syntax](@ref) ...\n\n... [#42](@ref) ...Plain text in the \"text\" part of a link will either cross-reference a header, or, when it is a number preceded by a #, a GitHub issue/pull request. Text wrapped in backticks will cross-reference a docstring from a @docs block.@refs may refer to docstrings or headers on different pages as well as the current page using the same syntax.Note that depending on what the CurrentModule is set to, a docstring @ref may need to be prefixed by the module which defines it.",
"title": "@ref link"
},
{
"category": "section",
"location": "man/syntax/#@repl-block-1",
"page": "Syntax",
"text": "These are similar to @example blocks, but adds a julia> prompt before each toplevel expression. ; and # hide syntax may be used in @repl blocks in the same way as in the Julia REPL and @example blocks.```@repl\na = 1\nb = 2\na + b\n```will generate```julia\njulia> a = 1\n1\n\njulia> b = 2\n2\n\njulia> a + b\n3\n```Named @repl <name> blocks behave in the same way as named @example <name> blocks.note: Note\nThe working directory, pwd, is set to the directory in build where the file will be written to, and the paths in include calls are interpreted to be relative to pwd.",
"title": "@repl block"
},
{
"category": "section",
"location": "man/syntax/#@setup-name-block-1",
"page": "Syntax",
"text": "These are similar to @example blocks, but both the input and output are hidden from the final document. This can be convenient if there are several lines of setup code that need to be hidden.note: Note\nUnlike @example and @repl blocks, @setup requires a <name> attribute to associate it with downstream @example <name> and @repl <name> blocks.```@setup abc\nusing RDatasets\nusing DataFrames\niris = dataset(\"datasets\", \"iris\")\n```\n\n```@example abc\nprintln(iris)\n```",
"title": "@setup <name> block"
},
{
"category": "section",
"location": "man/syntax/#Duplicate-Headers-1",
"page": "Syntax",
"text": "In some cases a document may contain multiple headers with the same name, but on different pages or of different levels. To allow @ref to cross-reference a duplicate header it must be given a name as in the following example# [Header](@id my_custom_header_name)\n\n...\n\n## Header\n\n... [Custom Header](@ref my_custom_header_name) ...The link that wraps the named header is removed in the final document. The text for a named @ref ... does not need to match the header that it references. Named @ref ...s may refer to headers on different pages in the same way as unnamed ones do.Duplicate docstring references do not occur since splicing the same docstring into a document more than once is disallowed.",
"title": "Duplicate Headers"
},
{
"category": "section",
"location": "man/syntax/#Named-doc-@refs-1",
"page": "Syntax",
"text": "Docstring @refs can also be \"named\" in a similar way to headers as shown in the Duplicate Headers section above. For examplemodule Mod\n\n\"\"\"\nBoth of the following references point to `g` found in module `Main.Other`:\n\n * [`Main.Other.g`](@ref)\n * [`g`](@ref Main.Other.g)\n\n\"\"\"\nf(args...) = # ...\n\nendThis can be useful to avoid having to write fully qualified names for references that are not imported into the current module, or when the text displayed in the link is used to add additional meaning to the surrounding text, such asUse [`for i = 1:10 ...`](@ref for) to loop over all the numbers from 1 to 10.note: Note\nNamed doc @refs should be used sparingly since writing unqualified names may, in some cases, make it difficult to tell which function is being referred to in a particular docstring if there happen to be several modules that provide definitions with the same name.",
"title": "Named doc @refs"
},
{
"category": "section",
"location": "man/syntax/#Syntax-1",
"page": "Syntax",
"text": "This section of the manual describes the syntax used by Documenter to build documentation.Pages = [\"syntax.md\"]",
"title": "Syntax"
},
{
"category": "type",
"location": "lib/internals/anchors/#Documenter.Anchors.Anchor",
"page": "Anchors",
"text": "Stores an arbitrary object called .object and it's location within a document.\n\nFields\n\nobject – the stored object.\norder – ordering of object within the entire document.\nfile – the destination file, in build, where the object will be written to.\nid – the generated \"slug\" identifying the object.\nnth – integer that unique-ifies anchors with the same id.\n\n\n\n\n\n",
"title": "Documenter.Anchors.Anchor"
},
{
"category": "type",
"location": "lib/internals/anchors/#Documenter.Anchors.AnchorMap",
"page": "Anchors",
"text": "Tree structure representating anchors in a document and their relationships with eachother.\n\nObject Hierarchy\n\nid -> file -> anchors\n\nEach id maps to a file which in turn maps to a vector of Anchor objects.\n\n\n\n\n\n",
"title": "Documenter.Anchors.AnchorMap"
},
{
"category": "type",
"location": "lib/internals/builder/#Documenter.Builder.CheckDocument",
"page": "Builder",
"text": "Checks that all documented objects are included in the document and runs doctests on all valid Julia code blocks.\n\n\n\n\n\n",
"title": "Documenter.Builder.CheckDocument"
},
{
"category": "type",
"location": "lib/internals/builder/#Documenter.Builder.CrossReferences",
"page": "Builder",
"text": "Finds and sets URLs for each @ref link in the document to the correct destinations.\n\n\n\n\n\n",
"title": "Documenter.Builder.CrossReferences"
},
{
"category": "type",
"location": "lib/internals/builder/#Documenter.Builder.DocumentPipeline",
"page": "Builder",
"text": "The default document processing \"pipeline\", which consists of the following actions:\n\nSetupBuildDirectory\nExpandTemplates\nCrossReferences\nCheckDocument\nPopulate\nRenderDocument\n\n\n\n\n\n",
"title": "Documenter.Builder.DocumentPipeline"
},
{
"category": "type",
"location": "lib/internals/builder/#Documenter.Builder.ExpandTemplates",
"page": "Builder",
"text": "Executes a sequence of actions on each node of the parsed markdown files in turn.\n\n\n\n\n\n",
"title": "Documenter.Builder.ExpandTemplates"
},
{
"category": "type",
"location": "lib/internals/builder/#Documenter.Builder.Populate",
"page": "Builder",
"text": "Populates the ContentsNodes and IndexNodes with links.\n\n\n\n\n\n",
"title": "Documenter.Builder.Populate"
},
{
"category": "type",
"location": "lib/internals/builder/#Documenter.Builder.RenderDocument",
"page": "Builder",
"text": "Writes the document tree to the build directory.\n\n\n\n\n\n",
"title": "Documenter.Builder.RenderDocument"
},
{
"category": "type",
"location": "lib/internals/builder/#Documenter.Builder.SetupBuildDirectory",
"page": "Builder",
"text": "Creates the correct directory layout within the build folder and parses markdown files.\n\n\n\n\n\n",
"title": "Documenter.Builder.SetupBuildDirectory"
},
{
"category": "type",
"location": "lib/internals/documents/#Documenter.Documents.Document",
"page": "Documents",
"text": "Represents an entire document.\n\n\n\n\n\n",
"title": "Documenter.Documents.Document"
},
{
"category": "type",
"location": "lib/internals/documents/#Documenter.Documents.Globals",
"page": "Documents",
"text": "Page-local values such as current module that are shared between nodes in a page.\n\n\n\n\n\n",
"title": "Documenter.Documents.Globals"
},
{
"category": "type",
"location": "lib/internals/documents/#Documenter.Documents.Internal",
"page": "Documents",
"text": "Private state used to control the generation process.\n\n\n\n\n\n",
"title": "Documenter.Documents.Internal"
},
{
"category": "type",
"location": "lib/internals/documents/#Documenter.Documents.NavNode",
"page": "Documents",
"text": "Element in the navigation tree of a document, containing navigation references to other page, reference to the Page object etc.\n\n\n\n\n\n",
"title": "Documenter.Documents.NavNode"
},
{
"category": "type",
"location": "lib/internals/documents/#Documenter.Documents.Page",
"page": "Documents",
"text": "Represents a single markdown file.\n\n\n\n\n\n",
"title": "Documenter.Documents.Page"
},
{
"category": "type",
"location": "lib/internals/documents/#Documenter.Documents.User",
"page": "Documents",
"text": "User-specified values used to control the generation process.\n\n\n\n\n\n",
"title": "Documenter.Documents.User"
},
{
"category": "type",
"location": "lib/internals/dom/#Documenter.Utilities.DOM.HTMLDocument",
"page": "DOM",
"text": "A HTML node that wraps around the root node of the document and adds a DOCTYPE to it.\n\n\n\n\n\n",
"title": "Documenter.Utilities.DOM.HTMLDocument"
},
{
"category": "type",
"location": "lib/internals/dom/#Documenter.Utilities.DOM.Node",
"page": "DOM",
"text": "Represents an element within an HTML document including any textual content, children Nodes, and attributes.\n\nThis type should not be constructed directly, but instead via (...) and [...] applied to a Tag or another Node object.\n\n\n\n\n\n",
"title": "Documenter.Utilities.DOM.Node"
},
{
"category": "type",
"location": "lib/internals/dom/#Documenter.Utilities.DOM.Tag",
"page": "DOM",
"text": "Represents a empty and attribute-less HTML element.\n\nUse @tags to define instances of this type rather than manually creating them via Tag(:tagname).\n\n\n\n\n\n",
"title": "Documenter.Utilities.DOM.Tag"
},
{
"category": "type",
"location": "lib/internals/expanders/#Documenter.Expanders.AutoDocsBlocks",
"page": "Expanders",
"text": "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 = ....\n\n```@autodocs\nModules = [Foo, Bar]\nOrder = [:function, :type]\n```\n\n\n\n\n\n",
"title": "Documenter.Expanders.AutoDocsBlocks"
},
{
"category": "type",
"location": "lib/internals/expanders/#Documenter.Expanders.ContentsBlocks",
"page": "Expanders",
"text": "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.\n\n```@contents\nPages = [\"foo.md\", \"bar.md\"]\nDepth = 1\n```\n\nThe default Depth value is 2.\n\n\n\n\n\n",
"title": "Documenter.Expanders.ContentsBlocks"
},
{
"category": "type",
"location": "lib/internals/expanders/#Documenter.Expanders.DocsBlocks",
"page": "Expanders",
"text": "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.\n\n```@docs\nDocumenter\nmakedocs\ndeploydocs\n```\n\n\n\n\n\n",
"title": "Documenter.Expanders.DocsBlocks"
},
{
"category": "type",
"location": "lib/internals/expanders/#Documenter.Expanders.EvalBlocks",
"page": "Expanders",
"text": "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.\n\n```@eval\nusing PyPlot\nx = linspace(-π, π)\ny = sin(x)\nplot(x, y, color = \"red\")\nsavefig(\"plot.svg\")\nMarkdown.parse(\"![Plot](plot.svg)\")\n```\n\n\n\n\n\n",
"title": "Documenter.Expanders.EvalBlocks"
},
{
"category": "type",
"location": "lib/internals/expanders/#Documenter.Expanders.ExampleBlocks",
"page": "Expanders",
"text": "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.\n\n```@example\na = 1\nb = 2\na + b\n```\n\n\n\n\n\n",
"title": "Documenter.Expanders.ExampleBlocks"
},
{
"category": "type",
"location": "lib/internals/expanders/#Documenter.Expanders.ExpanderPipeline",
"page": "Expanders",
"text": "The default node expander \"pipeline\", which consists of the following expanders:\n\nTrackHeaders\nMetaBlocks\nDocsBlocks\nAutoDocsBlocks\nEvalBlocks\nIndexBlocks\nContentsBlocks\nExampleBlocks\nSetupBlocks\nREPLBlocks\n\n\n\n\n\n",
"title": "Documenter.Expanders.ExpanderPipeline"
},
{
"category": "type",
"location": "lib/internals/expanders/#Documenter.Expanders.IndexBlocks",
"page": "Expanders",
"text": "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\n\n```@index\nPages = [\"foo.md\", \"bar.md\"]\n```\n\n\n\n\n\n",
"title": "Documenter.Expanders.IndexBlocks"
},
{
"category": "type",
"location": "lib/internals/expanders/#Documenter.Expanders.MetaBlocks",
"page": "Expanders",
"text": "Parses each code block where the language is @meta and evaluates the key/value pairs found within the block, i.e.\n\n```@meta\nCurrentModule = Documenter\nDocTestSetup = quote\n using Documenter\nend\n```\n\n\n\n\n\n",
"title": "Documenter.Expanders.MetaBlocks"
},
{
"category": "type",
"location": "lib/internals/expanders/#Documenter.Expanders.REPLBlocks",
"page": "Expanders",
"text": "Similar to the ExampleBlocks expander, but inserts a Julia REPL prompt before each toplevel expression in the final document.\n\n\n\n\n\n",
"title": "Documenter.Expanders.REPLBlocks"
},
{
"category": "type",
"location": "lib/internals/expanders/#Documenter.Expanders.SetupBlocks",
"page": "Expanders",
"text": "Similar to the ExampleBlocks expander, but hides all output in the final document.\n\n\n\n\n\n",
"title": "Documenter.Expanders.SetupBlocks"
},
{
"category": "type",
"location": "lib/internals/expanders/#Documenter.Expanders.TrackHeaders",
"page": "Expanders",
"text": "Tracks all Markdown.Header nodes found in the parsed markdown files and stores an Anchors.Anchor object for each one.\n\n\n\n\n\n",
"title": "Documenter.Expanders.TrackHeaders"
},
{
"category": "type",
"location": "lib/internals/selectors/#Documenter.Utilities.Selectors.AbstractSelector",
"page": "Selectors",
"text": "Root selector type. Each user-defined selector must subtype from this, i.e.\n\nabstract type MySelector <: Selectors.AbstractSelector end\n\nabstract type First <: MySelector end\nabstract type Second <: MySelector end\n\n\n\n\n\n",
"title": "Documenter.Utilities.Selectors.AbstractSelector"
},
{
"category": "type",
"location": "lib/internals/utilities/#Documenter.Utilities.Object",
"page": "Utilities",
"text": "Represents an object stored in the docsystem by its binding and signature.\n\n\n\n\n\n",
"title": "Documenter.Utilities.Object"
},
{
"category": "type",
"location": "lib/internals/writers/#Documenter.Plugin",
"page": "Writers",
"text": "abstract type Plugin end\n\nAny plugin that needs to either solicit user input or store information in a Documents.Document should create a subtype of Plugin. The subtype, T <: Documenter.Plugin, must have an empty constructor T() that initialized T with the appropriate default values.\n\nTo retrieve the values stored in T, the plugin can call Documents.getplugin. If T was passed to makedocs, the passed type will be returned. Otherwise, a new T object will be created.\n\n\n\n\n\n",
"title": "Documenter.Plugin"
},
{
"category": "type",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.HTML",
"page": "Writers",
"text": "HTML(kwargs...)\n\nSets the behavior of HTMLWriter.\n\nKeyword arguments\n\nprettyurls (default true) – allows toggling the pretty URLs feature.\n\nBy default (i.e. when prettyurls is set to true), Documenter creates a directory structure that hides the .html suffixes from the URLs (e.g. by default src/foo.md becomes src/foo/index.html, but can be accessed with via src/foo/ in the browser). This structure is preferred when publishing the generate HTML files as a website (e.g. on GitHub Pages), which is Documenter's primary use case.\n\nIf prettyurls = false, then Documenter generates src/foo.html instead, suitable for local documentation builds, as browsers do not normally resolve foo/ to foo/index.html for local files.\n\nTo have pretty URLs disabled in local builds, but still have them enabled for the automatic CI deployment builds, you can set prettyurls = get(ENV, \"CI\", nothing) == \"true\" (the specific environment variable you will need to check may depend on the CI system you are using, but this will work on Travis CI).\n\ndisable_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.\n\nedit_branch specifies which branch, tag or commit the \"Edit on GitHub\" links point to. It defaults to master. If it set to nothing, the current commit will be used.\n\ncanonical specifies the canonical URL for your documentation. We recommend you set this to the base url of your stable documentation, e.g. https://juliadocs.github.io/Documenter.jl/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.\n\nanalytics can be used specify the Google Analytics tracking ID.\n\nassets can be used to include additional assets (JS, CSS, ICO etc. files). See below for more information.\n\nDefault and custom assets\n\nDocumenter 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.\n\nThe HTML output also links certain custom assets to the generated HTML documents, specifically 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).\n\nFor 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.\n\nAdditional JS, ICO, and CSS assets can be included in the generated pages using the assets keyword for makedocs. assets must be a Vector{String} and will include each listed asset in the <head> of every page in the order in which they are listed. 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, or .css. Adding an ICO asset is primarilly useful for setting a custom favicon.\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.HTML"
},
{
"category": "type",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.HTMLContext",
"page": "Writers",
"text": "HTMLWriter-specific globals that are passed to domify and other recursive functions.\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.HTMLContext"
},
{
"category": "type",
"location": "lib/internals/writers/#Documenter.Writers.LaTeXWriter.LaTeX",
"page": "Writers",
"text": "LaTeXWriter.LaTeX(; kwargs...)\n\nOutput format specifier that results in LaTeX/PDF output. Used together with makedocs, e.g.\n\nmakedocs(\n format = LaTeX()\n)\n\nThe makedocs argument sitename will be used for the \\title field in the tex document, and if the build is for a release tag (i.e. when the \"TRAVIS_TAG\" environment variable is set) the version number will be appended to the title. The makedocs argument authors should also be specified, it will be used for the \\authors field in the tex document.\n\nKeyword arguments\n\nplatform sets the platform where the tex-file is compiled, either \"native\" (default) or \"docker\". See Other Output Formats for more information.\n\n\n\n\n\n",
"title": "Documenter.Writers.LaTeXWriter.LaTeX"
}
]
Raw
search.json
[
{
"category": "constant",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.MDBlockContext",
"page": "Writers",
"text": "MDBlockContext is a union of all the Markdown nodes whose children should be blocks. It can be used to dispatch on all the block-context nodes at once.\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.MDBlockContext"
},
{
"category": "function",
"location": "lib/internals/docsystem/#Documenter.DocSystem.getdocs",
"page": "DocSystem",
"text": "getdocs(binding)\ngetdocs(binding, typesig; compare, modules, aliases)\n\n\nFind all DocStr objects that match the provided arguments:\n\nbinding: the name of the object.\ntypesig: the signature of the object. Default: Union{}.\ncompare: how to compare signatures? Exact (==) or subtypes (<:). Default: <:.\nmodules: which modules to search through. Default: all modules.\naliases: check aliases of binding when nothing is found. Default: true.\n\nReturns a Vector{DocStr} ordered by definition order in 0.5 and by type_morespecific in 0.4.\n\n\n\n\n\n",
"title": "Documenter.DocSystem.getdocs"
},
{
"category": "function",
"location": "lib/internals/docsystem/#Documenter.DocSystem.getdocs",
"page": "DocSystem",
"text": "getdocs(object)\ngetdocs(object, typesig; kws...)\n\n\nAccepts objects of any type and tries to convert them to Bindings before searching for the Binding in the docsystem.\n\nNote that when conversion fails this method returns an empty Vector{DocStr}.\n\n\n\n\n\n",
"title": "Documenter.DocSystem.getdocs"
},
{
"category": "function",
"location": "lib/internals/docsystem/#Documenter.DocSystem.multidoc",
"page": "DocSystem",
"text": "Construct a MultiDoc object from the provided argument.\n\nValid inputs are:\n\nMarkdown.MD\nDocs.FuncDoc\nDocs.TypeDoc\n\n\n\n\n\n",
"title": "Documenter.DocSystem.multidoc"
},
{
"category": "function",
"location": "lib/internals/documenter/#Documenter.git_push",
"page": "Documenter",
"text": "git_push(\n root, tmp, repo;\n branch=\"gh-pages\", dirname=\"\", target=\"site\", tag=\"\", key=\"\", sha=\"\", devurl=\"dev\"\n)\n\nHandles pushing changes to the remote documentation branch. When tag is empty the docs are deployed to the devurl directory, and when building docs for a tag they are deployed to a vX.Y.Z directory.\n\n\n\n\n\n",
"title": "Documenter.git_push"
},
{
"category": "function",
"location": "lib/internals/documenter/#Documenter.gitrm_copy",
"page": "Documenter",
"text": "gitrm_copy(src, dst)\n\nUses 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.\n\nThis 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.\n\n\n\n\n\n",
"title": "Documenter.gitrm_copy"
},
{
"category": "function",
"location": "lib/internals/documentertools/#DocumenterTools.package_devpath",
"page": "DocumenterTools",
"text": "package_devpath(pkg)\n\n\nReturns the path to the top level directory of a devved out package source tree. The package is identified by its top level module pkg.\n\n\n\n\n\n",
"title": "DocumenterTools.package_devpath"
},
{
"category": "function",
"location": "lib/internals/selectors/#Documenter.Utilities.Selectors.matcher",
"page": "Selectors",
"text": "Define the matching test for each case in a selector, i.e.\n\nSelectors.matcher(::Type{First}, x) = x == 1\nSelectors.matcher(::Type{Second}, x) = true\n\nNote that the return type must be Bool.\n\nTo match against multiple cases use the Selectors.strict function.\n\n\n\n\n\n",
"title": "Documenter.Utilities.Selectors.matcher"
},
{
"category": "function",
"location": "lib/internals/selectors/#Documenter.Utilities.Selectors.order",
"page": "Selectors",
"text": "Define the precedence of each case in a selector, i.e.\n\nSelectors.order(::Type{First}) = 1.0\nSelectors.order(::Type{Second}) = 2.0\n\nNote that the return type must be Float64. Defining multiple case types to have the same order will result in undefined behaviour.\n\n\n\n\n\n",
"title": "Documenter.Utilities.Selectors.order"
},
{
"category": "function",
"location": "lib/internals/selectors/#Documenter.Utilities.Selectors.runner",
"page": "Selectors",
"text": "Define the code that will run when a particular Selectors.matcher test returns true, i.e.\n\nSelectors.runner(::Type{First}, x) = println(\"`x` is equal to `1`.\")\nSelectors.runner(::Type{Second}, x) = println(\"`x` is not equal to `1`.\")\n\n\n\n\n\n",
"title": "Documenter.Utilities.Selectors.runner"
},
{
"category": "function",
"location": "lib/internals/utilities/#Documenter.Utilities.docs",
"page": "Utilities",
"text": "docs(ex, str)\n\nReturns an expression that, when evaluated, returns the docstrings associated with ex.\n\n\n\n\n\n",
"title": "Documenter.Utilities.docs"
},
{
"category": "function",
"location": "lib/public/#Documenter.Deps.pip",
"page": "Public",
"text": "pip(deps)\n\n\nInstalls (as non-root user) all python packages listed in deps.\n\nExamples\n\nusing Documenter\n\nmakedocs(\n # ...\n)\n\ndeploydocs(\n deps = Deps.pip(\"pygments\", \"mkdocs\", \"mkdocs-material\"),\n # ...\n)\n\n\n\n\n\n",
"title": "Documenter.Deps.pip"
},
{
"category": "function",
"location": "lib/public/#Documenter.deploydocs",
"page": "Public",
"text": "deploydocs(\n root = \"<current-directory>\",\n target = \"build\",\n repo = \"<required>\",\n branch = \"gh-pages\",\n deps = nothing | <Function>,\n make = nothing | <Function>,\n devbranch = \"master\",\n devurl = \"dev\",\n versions = [\"stable\" => \"v^\", \"v#.#\", devurl => devurl]\n)\n\nConverts markdown files generated by makedocs to HTML and pushes them to repo. This function should be called from within a package's docs/make.jl file after the call to makedocs, like so\n\nusing Documenter, PACKAGE_NAME\nmakedocs(\n # options...\n)\ndeploydocs(\n repo = \"github.com/...\"\n)\n\nWhen 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.\n\nRequired keyword arguments\n\nrepo 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:\n\nrepo = \"github.com/JuliaDocs/Documenter.jl.git\"\n\nOptional keyword arguments\n\nroot has the same purpose as the root keyword for makedocs.\n\ntarget is the directory, relative to root, where generated content that should be deployed to gh-pages is written to. written to. It should generally be the same as makedocs's build and defaults to \"build\".\n\nbranch 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\".\n\ndeps is the function used to install any additional dependencies needed to build the documentation. By default nothing is installed.\n\nIt can be used e.g. for a Markdown build. The following example installed the pygments and mkdocs Python packages using the Deps.pip function:\n\ndeps = Deps.pip(\"pygments\", \"mkdocs\")\n\nmake is the function used to specify an additonal build phase. By default, nothing gets executed.\n\ndevbranch is the branch that \"tracks\" the in-development version of the generated documentation. By default this value is set to \"master\".\n\ndevurl the folder that in-development version of the docs will be deployed. Defaults to \"dev\".\n\nforcepush 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.\n\nversions determines content and order of the resulting version selector in the generated html. The following entries are valied in the versions vector:\n\n\"v#\": includes links to the latest documentation for each major release cycle (i.e. v2.0, v1.1).\n\"v#.#\": includes links to the latest documentation for each minor release cycle (i.e. v2.0, v1.1, v1.0, v0.1).\n\"v#.#.#\": includes links to all released versions.\n\"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).\nA 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^\").\n\nEnvironment variables\n\ndeploydocs's behavior is influenced by the following environment variables, many of which are specific to the Travis CI platform.\n\nDOCUMENTER_KEY: must contain the Base64-encoded SSH private key for the repository.\nTRAVIS_PULL_REQUEST: must be set to false.\nThis avoids deployment on pull request builds. Note that there is no way to safely enable builds on pull requests, since that would expose the SSH private key (DOCUMENTER_KEY), giving anyone opening a pull request full write access to the repository.\nTRAVIS_REPO_SLUG: must match the value of the repo keyword.\nTRAVIS_EVENT_TYPE: may not be set to cron.\nThis avoids the re-deployment of existing docs on builds that were triggered by a Travis cron job.\nTRAVIS_BRANCH: unless TRAVIS_TAG is non-empty, this must have the same value as the devbranch keyword.\nThis 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).\nTRAVIS_TAG: if set, a tagged version deployment is performed instead; the value must be a valid version number (i.e. match Base.VERSION_REGEX).\nThe documentation for a package version tag gets deployed to a directory named after the version number in TRAVIS_TAG instead.\n\nThe TRAVIS_* variables are set automatically on Travis, but could be set manually to appropriate values as well to run deploydocs locally or on other CI platforms. More information on how Travis sets the TRAVIS_* variables can be found in the Travis documentation.\n\nSee Also\n\nThe 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.\n\n\n\n\n\n",
"title": "Documenter.deploydocs"
},
{
"category": "function",
"location": "lib/public/#Documenter.hide",
"page": "Public",
"text": "hide(page)\n\n\nAllows 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 overriden using the => operator as usual.\n\nUsage\n\nmakedocs(\n ...,\n pages = [\n ...,\n hide(\"page1.md\"),\n hide(\"Title\" => \"page2.md\")\n ]\n)\n\n\n\n\n\nhide(root, children)\n\n\nAllows 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).\n\nUsage\n\nmakedocs(\n ...,\n pages = [\n ...,\n hide(\"Hidden section\" => \"hidden_index.md\", [\n \"hidden1.md\",\n \"Hidden 2\" => \"hidden2.md\"\n ]),\n hide(\"hidden_index.md\", [...])\n ]\n)\n\n\n\n\n\n",
"title": "Documenter.hide"
},
{
"category": "function",
"location": "lib/public/#Documenter.makedocs",
"page": "Public",
"text": "makedocs(\n root = \"<current-directory>\",\n source = \"src\",\n build = \"build\",\n clean = true,\n doctest = true,\n modules = Module[],\n repo = \"\",\n)\n\nCombines markdown files and inline docstrings into an interlinked document. In most cases makedocs should be run from a make.jl file:\n\nusing Documenter\nmakedocs(\n # keywords...\n)\n\nwhich is then run from the command line with:\n\n$ julia make.jl\n\nThe folder structure that makedocs expects looks like:\n\ndocs/\n build/\n src/\n make.jl\n\nKeywords\n\nroot is the directory from which makedocs should run. When run from a make.jl file this keyword does not need to be set. It is, for the most part, needed when repeatedly running makedocs from the Julia REPL like so:\n\njulia> makedocs(root = joinpath(pathof(MyModule), \"..\", \"..\", \"docs\"))\n\nsource is the directory, relative to root, where the markdown source files are read from. By convention this folder is called src. Note that any non-markdown files stored in source are copied over to the build directory when makedocs is run.\n\nbuild is the directory, relative to root, into which generated files and folders are written when makedocs is run. The name of the build directory is, by convention, called build, though, like with source, users are free to change this to anything else to better suit their project needs.\n\nclean tells makedocs whether to remove all the content from the build folder prior to generating new content from source. By default this is set to true.\n\ndoctest instructs makedocs on whether to try to test Julia code blocks that are encountered in the generated document. By default this keyword is set to true. Doctesting should only ever be disabled when initially setting up a newly developed package where the developer is just trying to get their package and documentation structure correct. After that, it's encouraged to always make sure that documentation examples are runnable and produce the expected results. See the Doctests manual section for details about running doctests.\n\nmodules specifies a vector of modules that should be documented in source. If any inline docstrings from those modules are seen to be missing from the generated content then a warning will be printed during execution of makedocs. By default no modules are passed to modules and so no warnings will appear. This setting can be used as an indicator of the \"coverage\" of the generated documentation. For example Documenter's make.jl file contains:\n\nmakedocs(\n modules = [Documenter],\n # ...\n)\n\nand so any docstring from the module Documenter that is not spliced into the generated documentation in build will raise a warning.\n\nrepo specifies a template for the \"link to source\" feature. If you are using GitHub, this is automatically generated from the remote. If you are using a different host, you can use this option to tell Documenter how URLs should be generated. The following placeholders will be replaced with the respective value of the generated link:\n\n{commit} Git branch or tag name, or commit hash\n{path} Path to the file in the repository\n{line} Line (or range of lines) in the source file\n\nFor example if you are using GitLab.com, you could use\n\nmakedocs(repo = \"https://gitlab.com/user/project/blob/{commit}{path}#{line}\")\n\nExperimental keywords\n\nIn addition to standard arguments there is a set of non-finalized experimental keyword arguments. The behaviour of these may change or they may be removed without deprecation when a minor version changes (i.e. except in patch releases).\n\ncheckdocs 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 blocks with that docstring). Possible values are :all (check all names) and :exports (check only exported names). The default value is :none, in which case no checks are performed. If strict is also enabled then the build will fail if any missing docstrings are encountered.\n\nlinkcheck – 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. If strict is also enabled then the build will fail if there are any broken (400+ status code) links. Default: false.\n\nlinkcheck_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.\n\nstrict – makedocs fails the build right before rendering if it encountered any errors with the document in the previous build phases.\n\nOutput formats\n\nformat allows the output format to be specified. The default format is Documenter.HTML which creates a set of HTML files.\n\nThere are other possible formats that are enabled by using other addon-packages. For examples, the DocumenterMarkdown package define the DocumenterMarkdown.Markdown() format for use with e.g. MkDocs, and the DocumenterLaTeX package define the DocumenterLaTeX.LaTeX() format for LaTeX / PDF output. See the Other Output Formats for more information.\n\nSee Also\n\nA guide detailing how to document a package using Documenter's makedocs is provided in the setup guide in the manual.\n\n\n\n\n\n",
"title": "Documenter.makedocs"
},
{
"category": "function",
"location": "lib/public/#DocumenterTools.Travis.genkeys",
"page": "Public",
"text": "genkeys(; user=\"$USER\", repo=\"$REPO\")\n\nGenerates the SSH keys necessary for the automatic deployment of documentation with Documenter from Travis to GitHub Pages.\n\nBy default the links in the instructions need to be modified to correspond to actual URLs. The optional user and repo keyword arguments can be specified so that the URLs in the printed instructions could be copied directly. They should be the name of the GitHub user or organization where the repository is hosted and the full name of the repository, respectively.\n\nThis method of genkeys requires the following command lines programs to be installed:\n\nwhich\nssh-keygen\n\nExamples\n\njulia> using DocumenterTools\n\njulia> Travis.genkeys()\n[ Info: add the public key below to https://github.com/$USER/$REPO/settings/keys with read/write access:\n\nssh-rsa AAAAB3NzaC2yc2EAAAaDAQABAAABAQDrNsUZYBWJtXYUk21wxZbX3KxcH8EqzR3ZdTna0Wgk...jNmUiGEMKrr0aqQMZEL2BG7 username@hostname\n\n[ Info: add a secure environment variable named 'DOCUMENTER_KEY' to https://travis-ci.org/$USER/$REPO/settings with value:\n\nLS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBNnpiRkdXQVZpYlIy...QkVBRWFjY3BxaW9uNjFLaVdOcDU5T2YrUkdmCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==\n\n\njulia> Travis.genkeys(user=\"JuliaDocs\", repo=\"DocumenterTools.jl\")\n[Info: add the public key below to https://github.com/JuliaDocs/DocumenterTools.jl/settings/keys with read/write access:\n\nssh-rsa AAAAB3NzaC2yc2EAAAaDAQABAAABAQDrNsUZYBWJtXYUk21wxZbX3KxcH8EqzR3ZdTna0Wgk...jNmUiGEMKrr0aqQMZEL2BG7 username@hostname\n\n[ Info: add a secure environment variable named 'DOCUMENTER_KEY' to https://travis-ci.org/JuliaDocs/DocumenterTools.jl/settings with value:\n\nLS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBNnpiRkdXQVZpYlIy...QkVBRWFjY3BxaW9uNjFLaVdOcDU5T2YrUkdmCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==\n\n\n\n\n\ngenkeys(package::Module; remote=\"origin\")\n\nLike the other method, this generates the SSH keys necessary for the automatic deployment of documentation with Documenter from Travis to GitHub Pages, but attempts to guess the package URLs from the Git remote.\n\npackage needs to be the top level module of the package. The remote keyword argument can be used to specify which Git remote is used for guessing the repository's GitHub URL.\n\nThis method requires the following command lines programs to be installed:\n\nwhich\ngit\nssh-keygen\n\nnote: Note\nThe package must be in development mode. Make sure you run pkg> develop pkg from the Pkg REPL, or Pkg.develop(\"pkg\") before generating the SSH keys.\n\nExamples\n\njulia> using DocumenterTools\n\njulia> Travis.genkeys(DocumenterTools)\n[Info: add the public key below to https://github.com/JuliaDocs/DocumenterTools.jl/settings/keys with read/write access:\n\nssh-rsa AAAAB3NzaC2yc2EAAAaDAQABAAABAQDrNsUZYBWJtXYUk21wxZbX3KxcH8EqzR3ZdTna0Wgk...jNmUiGEMKrr0aqQMZEL2BG7 username@hostname\n\n[ Info: add a secure environment variable named 'DOCUMENTER_KEY' to https://travis-ci.org/JuliaDocs/DocumenterTools.jl/settings with value:\n\nLS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBNnpiRkdXQVZpYlIy...QkVBRWFjY3BxaW9uNjFLaVdOcDU5T2YrUkdmCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==\n\n\n\n\n\n",
"title": "DocumenterTools.Travis.genkeys"
},
{
"category": "function",
"location": "lib/public/#DocumenterTools.generate",
"page": "Public",
"text": "DocumenterTools.generate(path::String; name = nothing, format = :html)\n\nCreate 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.\n\ngenerate creates the following files in path:\n\n.gitignore\nsrc/index.md\nmake.jl\nmkdocs.yml\nProject.toml\n\nArguments\n\npath file path to the documentation directory.\n\nKeywords Arguments\n\nname is the name of the package (without .jl). If name is not given generate tries to detect it automatically.\n\nformat can be either :html (default), :markdown or :pdf corresponding to the format keyword to Documenter's makedocs function, see Documenter's manual.\n\nExamples\n\njulia> using DocumenterTools\n\njulia> Documenter.generate(\"path/to/MyPackage/docs\")\n[ ... output ... ]\n\n\n\n\n\nDocumenterTools.generate(pkg::Module; dir = \"docs\", format = :html)\n\nSame as generate(path::String) but the path and name is determined automatically from the module.\n\nnote: Note\nThe package must be in development mode. Make sure you run pkg> develop pkg from the Pkg REPL, or Pkg.develop(\"pkg\") before generating docs.\n\nExamples\n\njulia> using DocumenterTools\n\njulia> using MyPackage\n\njulia> DocumenterTools.generate(MyPackage)\n[ ... output ... ]\n\n\n\n\n\n",
"title": "DocumenterTools.generate"
},
{
"category": "macro",
"location": "lib/internals/dom/#Documenter.Utilities.DOM.@tags-Tuple",
"page": "DOM",
"text": "Define a collection of Tag objects and bind them to constants with the same names.\n\nExamples\n\nDefined globally within a module:\n\n@tags div ul li\n\nDefined within the scope of a function to avoid cluttering the global namespace:\n\nfunction template(args...)\n @tags div ul li\n # ...\nend\n\n\n\n\n\n",
"title": "Documenter.Utilities.DOM.@tags"
},
{
"category": "method",
"location": "lib/internals/anchors/#Documenter.Anchors.add!-Tuple{Documenter.Anchors.AnchorMap,Documenter.Anchors.Anchor,Any,Any}",
"page": "Anchors",
"text": "add!(m, anchor, id, file)\n\n\nAdds a new Anchor to the AnchorMap for a given id and file.\n\nEither an actual Anchor object may be provided or any other object which is automatically wrapped in an Anchor before being added to the AnchorMap.\n\n\n\n\n\n",
"title": "Documenter.Anchors.add!"
},
{
"category": "method",
"location": "lib/internals/anchors/#Documenter.Anchors.anchor-Tuple{Documenter.Anchors.AnchorMap,Any}",
"page": "Anchors",
"text": "anchor(m, id)\n\n\nReturns the Anchor object matching id. file and n may also be provided. An Anchor is returned, or nothing in case of no match.\n\n\n\n\n\n",
"title": "Documenter.Anchors.anchor"
},
{
"category": "method",
"location": "lib/internals/anchors/#Documenter.Anchors.exists-Tuple{Documenter.Anchors.AnchorMap,Any,Any,Any}",
"page": "Anchors",
"text": "exists(m, id, file, n)\n\n\nDoes the given id exist within the AnchorMap? A file and integer n may also be provided to narrow the search for existance.\n\n\n\n\n\n",
"title": "Documenter.Anchors.exists"
},
{
"category": "method",
"location": "lib/internals/anchors/#Documenter.Anchors.isunique-Tuple{Documenter.Anchors.AnchorMap,Any}",
"page": "Anchors",
"text": "isunique(m, id)\n\n\nIs the id unique within the given AnchorMap? May also specify the file.\n\n\n\n\n\n",
"title": "Documenter.Anchors.isunique"
},
{
"category": "method",
"location": "lib/internals/builder/#Documenter.Builder.walk_navpages-NTuple{6,Any}",
"page": "Builder",
"text": "walk_navpages(visible, title, src, children, parent, doc)\n\n\nRecursively walks through the Documents.Document's .user.pages field, generating Documents.NavNodes and related data structures in the process.\n\nThis implementation is the de facto specification for the .user.pages field.\n\n\n\n\n\n",
"title": "Documenter.Builder.walk_navpages"
},
{
"category": "method",
"location": "lib/internals/cross-references/#Documenter.CrossReferences.crossref-Tuple{Documenter.Documents.Document}",
"page": "CrossReferences",
"text": "crossref(doc)\n\n\nTraverses a Documents.Document and replaces links containg @ref URLs with their real URLs.\n\n\n\n\n\n",
"title": "Documenter.CrossReferences.crossref"
},
{
"category": "method",
"location": "lib/internals/cross-references/#Documenter.CrossReferences.find_object-Tuple{Documenter.Documents.Document,Any,Any}",
"page": "CrossReferences",
"text": "find_object(doc, binding, typesig)\n\n\nFind 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.\n\n\n\n\n\n",
"title": "Documenter.CrossReferences.find_object"
},
{
"category": "method",
"location": "lib/internals/docchecks/#Documenter.DocChecks.footnotes-Tuple{Documenter.Documents.Document}",
"page": "DocChecks",
"text": "footnotes(doc)\n\n\nChecks footnote links in a Documents.Document.\n\n\n\n\n\n",
"title": "Documenter.DocChecks.footnotes"
},
{
"category": "method",
"location": "lib/internals/docchecks/#Documenter.DocChecks.linkcheck-Tuple{Documenter.Documents.Document}",
"page": "DocChecks",
"text": "linkcheck(doc)\n\n\nChecks external links using curl.\n\n\n\n\n\n",
"title": "Documenter.DocChecks.linkcheck"
},
{
"category": "method",
"location": "lib/internals/docchecks/#Documenter.DocChecks.missingdocs-Tuple{Documenter.Documents.Document}",
"page": "DocChecks",
"text": "missingdocs(doc)\n\n\nChecks that a Documents.Document contains all available docstrings that are defined in the modules keyword passed to Documenter.makedocs.\n\nPrints out the name of each object that has not had its docs spliced into the document.\n\n\n\n\n\n",
"title": "Documenter.DocChecks.missingdocs"
},
{
"category": "method",
"location": "lib/internals/docsystem/#Documenter.DocSystem.binding-Tuple{Any}",
"page": "DocSystem",
"text": "Converts an object to a Base.Docs.Binding object.\n\nbinding(any)\n\n\nSupported inputs are:\n\nBinding\nDataType\nFunction\nModule\nSymbol\n\nNote that unsupported objects will throw an ArgumentError.\n\n\n\n\n\n",
"title": "Documenter.DocSystem.binding"
},
{
"category": "method",
"location": "lib/internals/docsystem/#Documenter.DocSystem.convertmeta-Tuple{IdDict{Any,Any}}",
"page": "DocSystem",
"text": "convertmeta(meta)\n\n\nConverts a 0.4-style docstring cache into a 0.5 one.\n\nThe original docstring cache is not modified.\n\n\n\n\n\n",
"title": "Documenter.DocSystem.convertmeta"
},
{
"category": "method",
"location": "lib/internals/docsystem/#Documenter.DocSystem.docstr-Tuple{Markdown.MD}",
"page": "DocSystem",
"text": "docstr(md; kws...)\n\n\nConstruct a DocStr object from a Markdown.MD object.\n\nThe optional keyword arguments are used to add new data to the DocStr's .data dictionary.\n\n\n\n\n\n",
"title": "Documenter.DocSystem.docstr"
},
{
"category": "method",
"location": "lib/internals/doctests/#Documenter.DocTests.doctest-Tuple{Documenter.Documents.Document}",
"page": "DocTests",
"text": "doctest(doc)\n\n\nTraverses the document tree and tries to run each Julia code block encountered. Will abort the document generation when an error is thrown. Use doctest = false keyword in Documenter.makedocs to disable doctesting.\n\n\n\n\n\n",
"title": "Documenter.DocTests.doctest"
},
{
"category": "method",
"location": "lib/internals/documentertools/#DocumenterTools.Generator.gitignore-Tuple{}",
"page": "DocumenterTools",
"text": "gitignore()\n\n\nContents of the default .gitignore file.\n\n\n\n\n\n",
"title": "DocumenterTools.Generator.gitignore"
},
{
"category": "method",
"location": "lib/internals/documentertools/#DocumenterTools.Generator.index-Tuple{Any}",
"page": "DocumenterTools",
"text": "index(pkgname)\n\n\nContents of the default src/index.md file.\n\n\n\n\n\n",
"title": "DocumenterTools.Generator.index"
},
{
"category": "method",
"location": "lib/internals/documentertools/#DocumenterTools.Generator.make-Tuple{Any}",
"page": "DocumenterTools",
"text": "make(pkgname; format)\n\n\nContents of the default make.jl file.\n\n\n\n\n\n",
"title": "DocumenterTools.Generator.make"
},
{
"category": "method",
"location": "lib/internals/documentertools/#DocumenterTools.Generator.mkdocs-Tuple{Any}",
"page": "DocumenterTools",
"text": "mkdocs(pkgname; description, author, url)\n\n\nContents of the default mkdocs.yml file.\n\n\n\n\n\n",
"title": "DocumenterTools.Generator.mkdocs"
},
{
"category": "method",
"location": "lib/internals/documentertools/#DocumenterTools.Generator.project-Tuple{}",
"page": "DocumenterTools",
"text": "project(; format)\n\n\nContents of the default Project.toml file.\n\n\n\n\n\n",
"title": "DocumenterTools.Generator.project"
},
{
"category": "method",
"location": "lib/internals/documentertools/#DocumenterTools.Generator.savefile-Tuple{Any,Any,Any}",
"page": "DocumenterTools",
"text": "savefile(f, root, filename)\n\n\nAttempts to save a file at $(root)/$(filename). f will be called with file stream (see open).\n\nfilename can also be a file in a subdirectory (e.g. src/index.md), and then then subdirectories will be created automatically.\n\n\n\n\n\n",
"title": "DocumenterTools.Generator.savefile"
},
{
"category": "method",
"location": "lib/internals/documents/#Documenter.Documents.getplugin-Union{Tuple{T}, Tuple{Document,Type{T}}} where T<:Documenter.Plugin",
"page": "Documents",
"text": "getplugin(doc::Document, T)\n\nRetrieves the Plugin type for T stored in doc. If T was passed to makedocs, the passed type will be returned. Otherwise, a new T object will be created using the default constructor T().\n\n\n\n\n\n",
"title": "Documenter.Documents.getplugin"
},
{
"category": "method",
"location": "lib/internals/documents/#Documenter.Documents.navpath-Tuple{Documenter.Documents.NavNode}",
"page": "Documents",
"text": "Constructs a list of the ancestors of the navnode (inclding the navnode itself), ordered so that the root of the navigation tree is the first and navnode itself is the last item.\n\n\n\n\n\n",
"title": "Documenter.Documents.navpath"
},
{
"category": "method",
"location": "lib/internals/documents/#Documenter.Documents.populate!-Tuple{Documenter.Documents.Document}",
"page": "Documents",
"text": "populate!(document)\n\n\nPopulates the ContentsNodes and IndexNodes of the document with links.\n\nThis 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.\n\n\n\n\n\n",
"title": "Documenter.Documents.populate!"
},
{
"category": "method",
"location": "lib/internals/documents/#Documenter.Documents.walk-Tuple{Any,Any,Any}",
"page": "Documents",
"text": "walk(f, meta, element)\n\n\nCalls f on element and any of its child elements. meta is a Dict containing metadata such as current module.\n\n\n\n\n\n",
"title": "Documenter.Documents.walk"
},
{
"category": "method",
"location": "lib/internals/dom/#Documenter.Utilities.DOM.escapehtml-Tuple{AbstractString}",
"page": "DOM",
"text": "Escape characters in the provided string. This converts the following characters:\n\n< to &lt;\n> to &gt;\n& to &amp;\n' to &#39;\n\" to &quot;\n\nWhen 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 ===.\n\n\n\n\n\n",
"title": "Documenter.Utilities.DOM.escapehtml"
},
{
"category": "method",
"location": "lib/internals/dom/#Documenter.Utilities.DOM.flatten!-Tuple{Any,Any,Union{AbstractString, Symbol, Node, Pair}}",
"page": "DOM",
"text": "Signatures\n\nflatten!(f!, out, x::Atom)\nflatten!(f!, out, xs)\n\nFlatten the contents the third argument into the second after applying the function f! to the element.\n\n\n\n\n\n",
"title": "Documenter.Utilities.DOM.flatten!"
},
{
"category": "method",
"location": "lib/internals/mdflatten/#Documenter.Utilities.MDFlatten.mdflatten-Tuple{Any}",
"page": "MDFlatten",
"text": "Convert a Markdown object to a String of only text (i.e. not formatting info).\n\nIt 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.\n\n\n\n\n\n",
"title": "Documenter.Utilities.MDFlatten.mdflatten"
},
{
"category": "method",
"location": "lib/internals/selectors/#Documenter.Utilities.Selectors.disable-Union{Tuple{T}, Tuple{Type{T}}} where T<:Documenter.Utilities.Selectors.AbstractSelector",
"page": "Selectors",
"text": "Disable a particular case in a selector so that it is never used.\n\nSelectors.disable(::Type{Debug}) = true\n\n\n\n\n\n",
"title": "Documenter.Utilities.Selectors.disable"
},
{
"category": "method",
"location": "lib/internals/selectors/#Documenter.Utilities.Selectors.dispatch-Union{Tuple{T}, Tuple{Type{T},Vararg{Any,N} where N}} where T<:Documenter.Utilities.Selectors.AbstractSelector",
"page": "Selectors",
"text": "Call Selectors.runner(T, args...) where T is a subtype of MySelector for which matcher(T, args...) is true.\n\nSelectors.dispatch(MySelector, args...)\n\n\n\n\n\n",
"title": "Documenter.Utilities.Selectors.dispatch"
},
{
"category": "method",
"location": "lib/internals/selectors/#Documenter.Utilities.Selectors.strict-Union{Tuple{T}, Tuple{Type{T}}} where T<:Documenter.Utilities.Selectors.AbstractSelector",
"page": "Selectors",
"text": "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.\n\n# Adding a debugging selector case.\nabstract type Debug <: MySelector end\n\n# Insert prior to all other cases.\nSelectors.order(::Type{Debug}) = 0.0\n\n# Fallthrough to the next case on success.\nSelectors.strict(::Type{Debug}) = false\n\n# We always match, regardless of the value of `x`.\nSelectors.matcher(::Type{Debug}, x) = true\n\n# Print some debugging info.\nSelectors.runner(::Type{Debug}, x) = @show x\n\n\n\n\n\n",
"title": "Documenter.Utilities.Selectors.strict"
},
{
"category": "method",
"location": "lib/internals/textdiff/#Documenter.Utilities.TextDiff.splitby-Tuple{Regex,AbstractString}",
"page": "TextDiff",
"text": "splitby(reg, text)\n\n\nSplits 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.\n\n\n\n\n\n",
"title": "Documenter.Utilities.TextDiff.splitby"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.assetsdir-Tuple{}",
"page": "Utilities",
"text": "Returns the path to the Documenter assets directory.\n\n\n\n\n\n",
"title": "Documenter.Utilities.assetsdir"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.check_kwargs-Tuple{Any}",
"page": "Utilities",
"text": "Prints a formatted warning to the user listing unrecognised keyword arguments.\n\n\n\n\n\n",
"title": "Documenter.Utilities.check_kwargs"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.currentdir-Tuple{}",
"page": "Utilities",
"text": "Returns the current directory.\n\n\n\n\n\n",
"title": "Documenter.Utilities.currentdir"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.doccat-Tuple{Documenter.Utilities.Object}",
"page": "Utilities",
"text": "Returns the category name of the provided Object.\n\n\n\n\n\n",
"title": "Documenter.Utilities.doccat"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.filterdocs-Tuple{Markdown.MD,Set{Module}}",
"page": "Utilities",
"text": "filterdocs(doc, modules)\n\nRemove docstrings from the markdown object, doc, that are not from one of modules.\n\n\n\n\n\n",
"title": "Documenter.Utilities.filterdocs"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.get_commit_short-Tuple{Any}",
"page": "Utilities",
"text": "get_commit_short(dir)\n\n\nReturns the first 5 characters of the current git commit hash of the directory dir.\n\n\n\n\n\n",
"title": "Documenter.Utilities.get_commit_short"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.isabsurl-Tuple{Any}",
"page": "Utilities",
"text": "isabsurl(url)\n\nChecks whether url is an absolute URL (as opposed to a relative one).\n\n\n\n\n\n",
"title": "Documenter.Utilities.isabsurl"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.issubmodule-Tuple{Any,Any}",
"page": "Utilities",
"text": "issubmodule(sub, mod)\n\nChecks whether sub is a submodule of mod. A module is also considered to be its own submodule.\n\nE.g. A.B.C is a submodule of A, A.B and A.B.C, but it is not a submodule of D, A.D nor A.B.C.D.\n\n\n\n\n\n",
"title": "Documenter.Utilities.issubmodule"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.mdparse-Tuple{AbstractString}",
"page": "Utilities",
"text": "mdparse(s::AbstractString; mode=:single)\n\nParses 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.\n\nThe mode keyword argument can be one of the following:\n\n:single (default) – returns a single block-level object (e.g. Markdown.Paragraph or Markdown.Admonition) and errors if the string parses into multiple blocks.\n:blocks – the function returns a Vector{Any} of Markdown blocks.\n: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.\n\n\n\n\n\n",
"title": "Documenter.Utilities.mdparse"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.nodocs-Tuple{Any}",
"page": "Utilities",
"text": "Does the given docstring represent actual documentation or a no docs error message?\n\n\n\n\n\n",
"title": "Documenter.Utilities.nodocs"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.object-Tuple{Union{Expr, Symbol},AbstractString}",
"page": "Utilities",
"text": "object(ex, str)\n\nReturns a expression that, when evaluated, returns an Object representing ex.\n\n\n\n\n\n",
"title": "Documenter.Utilities.object"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.parseblock-Tuple{AbstractString,Any,Any}",
"page": "Utilities",
"text": "Returns a vector of parsed expressions and their corresponding raw strings.\n\nReturns 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.\n\nThe keyword argument skip = N drops the leading N lines from the input string.\n\n\n\n\n\n",
"title": "Documenter.Utilities.parseblock"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.relpath_from_repo_root-Tuple{Any}",
"page": "Utilities",
"text": "relpath_from_repo_root(file)\n\n\nReturns the path of file, relative to the root of the Git repository, or nothing if the file is not in a Git repository.\n\n\n\n\n\n",
"title": "Documenter.Utilities.relpath_from_repo_root"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.repo_root-Tuple{Any}",
"page": "Utilities",
"text": "repo_root(file; dbdir=\".git\")\n\nTries to determine the root directory of the repository containing file. If the file is not in a repository, the function returns nothing.\n\nThe dbdir keyword argument specifies the name of the directory we are searching for to determine if this is a repostory or not. If there is a file called dbdir, then it's contents is checked under the assumption that it is a Git worktree.\n\n\n\n\n\n",
"title": "Documenter.Utilities.repo_root"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.slugify-Tuple{AbstractString}",
"page": "Utilities",
"text": "Slugify a string into a suitable URL.\n\n\n\n\n\n",
"title": "Documenter.Utilities.slugify"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.srcpath-Tuple{Any,Any,Any}",
"page": "Utilities",
"text": "Find the path of a file relative to the source directory. root is the path to the directory containing the file file.\n\nIt is meant to be used with walkdir(source).\n\n\n\n\n\n",
"title": "Documenter.Utilities.srcpath"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.submodules-Tuple{Array{Module,1}}",
"page": "Utilities",
"text": "Returns the set of submodules of a given root module/s.\n\n\n\n\n\n",
"title": "Documenter.Utilities.submodules"
},
{
"category": "method",
"location": "lib/internals/utilities/#Documenter.Utilities.withoutput-Tuple{Any}",
"page": "Utilities",
"text": "Call a function and capture all stdout and stderr output.\n\nwithoutput(f) --> (result, success, backtrace, output)\n\nwhere\n\nresult is the value returned from calling function f.\nsuccess signals whether f has thrown an error, in which case result stores the Exception that was raised.\nbacktrace a Vector{Ptr{Cvoid}} produced by catch_backtrace() if an error is thrown.\noutput is the combined output of stdout and stderr during execution of f.\n\n\n\n\n\n",
"title": "Documenter.Utilities.withoutput"
},
{
"category": "method",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.collect_subsections-Tuple{Documenter.Documents.Page}",
"page": "Writers",
"text": "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.\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.collect_subsections"
},
{
"category": "method",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.copy_asset-Tuple{Any,Any}",
"page": "Writers",
"text": "Copies an asset from Documenters assets/html/ directory to doc.user.build. Returns the path of the copied asset relative to .build.\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.copy_asset"
},
{
"category": "method",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.domify-Tuple{Any,Any}",
"page": "Writers",
"text": "Converts recursively a Documents.Page, Markdown or Documenter *Node objects into HTML DOM.\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.domify"
},
{
"category": "method",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.fixlinks!-Tuple{Any,Any,Markdown.Link}",
"page": "Writers",
"text": "Replaces URLs in Markdown.Link elements (if they point to a local .md page) with the actual URLs.\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.fixlinks!"
},
{
"category": "method",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.get_url-Tuple{Any,AbstractString}",
"page": "Writers",
"text": "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/.\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.get_url"
},
{
"category": "method",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.get_url-Tuple{Any,Documenter.Documents.NavNode}",
"page": "Writers",
"text": "Returns the full path of a Documents.NavNode relative to src/.\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.get_url"
},
{
"category": "method",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.getpage-Tuple{Any,Any}",
"page": "Writers",
"text": "Returns a page (as a Documents.Page object) using the HTMLContext.\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.getpage"
},
{
"category": "method",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.mdconvert-Tuple{Any}",
"page": "Writers",
"text": "Convert a markdown object to a DOM.Node object.\n\nThe parent argument is passed to allow for context-dependant conversions.\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.mdconvert"
},
{
"category": "method",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.navhref-Tuple{Any,Any,Any}",
"page": "Writers",
"text": "Get the relative hyperlink between two Documents.NavNodes. Assumes that both Documents.NavNodes have an associated Documents.Page (i.e. .page is not nothing).\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.navhref"
},
{
"category": "method",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.navitem-Tuple{Any,Any}",
"page": "Writers",
"text": "navitem returns the lists and list items of the navigation menu. It gets called recursively to construct the whole tree.\n\nIt 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(\"\")).\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.navitem"
},
{
"category": "method",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.open_output-Tuple{Any,Any,Any}",
"page": "Writers",
"text": "Opens the output file of the navnode in write node. If necessary, the path to the output file is created before opening the file.\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.open_output"
},
{
"category": "method",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.pagetitle-Tuple{Documenter.Documents.Page}",
"page": "Writers",
"text": "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).\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.pagetitle"
},
{
"category": "method",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.pretty_url-Tuple{Any,AbstractString}",
"page": "Writers",
"text": "If html_prettyurls is enabled, returns a \"pretty\" version of the path which can then be used in links in the resulting HTML file.\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.pretty_url"
},
{
"category": "method",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.relhref-Tuple{Any,Any}",
"page": "Writers",
"text": "Calculates a relative HTML link from one path to another.\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.relhref"
},
{
"category": "method",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.render_page-Tuple{Any,Any}",
"page": "Writers",
"text": "Constructs and writes the page referred to by the navnode to .build.\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.render_page"
},
{
"category": "method",
"location": "lib/internals/writers/#Documenter.Writers.render-Tuple{Documenter.Documents.Document}",
"page": "Writers",
"text": "Writes a Documents.Document object to .user.build directory in the formats specified in the .user.format vector.\n\nAdding additional formats requires adding new Selector definitions as follows:\n\nabstract type CustomFormat <: FormatSelector end\n\nSelectors.order(::Type{CustomFormat}) = 4.0 # or a higher number.\nSelectors.matcher(::Type{CustomFormat}, fmt, _) = fmt === :custom\nSelectors.runner(::Type{CustomFormat}, _, doc) = CustomWriter.render(doc)\n\n# Definition of `CustomWriter` module below...\n\n\n\n\n\n",
"title": "Documenter.Writers.render"
},
{
"category": "module",
"location": "lib/internals/anchors/#Documenter.Anchors",
"page": "Anchors",
"text": "Defines the Anchor and AnchorMap types.\n\nAnchors and AnchorMaps are used to represent links between objects within a document.\n\n\n\n\n\n",
"title": "Documenter.Anchors"
},
{
"category": "module",
"location": "lib/internals/builder/#Documenter.Builder",
"page": "Builder",
"text": "Defines the Documenter.jl build \"pipeline\" named DocumentPipeline.\n\nEach stage of the pipeline performs an action on a Documents.Document object. These actions may involve creating directory structures, expanding templates, running doctests, etc.\n\n\n\n\n\n",
"title": "Documenter.Builder"
},
{
"category": "module",
"location": "lib/internals/cross-references/#Documenter.CrossReferences",
"page": "CrossReferences",
"text": "Provides the crossref function used to automatically calculate link URLs.\n\n\n\n\n\n",
"title": "Documenter.CrossReferences"
},
{
"category": "module",
"location": "lib/internals/docchecks/#Documenter.DocChecks",
"page": "DocChecks",
"text": "Provides the missingdocs, footnotes and linkcheck functions for checking docs.\n\n\n\n\n\n",
"title": "Documenter.DocChecks"
},
{
"category": "module",
"location": "lib/internals/docsystem/#Documenter.DocSystem",
"page": "DocSystem",
"text": "Provides a consistent interface to retreiving DocStr objects from the Julia docsystem in both 0.4 and 0.5.\n\n\n\n\n\n",
"title": "Documenter.DocSystem"
},
{
"category": "module",
"location": "lib/internals/doctests/#Documenter.DocTests",
"page": "DocTests",
"text": "Provides the doctest function that makes sure that the jldoctest code blocks in the documents and docstrings run and are up to date.\n\n\n\n\n\n",
"title": "Documenter.DocTests"
},
{
"category": "module",
"location": "lib/internals/documentertools/#DocumenterTools.Generator",
"page": "DocumenterTools",
"text": "Provides the functions related to generating documentation stubs.\n\n\n\n\n\n",
"title": "DocumenterTools.Generator"
},
{
"category": "module",
"location": "lib/internals/documents/#Documenter.Documents",
"page": "Documents",
"text": "Defines Document and its supporting types\n\nPage\nUser\nInternal\nGlobals\n\n\n\n\n\n",
"title": "Documenter.Documents"
},
{
"category": "module",
"location": "lib/internals/dom/#Documenter.Utilities.DOM",
"page": "DOM",
"text": "Provides a domain specific language for representing HTML documents.\n\nExamples\n\nusing Documenter.Utilities.DOM\n\n# `DOM` does not export any HTML tags. Define the ones we actually need.\n@tags div p em strong ul li\n\ndiv(\n p(\"This \", em(\"is\"), \" a \", strong(\"paragraph.\"),\n p(\"And this is \", strong(\"another\"), \" one\"),\n ul(\n li(\"and\"),\n li(\"an\"),\n li(\"unordered\"),\n li(\"list\")\n )\n)\n\nNotes\n\nAll the arguments passed to a node are flattened into a single vector rather than preserving any nested structure. This means that passing two vectors of nodes to a div will result in a div node with a single vector of children (the concatenation of the two vectors) rather than two vector children. The only arguments that are not flattened are nested nodes.\n\nString arguments are automatically converted into text nodes. Text nodes do not have any children or attributes and when displayed the string is escaped using escapehtml.\n\nAttributes\n\nAs well as plain nodes shown in the previous example, nodes can have attributes added to them using the following syntax.\n\ndiv[\".my-class\"](\n img[:src => \"foo.jpg\"],\n input[\"#my-id\", :disabled]\n)\n\nIn the above example we add a class = \"my-class\" attribute to the div node, a src = \"foo.jpg\" to the img, and id = \"my-id\" disabled attributes to the input node.\n\nThe following syntax is supported within [...]:\n\ntag[\"#id\"]\ntag[\".class\"]\ntag[\".class#id\"]\ntag[:disabled]\ntag[:src => \"foo.jpg\"]\n# ... or any combination of the above arguments.\n\nInternal Representation\n\nThe @tags macro defines named Tag objects as follows\n\n@tags div p em strong\n\nexpands to\n\nconst div, p, em, strong = Tag(:div), Tag(:p), Tag(:em), Tag(:strong)\n\nThese 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.\n\ntag(...) # No attributes.\ntag[...] # No children.\ntag[...](...) # Has both attributes and children.\n\nAll 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 nessesary text escaped.\n\n\n\n\n\n",
"title": "Documenter.Utilities.DOM"
},
{
"category": "module",
"location": "lib/internals/expanders/#Documenter.Expanders",
"page": "Expanders",
"text": "Defines node \"expanders\" that transform nodes from the parsed markdown files.\n\n\n\n\n\n",
"title": "Documenter.Expanders"
},
{
"category": "module",
"location": "lib/internals/mdflatten/#Documenter.Utilities.MDFlatten",
"page": "MDFlatten",
"text": "Provides the mdflatten function that can \"flatten\" Markdown objects into a string, with formatting etc. stripped.\n\nNote that the tests in test/mdflatten.jl should be considered to be the spec for the output (number of newlines, indents, formatting, etc.).\n\n\n\n\n\n",
"title": "Documenter.Utilities.MDFlatten"
},
{
"category": "module",
"location": "lib/internals/selectors/#Documenter.Utilities.Selectors",
"page": "Selectors",
"text": "An extensible code selection interface.\n\nThe Selectors module provides an extensible way to write code that has to dispatch on different predicates without hardcoding the control flow into a single chain of if statements.\n\nIn the following example a selector for a simple condition is implemented and the generated selector code is described:\n\nabstract type MySelector <: Selectors.AbstractSelector end\n\n# The different cases we want to test.\nabstract type One <: MySelector end\nabstract type NotOne <: MySelector end\n\n# The order in which to test the cases.\nSelectors.order(::Type{One}) = 0.0\nSelectors.order(::Type{NotOne}) = 1.0\n\n# The predicate to test against.\nSelectors.matcher(::Type{One}, x) = x === 1\nSelectors.matcher(::Type{NotOne}, x) = x !== 1\n\n# What to do when a test is successful.\nSelectors.runner(::Type{One}, x) = println(\"found one\")\nSelectors.runner(::Type{NotOne}, x) = println(\"not found\")\n\n# Test our selector with some numbers.\nfor i in 0:5\n Selectors.dispatch(MySelector, i)\nend\n\nSelectors.dispatch(Selector, i) will behave equivalent to the following:\n\nfunction dispatch(::Type{MySelector}, i::Int)\n if matcher(One, i)\n runner(One, i)\n elseif matcher(NotOne, i)\n runner(NotOne, i)\n end\nend\n\nand further to\n\nfunction dispatch(::Type{MySelector}, i::Int)\n if i === 1\n println(\"found one\")\n elseif i !== 1\n println(\"not found\")\n end\nend\n\nThe module provides the following interface for creating selectors:\n\norder\nmatcher\nrunner\nstrict\ndisable\ndispatch\n\n\n\n\n\n",
"title": "Documenter.Utilities.Selectors"
},
{
"category": "module",
"location": "lib/internals/utilities/#Documenter.Utilities",
"page": "Utilities",
"text": "Provides a collection of utility functions and types that are used in other submodules.\n\n\n\n\n\n",
"title": "Documenter.Utilities"
},
{
"category": "module",
"location": "lib/internals/writers/#Documenter.Writers",
"page": "Writers",
"text": "A module that provides several renderers for Document objects. The supported formats are currently:\n\n:markdown – the default format.\n:html – generates a complete HTML site with navigation and search included.\n:latex – generates a PDF using LuaLaTeX.\n\n\n\n\n\n",
"title": "Documenter.Writers"
},
{
"category": "module",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter",
"page": "Writers",
"text": "A module for rendering Document objects to HTML.\n\nKeywords\n\nHTMLWriter 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_branch and prettyurls.\n\nsitename is the site's title displayed in the title bar and at the top of the *navigation menu. This argument is mandatory for HTMLWriter.\n\npages defines the hierarchy of the navigation menu.\n\nExperimental keywords\n\nversion 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.\n\nHTML Plugin options\n\nThe HTML Documenter.Plugin provides additional customization options for the HTMLWriter. For more information, see the HTML documentation.\n\nPage outline\n\nThe 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:\n\nIt is then used to automatically determine the page title in the navigation menu and in the <title> tag, unless specified in the .pages option.\nIf the first heading is interpreted as being the page title, it is not displayed in the navigation sidebar.\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter"
},
{
"category": "module",
"location": "lib/internals/writers/#Documenter.Writers.LaTeXWriter",
"page": "Writers",
"text": "A module for rendering Document objects to LaTeX and PDF.\n\nKeywords\n\nLaTeXWriter uses the following additional keyword arguments that can be passed to Documenter.makedocs: authors, sitename.\n\nsitename 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.\n\nauthors can be used to specify the authors of. It goes into the \\author LaTeX command.\n\n\n\n\n\n",
"title": "Documenter.Writers.LaTeXWriter"
},
{
"category": "module",
"location": "lib/internals/writers/#Documenter.Writers.MarkdownWriter",
"page": "Writers",
"text": "A module for rendering Document objects to markdown.\n\n\n\n\n\n",
"title": "Documenter.Writers.MarkdownWriter"
},
{
"category": "module",
"location": "lib/public/#Documenter",
"page": "Public",
"text": "Main module for Documenter.jl – a documentation generation package for Julia.\n\nTwo functions are exported from this module for public use:\n\nmakedocs. Generates documentation from docstrings and templated markdown files.\ndeploydocs. Deploys generated documentation from Travis-CI to GitHub Pages.\n\nExports\n\nDeps\ndeploydocs\nhide\nmakedocs\n\n\n\n\n\n",
"title": "Documenter"
},
{
"category": "module",
"location": "lib/public/#Documenter.Deps",
"page": "Public",
"text": "Exported module that provides build and deploy dependencies and related functions.\n\nCurrently only pip is implemented.\n\n\n\n\n\n",
"title": "Documenter.Deps"
},
{
"category": "module",
"location": "lib/public/#DocumenterTools.Travis",
"page": "Public",
"text": "Package functions for interacting with Travis.\n\ngenkeys\n\n\n\n\n\n",
"title": "DocumenterTools.Travis"
},
{
"category": "page",
"location": "#",
"page": "Home",
"text": "A documentation generator for Julia.",
"title": "Home"
},
{
"category": "page",
"location": "#",
"page": "Home",
"text": "A package for building documentation from docstrings and markdown files.",
"title": "Home"
},
{
"category": "page",
"location": "#",
"page": "Home",
"text": "Pages = [\"lib/public.md\", \"lib/internals.md\"]",
"title": "Home"
},
{
"category": "page",
"location": "#",
"page": "Home",
"text": "Pages = [\"lib/public.md\"]",
"title": "Home"
},
{
"category": "page",
"location": "#",
"page": "Home",
"text": "Pages = [\n \"man/guide.md\",\n \"man/examples.md\",\n \"man/syntax.md\",\n \"man/doctests.md\",\n \"man/hosting.md\",\n \"man/latex.md\",\n \"man/contributing.md\",\n]\nDepth = 1",
"title": "Home"
},
{
"category": "page",
"location": "#",
"page": "Home",
"text": "See the Index for the complete list of documented functions and types.",
"title": "Home"
},
{
"category": "page",
"location": "#",
"page": "Home",
"text": "Some examples of packages using Documenter can be found on the Examples page.",
"title": "Home"
},
{
"category": "page",
"location": "#",
"page": "Home",
"text": "The Package Guide provides a tutorial explaining how to get started using Documenter.",
"title": "Home"
},
{
"category": "page",
"location": "#",
"page": "Home",
"text": "Write all your documentation in Markdown.\nMinimal configuration.\nSupports Julia 0.7 and 1.0.\nDoctests Julia code blocks.\nCross references for docs and section headers.\nLaTeX syntax support.\nChecks for missing docstrings and incorrect cross references.\nGenerates tables of contents and docstring indexes.\nAutomatically builds and deploys docs from Travis to GitHub Pages.",
"title": "Home"
},
{
"category": "page",
"location": "#",
"page": "Home",
"text": "note: Note\nPlease 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.",
"title": "Home"
},
{
"category": "page",
"location": "contributing/#",
"page": "Contributing",
"text": "4-space indentation;\nmodules spanning entire files should not be indented, but modules that have surrounding code should;\nno blank lines at the start or end of files;\ndo not manually align syntax such as = or :: over adjacent lines;\nuse function ... end when a method definition contains more than one toplevel expression;\nrelated short-form method definitions don't need a new line between them;\nunrelated or long-form method definitions must have a blank line separating each one;\nsurround all binary operators with whitespace except for ::, ^, and :;\nfiles containing a single module ... end must be named after the module;\nmethod arguments should be ordered based on the amount of usage within the method body;\nmethods extended from other modules must follow their inherited argument order, not the above rule;\nexplicit return should be preferred except in short-form method definitions;\navoid dense expressions where possible e.g. prefer nested ifs over complex nested ?s;\ninclude a trailing , in vectors, tuples, or method calls that span several lines;\ndo not use multiline comments (#= and =#);\nwrap long lines as near to 92 characters as possible, this includes docstrings;\nfollow the standard naming conventions used in Base.",
"title": "Contributing"
},
{
"category": "page",
"location": "contributing/#",
"page": "Contributing",
"text": "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.",
"title": "Contributing"
},
{
"category": "page",
"location": "contributing/#",
"page": "Contributing",
"text": "Each new minor version x.y.0 gets a branch called release-x.y (a protected branch).\nNew versions are usually tagged only from the release-x.y branches.\nFor 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).\nThe old release-* branches may be removed once they have outlived their usefulness.\nPatch version milestones are used to keep track of which PRs get backported etc.",
"title": "Contributing"
},
{
"category": "page",
"location": "contributing/#",
"page": "Contributing",
"text": "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.",
"title": "Contributing"
},
{
"category": "page",
"location": "contributing/#",
"page": "Contributing",
"text": "Follow the style of the surrounding text when making changes. When adding new features please try to stick to the following points whenever applicable.",
"title": "Contributing"
},
{
"category": "page",
"location": "contributing/#",
"page": "Contributing",
"text": "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.",
"title": "Contributing"
},
{
"category": "page",
"location": "contributing/#",
"page": "Contributing",
"text": "Please open pull requests against the master branch rather than any of the release-* branches whenever possible.",
"title": "Contributing"
},
{
"category": "page",
"location": "contributing/#",
"page": "Contributing",
"text": "This page details the some of the guidelines that should be followed when contributing to this package.",
"title": "Contributing"
},
{
"category": "page",
"location": "contributing/#",
"page": "Contributing",
"text": "Use unbalanced # headers, i.e. no # on the right hand side of the header text;\ninclude a single blank line between toplevel blocks;\nunordered lists must use * bullets with two preceding spaces;\ndo not hard wrap lines;\nuse emphasis (*) and bold (**) sparingly;\nalways use fenced code blocks instead of indented blocks;\nfollow the conventions outlined in the Julia documentation page on documentation.",
"title": "Contributing"
},
{
"category": "page",
"location": "lib/internals/#",
"page": "Internals",
"text": "A list of all internal documentation sorted by module.",
"title": "Internals"
},
{
"category": "page",
"location": "lib/internals/#",
"page": "Internals",
"text": "Pages = [joinpath(\"internals\", f) for f in readdir(\"internals\")]",
"title": "Internals"
},
{
"category": "page",
"location": "lib/internals/#",
"page": "Internals",
"text": "Pages = [joinpath(\"internals\", f) for f in readdir(\"internals\")]",
"title": "Internals"
},
{
"category": "page",
"location": "lib/internals/#",
"page": "Internals",
"text": "This page lists all the documented internals of the Documenter module and submodules.",
"title": "Internals"
},
{
"category": "page",
"location": "lib/internals/anchors/#",
"page": "Anchors",
"text": "Modules = [Documenter.Anchors]",
"title": "Anchors"
},
{
"category": "page",
"location": "lib/internals/builder/#",
"page": "Builder",
"text": "Modules = [Documenter.Builder]",
"title": "Builder"
},
{
"category": "page",
"location": "lib/internals/cross-references/#",
"page": "CrossReferences",
"text": "Modules = [Documenter.CrossReferences]",
"title": "CrossReferences"
},
{
"category": "page",
"location": "lib/internals/docchecks/#",
"page": "DocChecks",
"text": "Modules = [Documenter.DocChecks]",
"title": "DocChecks"
},
{
"category": "page",
"location": "lib/internals/docsystem/#",
"page": "DocSystem",
"text": "Modules = [Documenter.DocSystem]",
"title": "DocSystem"
},
{
"category": "page",
"location": "lib/internals/doctests/#",
"page": "DocTests",
"text": "Modules = [Documenter.DocTests]",
"title": "DocTests"
},
{
"category": "page",
"location": "lib/internals/documenter/#",
"page": "Documenter",
"text": "Documenter.gitrm_copy\nDocumenter.git_push",
"title": "Documenter"
},
{
"category": "page",
"location": "lib/internals/documentertools/#",
"page": "DocumenterTools",
"text": "DocumenterTools.package_devpath",
"title": "DocumenterTools"
},
{
"category": "page",
"location": "lib/internals/documentertools/#",
"page": "DocumenterTools",
"text": "Modules = [DocumenterTools.Generator]",
"title": "DocumenterTools"
},
{
"category": "page",
"location": "lib/internals/documents/#",
"page": "Documents",
"text": "Modules = [Documenter.Documents]",
"title": "Documents"
},
{
"category": "page",
"location": "lib/internals/dom/#",
"page": "DOM",
"text": "Modules = [Documenter.Utilities.DOM]",
"title": "DOM"
},
{
"category": "page",
"location": "lib/internals/expanders/#",
"page": "Expanders",
"text": "Modules = [Documenter.Expanders]",
"title": "Expanders"
},
{
"category": "page",
"location": "lib/internals/mdflatten/#",
"page": "MDFlatten",
"text": "Modules = [Documenter.Utilities.MDFlatten]",
"title": "MDFlatten"
},
{
"category": "page",
"location": "lib/internals/selectors/#",
"page": "Selectors",
"text": "Modules = [Documenter.Selectors]",
"title": "Selectors"
},
{
"category": "page",
"location": "lib/internals/textdiff/#",
"page": "TextDiff",
"text": "Modules = [Documenter.Utilities.TextDiff]",
"title": "TextDiff"
},
{
"category": "page",
"location": "lib/internals/utilities/#",
"page": "Utilities",
"text": "Modules = [Documenter.Utilities]",
"title": "Utilities"
},
{
"category": "page",
"location": "lib/internals/writers/#",
"page": "Writers",
"text": "Documenter.Plugin",
"title": "Writers"
},
{
"category": "page",
"location": "lib/internals/writers/#",
"page": "Writers",
"text": "Modules = [\n Documenter.Writers,\n Documenter.Writers.MarkdownWriter,\n Documenter.Writers.HTMLWriter,\n Documenter.Writers.LaTeXWriter,\n]",
"title": "Writers"
},
{
"category": "page",
"location": "lib/public/#",
"page": "Public",
"text": "Documentation for Documenter.jl's public interface.",
"title": "Public"
},
{
"category": "page",
"location": "lib/public/#",
"page": "Public",
"text": "DocumenterTools.generate\nDocumenterTools.Travis.genkeys\nDocumenterTools.Travis",
"title": "Public"
},
{
"category": "page",
"location": "lib/public/#",
"page": "Public",
"text": "Documenter\nmakedocs\nhide\ndeploydocs\nDeps\nDeps.pip",
"title": "Public"
},
{
"category": "page",
"location": "lib/public/#",
"page": "Public",
"text": "Pages = [\"public.md\"]",
"title": "Public"
},
{
"category": "page",
"location": "lib/public/#",
"page": "Public",
"text": "Pages = [\"public.md\"]",
"title": "Public"
},
{
"category": "page",
"location": "lib/public/#",
"page": "Public",
"text": "See Internal Documentation for internal package docs covering all submodules.",
"title": "Public"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "A filter takes the form of a regular expression. In a doctest, each match in the expected output and the actual output is removed before the two outputs are compared. Filters are added globally, i.e. applied to all doctests in the documentation, by passing a list of regular expressions to makedocs with the keyword doctestfilters.",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "A part of the output of a doctest might be non-deterministic, e.g. pointer addresses and timings. It is therefore possible to filter a doctest so that the deterministic part can still be tested.",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "An example is given below where some of the non-deterministic output from @time is filtered.",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "Another option is to use the filter keyword argument. This defines a doctest-local filter which is only active for the specific doctest. Note that such filters are not shared between named doctests either. It is possible to define a filter by a single regex (filter = r\"foo\") or as a list of regex (filter = [r\"foo\", r\"bar\"]). Example:",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "Another option is to use the setup keyword argument, which is convenient for short definitions, and for setups needed in inline docstrings.",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "As with script doctests, the code block must have it's language set to jldoctest. When a code block contains one or more julia> at the start of a line then it is assumed to be a REPL doctest. Semi-colons, ;, at the end of a line works in the same way as in the Julia REPL and will suppress the output, although the line is still evaluated.",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "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.",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "Doctests can also test for thrown exceptions and their stacktraces. Comparing of the actual and expected results is done by checking whether the expected result matches the start of the actual result. Hence, both of the following errors will match the actual result.",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "Doctests may require some setup code that must be evaluated prior to that of the actual example, but that should not be displayed in the final documentation. For this purpose a @meta block containing a DocTestSetup = ... value can be used. In the example below, the function foo is defined inside a @meta block. This block will be evaluated at the start of the following doctest blocks:",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "Documenter will, by default, try to run jldoctest code blocks that it finds in the generated documentation. This can help to avoid documentation examples from becoming outdated, incorrect, or misleading. It's recommended that as many of a package's examples be runnable by Documenter's doctest.",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "Every doctest block is evaluated inside its own module. This means that definitions (types, variables, functions etc.) from a block can not be used in the next block. For example:",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "For more fine grained control it is possible to define filters in @meta blocks by assigning them to the DocTestFilters variable, either as a single regular expression (DocTestFilters = [r\"foo\"]) or as a vector of several regex (DocTestFilters = [r\"foo\", r\"bar\"]).",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "If instead the first div(1, 0) error was written as",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "In the second div(1, 0), where no stacktrace is shown, it may appear to the reader that it is expected that no stacktrace will actually be displayed when they attempt to try to recreate the error themselves. To indicate to readers that the output result is truncated and does not display the entire (or any of) the stacktrace you may write [...] at the line where checking should stop, i.e.",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "It is possible to suppress the output from the doctest by setting the output keyword argument to false, for example",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "Note that not all features of the REPL are supported such as shell and help modes.",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "Note that the amount of whitespace appearing above and below the # output line is not significant and can be increased or decreased if desired.",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "Note that the output of the script will still be compared to the expected result, i.e. what is # output section, but the # output section will be suppressed in the rendered documentation.",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "Now, since the block below has the same label as the block above, the variable foo can be used:",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "The DocTestFilters = nothing is not strictly necessary, but good practice nonetheless to help avoid unintentional filtering in following doctest blocks.",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "The DocTestSetup = nothing is not strictly necessary, but good practice nonetheless to help avoid unintentional definitions in following doctest blocks.",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "The actual output produced by running the \"script\" is compared to the expected result and any difference will result in makedocs throwing an error and terminating.",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "The code block's \"language\" must be jldoctest and must include a line containing the text # output. The text before this line is the contents of the script which is run. The text that appears after # output is the textual representation that would be shown in the Julia REPL if the script had been included.",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "The first, of two, types of doctests is the \"script\" code block. To make Documenter detect this kind of code block the following format must be used:",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "The other kind of doctest is a simulated Julia REPL session. The following format is detected by Documenter as a REPL doctest:",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "The variable foo will not be defined in the next block:",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "This section of the manual outlines how to go about enabling doctests for code blocks in your package's documentation.",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "To fix outdated doctests, the doctest flag to makedocs can be set to doctest = :fix. This will run the doctests, and overwrite the old results with the new output.",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "To preserve definitions it is possible to label blocks in order to collect several blocks into the same module. All blocks with the same label (in the same file) will be evaluated in the same module, and hence share scope. This can be useful if the same definitions are used in more than one block, with for example text, or other doctest blocks, in between. Example:",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "```@meta\nDocTestFilters = r\"[0-9\\.]+ seconds \\(.*\\)\"\n```\n\n```jldoctest\njulia> @time [1,2,3,4]\n 0.000003 seconds (5 allocations: 272 bytes)\n4-element Array{Int64,1}:\n 1\n 2\n 3\n 4\n```\n\n```@meta\nDocTestFilters = nothing\n```",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "```@meta\nDocTestSetup = quote\n function foo(x)\n return x^2\n end\nend\n```\n\n```jldoctest\njulia> foo(2)\n4\n```\n\n```@meta\nDocTestSetup = nothing\n```",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "```jldoctest mylabel\njulia> foo = 42\n42\n```",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "```jldoctest mylabel\njulia> println(foo)\n42\n```",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "```jldoctest; filter = r\"[0-9\\.]+ seconds \\(.*\\)\"\njulia> @time [1,2,3,4]\n 0.000003 seconds (5 allocations: 272 bytes)\n4-element Array{Int64,1}:\n 1\n 2\n 3\n 4\n```",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "```jldoctest; output = false\na = 1\nb = 2\na + b\n\n# output\n\n3\n```",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "```jldoctest; setup = :(foo(x) = x^2)\njulia> foo(2)\n4\n```",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "```jldoctest\na = 1\nb = 2\na + b\n\n# output\n\n3\n```",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "```jldoctest\njulia> a = 1\n1\n\njulia> b = 2;\n\njulia> c = 3; # comment\n\njulia> a + b + c\n6\n```",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "```jldoctest\njulia> div(1, 0)\nERROR: DivideError: integer division error\n in div(::Int64, ::Int64) at ./int.jl:114\n```",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "```jldoctest\njulia> div(1, 0)\nERROR: DivideError: integer division error\n in div(::Int64, ::Int64) at ./int.jl:115\n\njulia> div(1, 0)\nERROR: DivideError: integer division error\n```",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "```jldoctest\njulia> div(1, 0)\nERROR: DivideError: integer division error\n[...]\n```",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "```jldoctest\njulia> foo = 42\n42\n```",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "```jldoctest\njulia> println(foo)\nERROR: UndefVarError: foo not defined\n```",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "note: Note\nIf you rely on setup-code for doctests inside docstrings, included in the document with @docs or @autodocs, the @meta block must be in the markdown file that calls these macros and not within the docstrings themselves, otherwise they will be ignored.",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "note: Note\nIt is recommended to git commit any code changes before running the doctest fixing. That way it is simple to restore to the previous state if the fixing goes wrong.",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "note: Note\nLabeled doctest blocks does not need to be consecutive (as in the example above) to be included in the same module. They can be interspaced with unlabeled blocks or blocks with another label.",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "note: Note\nThe :fix option currently only works for LF line endings ('\\n')",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "note: Note\nThe DocTestSetup and the setup values are re-evaluated at the start of each doctest block and no state is shared between any code blocks. To preserve definitions see Preserving Definitions Between Blocks.",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "note: Note\nThe global filters, filters defined in @meta blocks, and filters defined with the filter keyword argument are all applied to each doctest.",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "note: Note\nThere are some corner cases where the fixing algorithm may replace the wrong code snippet. It is therefore recommended to manually inspect the result of the fixing before committing.",
"title": "Doctests"
},
{
"category": "page",
"location": "man/doctests/#",
"page": "Doctests",
"text": "where line 115 is replaced with 114 then the doctest will fail.",
"title": "Doctests"
},
{
"category": "page",
"location": "man/examples/#",
"page": "Examples",
"text": "Augmentor.jl\nBanditOpt.jl\nBeaData.jl\nBio.jl\nControlSystems.jl\nCurrencies.jl\nDiscretePredictors.jl\nDocumenter.jl\nEvolvingGraphs.jl\nExtractMacro.jl\nEzXML.jl\nFourierFlows.jl\nGadfly.jl\nGeoStats.jl\nHighlights.jl\nIntervalConstraintProgramming.jl\nLuxor.jl\nMergedMethods.jl\nMimi.jl\nNumericSuffixes.jl\nNLOptControl.jl\nOhMyREPL.jl\nOnlineStats.jl\nPOMDPs.jl\nPhyloNetworks.jl\nPrivateModules.jl\nQuery.jl\nTaylorSeries.jl\nWeave.jl",
"title": "Examples"
},
{
"category": "page",
"location": "man/examples/#",
"page": "Examples",
"text": "DifferentialEquations.jl\nJuliaDocs landing page\nJuliaMusic\nPlots.jl",
"title": "Examples"
},
{
"category": "page",
"location": "man/examples/#",
"page": "Examples",
"text": "Packages that have tagged versions available in METADATA.jl.",
"title": "Examples"
},
{
"category": "page",
"location": "man/examples/#",
"page": "Examples",
"text": "Some projects or organizations maintain dedicated documentation repositories that are separate from specific packages.",
"title": "Examples"
},
{
"category": "page",
"location": "man/examples/#",
"page": "Examples",
"text": "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.",
"title": "Examples"
},
{
"category": "page",
"location": "man/examples/#",
"page": "Examples",
"text": "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.",
"title": "Examples"
},
{
"category": "page",
"location": "man/examples/#",
"page": "Examples",
"text": "note: Note\nPackages 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.",
"title": "Examples"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "# Example.jl Documentation\n\n```@contents\n```\n\n## Functions\n\n```@docs\nfunc(x)\n```\n\n## Index\n\n```@index\n```",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "# Example.jl Documentation\n\n```@docs\nfunc(x)\n```",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "# Example.jl Documentation\n\n```@docs\nfunc(x)\n```\n\n- link to [Example.jl Documentation](@ref)\n- link to [`func(x)`](@ref)",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "# Example.jl Documentation\n\n```@meta\nCurrentModule = Example\n```\n\n```@docs\nfunc(x)\n```",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "$ julia --color=yes make.jl",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "$ julia make.jl",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "Add the following to your make.jl file",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "At this point build/index.html should be an empty page since src/index.md is empty. You can try adding some text to src/index.md and re-running the make.jl file to see the changes.",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "By default all the pages (.md files) in your source directory get added to the sidebar, sorted by their filenames. However, in most cases you want to use the pages argument to makedocs to control how the sidebar looks like. The basic usage is as follows:",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "Documenter can auto-generate tables of contents and docstring indexes for your document with the following syntax. We'll illustrate these features using our index.md file from the previous sections. Add the following to that file",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "Documenter can be installed using the Julia package manager. From the Julia REPL, type ] to enter the Pkg REPL mode and run",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "Documenter is designed to do one thing – combine markdown files and inline docstrings from Julia's docsystem into a single inter-linked document. What follows is a step-by-step guide to creating a simple document.",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "Documenter: setting up build directory.\nDocumenter: expanding markdown templates.\nDocumenter: building cross-references.\nDocumenter: running document checks.\n > checking for missing docstrings.\n > running doctests.\n > checking footnote links.\nDocumenter: populating indices.\nDocumenter: rendering document.",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "Example/\n docs/\n ...\n src/\n Example.jl\n ...",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "Example/\n src/\n Example.jl\n ...",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "Firstly, we need a Julia module to document. This could be a package generated via PkgDev.generate or a single .jl script accessible via Julia's LOAD_PATH. For this guide we'll be using a package called Example.jl that has the following directory layout:",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "If you'd like to see the output from this command in color use",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "In some cases you may want to include a docstring for a Method that extends a Function from a different module – such as Base. In the following example we extend Base.length with a new definition for the struct T and also add a docstring:",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "Inside the docs/ folder we need to add two things. A source folder which will contain the markdown files that will be used to build the finished document and a Julia script that will be used to control the build process. The following names are recommended",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "It may be necessary to refer to a particular docstring or section of your document from elsewhere in the document. To do this we can make use of Documenter's cross-referencing syntax which looks pretty similar to normal markdown link syntax. Replace the contents of src/index.md with the following",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "Leave the newly added file empty and then run the following command from the docs/ directory",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "Next we'll splice a docstring defined in the Example module into the index.md file. To do this first document a function in that module:",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "Note that $ just represents the prompt character. You don't need to type that.",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "Note that a @docs block is evaluated in the Main module. This means that each object listed in the block must be visible there. The module can be changed to something else on a per-page basis with a @meta block as in the following",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "Note that the ... just represent unimportant files and folders.",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "Now add an index.md file to the src/ directory.",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "So we just have to replace each link's url with @ref and write the name of the thing we'd link to cross-reference. For document headers it's just plain text that matches the name of the header and for docstrings enclose the object in backticks.",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "The @contents block will generate a nested list of links to all the section headers in the document. By default it will gather all the level 1 and 2 headers from every page in the document, but this can be adjusted using Pages and Depth settings as in the following",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "The @index block will generate a flat list of links to all the docs that that have been spliced into the document using @docs blocks. As with the @contents block the pages to be included can be set with a Pages = [...] line. Since the list is not nested Depth is not supported for @index.",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "The docs/ folder should contain a new directory – called build/. It's structure should look like the following",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "Then in the src/index.md file add the following",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "This also works across different pages in the same way. Note that these sections and docstrings must be unique within a document.",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "This assumes you've installed Documenter as discussed in Installation and that your Example.jl package can be found by Julia.",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "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.",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "We must decide on a location where we'd like to store the documentation for this package. It's recommended to use a folder named docs/ in the toplevel of the package, like so",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "When trying to include this docstring with",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "When we next run make.jl the docstring for Example.func(x) should appear in place of the @docs block in build/index.md. Note that more than one object can be referenced inside a @docs block – just place each one on a separate line.",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "When you run that you should see the following output",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "With our docs/ directory now setup we're going to build our first document. It'll just be a single empty file at the moment, but we'll be adding to it later on.",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "```@contents\nPages = [\"foo.md\", \"bar.md\"]\nDepth = 3\n```",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "```@docs\nlength(::T)\n```",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "```@docs\nlength\n```",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "all the docs for length will be included – even those from other modules. There are two ways to solve this problem. Either include the type in the signature with",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "build/\n assets/\n arrow.svg\n documenter.css\n documenter.js\n search.js\n index.html\n search/index.html\n search_index.js",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "docs/\n src/\n make.jl",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "makedocs(\n # options\n modules = [MyModule]\n)",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "makedocs(\n ...,\n pages = [\n \"page.md\",\n \"Page title\" => \"page2.md\",\n \"Subsection\" => [\n ...\n ]\n ]\n)",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "module Example\n\nexport func\n\n\"\"\"\n func(x)\n\nReturns double the number `x` plus `1`.\n\"\"\"\nfunc(x) = 2x + 1\n\nend",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "note: Note\nBy default, Documenter has pretty URLs enabled, which means that src/foo.md is turned into src/foo/index.html, instead of simply src/foo.html, which is the preferred way when creating a set of HTML to be hosted on a web server.However, this can be a hindrance when browsing the documentation locally as browsers do not resolve directory URLs like foo/ to foo/index.html for local files. You have two options:You can run a local web server out of the docs/build directory. If you have Python installed, you can simple start one with python3 -m http.server --bind localhost (or python -m SimpleHTTPServer with Python 2).\nYou can disable the pretty URLs feature by passing prettyurls = false with the Documenter.HTML plugin:\nmakedocs(..., format = Documenter.HTML(prettyurls = false))\nAlternatively, if your goal is to eventually set up automatic documentation deployment with Travis CI (see Hosting Documentation), you can also use their environment variables to determine Documenter's behavior in make.jl on the fly:\nmakedocs(...,\n format = Documenter.HTML(\n prettyurls = get(ENV, \"CI\", nothing) == \"true\"\n )\n)",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "note: Note\nIf you use Documenter's default HTML output the name index.md is mandatory. This file will be the main page of the rendered HTML documentation.",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "note: Note\nIf your source directory is not accessible through Julia's LOAD_PATH, you might wish to add the following line at the top of make.jlpush!(LOAD_PATH,\"../src/\")",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "note: Note\nThe function DocumenterTools.generate from the DocumenterTools package can generate the basic structure that Documenter expects.",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "or declare the specific modules that makedocs should include with",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "pkg> add Documenter",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "struct T\n # ...\nend\n\n\"\"\"\nCustom `length` docs for `T`.\n\"\"\"\nBase.length(::T) = 1",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "using Documenter, Example\n\nmakedocs(sitename=\"My Documentation\")",
"title": "Guide"
},
{
"category": "page",
"location": "man/guide/#",
"page": "Guide",
"text": "warning: Warning\nNever git commit the contents of build (or any other content generated by Documenter) to your repository's master branch. Always commit generated files to the gh-pages branch of your repository. This helps to avoid including unnecessary changes for anyone reviewing commits that happen to include documentation changes.See the Hosting Documentation section for details regarding how you should go about setting this up correctly.",
"title": "Guide"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "Add the following to your package's .gitignore file",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "Add the public ssh key to your settings page for the GitHub repository that you are setting up by following the .../settings/key link provided. Click on Add deploy key, enter the name documenter as the title, and copy the public key into the Key field. Check Allow write access to allow Documenter to commit the generated documentation to the repo.\nNext add the long private key to the Travis settings page using the provided link. Again note that you should include no whitespace when copying the key. In the Environment Variables section add a key with the name DOCUMENTER_KEY and the value that was printed out. Do not set the variable to be displayed in the build log. Then click Add.\nwarning: Security warning\nTo 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.",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "After going through the Package Guide and Doctests page you will need to host the generated documentation somewhere for potential users to read. This guide will describe how to setup automatic updates for your package docs using the Travis build service and GitHub Pages. This is the same approach used by this package to host its own docs – the docs you're currently reading.",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "At the moment your docs/make.jl file probably only contains",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "By default Documenter will create a link called stable that points to the latest release",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "By default, Documenter pushes documentation to the gh-pages branch. If the branch does not exist it will be created automatically by deploydocs. If does exist then Documenter simply adds an additional commit with the built documentation. You should be aware that Documenter may overwrite existing content without warning.",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "Deploy keys provide push access to a single repository, to allow secure deployment of generated documentation from Travis to GitHub. The SSH keys can be generated with the Travis.genkeys from the DocumenterTools package.",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "Documentation built for a tag vX.Y.Z will be stored in a folder vX.Y.Z.\nDocumentation built from the devbranch branch (master by default) is stored a folder determined by the devurl keyword to deploydocs (dev by default).",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "Final Remarks",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "Follow the instructions that are printed out, namely:",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "INFO: add the public key below to https://github.com/USER/REPO/settings/keys\n with read/write access:\n\n[SSH PUBLIC KEY HERE]\n\nINFO: add a secure environment variable named 'DOCUMENTER_KEY' to\n https://travis-ci.org/USER/REPO/settings with value:\n\n[LONG BASE64 ENCODED PRIVATE KEY]",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "If the package is checked out in development mode with ] dev MyPackage, you can also use Travis.genkeys as follows:",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "If you wish to create the gh-pages branch manually the that can be done following these instructions.",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "If you would like to see a more complete example of how this process is setup then take a look at this package's repository for some inspiration.",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "Install and load DocumenterTools with",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "Instantiate the doc-building environment (i.e. docs/Project.toml, see below).\nInstall your package in the doc-build environment.\nRun the docs/make.jl script, which builds and deploys the documentation.",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "It is recommended to use this link, rather then the versioned links, since it will be updated with new releases.",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "Note that it is recommended that you have a [compat] section, like the one above, in your Project.toml file, which would restrict Documenter's version that gets installed when the build runs. This is to make sure that your builds do not start failing suddenly due to a new major release of Documenter, which may include breaking changes. However, it also means that you will not get updates to Documenter automatically, and hence need to upgrade Documenter's major version yourself.",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "Note that the hosted documentation does not update when you make pull requests; you see updates only when you merge to master or push new tags.",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "Once set up correctly, the following will happen each time you push new updates to your package repository:",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "Once your documentation has been pushed to the gh-pages branch you should add links to your README.md pointing to the stable (and perhaps dev) documentation URLs. It is common practice to make use of \"badges\" similar to those used for Travis and AppVeyor build statuses or code coverage. Adding the following to your package README.md should be all that is necessary:",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "PACKAGE_NAME and USER_NAME should be replaced with their appropriate values. The colour and text of the image can be changed by altering docs-stable-blue as described on shields.io, though it is recommended that package authors follow this standard to make it easier for potential users to find documentation links across multiple package README files.",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "See the deploydocs function documentation for more details.",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "That should be all that is needed to enable automatic documentation building. Pushing new commits to your master branch should trigger doc builds. Note that other branches do not trigger these builds and neither do pull requests by potential contributors.",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "The doc-build environment docs/Project.toml includes Documenter and other doc-build dependencies your package might have. If Documenter is the only dependency, then the Project.toml should include the following:",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "The documentation is deployed as follows:",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "The following sections outline how to enable this for your own package.",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "The three lines in the script: section do the following:",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "Then call the Travis.genkeys function as follows:",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "These are needed to avoid committing generated content to your repository.",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "To tell Travis that we want a new build stage we can add the following to the .travis.yml file:",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "Travis buildbots will start up and run your package tests in a \"Test\" stage.\nAfter the Test stage completes, a single bot will run a new \"Documentation\" stage, which will build the documentation.\nIf the documentation is built successfully, the bot will attempt to push the generated HTML pages back to GitHub.",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "Unless a custom domain is being used, the pages are found at:",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "We'll need to add an additional function call to this file after makedocs which would perform the deployment of the docs to the gh-pages branch. Add the following at the end of the file:",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "Which versions that will show up in the version selector is determined by the versions argument to deploydocs.",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "[![](https://img.shields.io/badge/docs-stable-blue.svg)](https://USER_NAME.github.io/PACKAGE_NAME.jl/stable)\n[![](https://img.shields.io/badge/docs-dev-blue.svg)](https://USER_NAME.github.io/PACKAGE_NAME.jl/dev)",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "[deps]\nDocumenter = \"e30172f5-a6a5-5a46-863b-614d45cd2de4\"\n\n[compat]\nDocumenter = \"~0.20\"",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "deploydocs(\n repo = \"github.com/USER_NAME/PACKAGE_NAME.jl.git\",\n)",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "docs/build/",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "https://USER_NAME.github.io/PACKAGE_NAME.jl/stable",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "https://USER_NAME.github.io/PACKAGE_NAME.jl/vX.Y.Z\nhttps://USER_NAME.github.io/PACKAGE_NAME.jl/dev",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "jobs:\n include:\n - stage: \"Documentation\"\n julia: 1.0\n os: linux\n script:\n - julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd()));\n Pkg.instantiate()'\n - julia --project=docs/ docs/make.jl\n after_success: skip",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "julia> using DocumenterTools",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "julia> using MyPackage\njulia> Travis.genkeys(MyPackage)",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "julia> using MyPackage\njulia> Travis.genkeys(user=\"MyUser\", repo=\"git@github.com:MyUser/MyPackage.jl.git\")",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "note: Note\nFollowing this guide should be the final step you take after you are comfortable with the syntax and build process used by Documenter.jl. It is recommended that you only proceed with the steps outlined here once you have successfully managed to build your documentation locally with Documenter.This guide assumes that you already have GitHub and Travis accounts setup. If not then go set those up first and then return here.",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "note: Note\nIf your package has a build script you should call Pkg.build(\"PackageName\") after the call to Pkg.develop to make sure the package is built properly.",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "note: Note\nThere are more explicit instructions for adding the keys to GitHub and Travis in the SSH Deploy Keys Walkthrough section of the manual.",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "note: Note\nYou will need several command line programs (which, git and ssh-keygen) to be installed for the following steps to work. If DocumenterTools fails, please see the the SSH Deploy Keys Walkthrough section for instruction on how to generate the keys manually (including in Windows).",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "pkg> add DocumenterTools",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "using Documenter, PACKAGE_NAME\n\nmakedocs()",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "where MyPackage is the name of the package you would like to create deploy keys for and MyUser is your GitHub username. Note that the keyword arguments are optional and can be omitted.",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "where MyPackage is the package you would like to create deploy keys for. The output will look similar to the text below:",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "where USER_NAME and PACKAGE_NAME must be set to the appropriate names. Note that repo should not specify any protocol, i.e. it should not begin with https:// or git@.",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/#",
"page": "Hosting Documentation",
"text": "where the julia: and os: entries decide the worker from which the docs are built and deployed. In the example above we will thus build and deploy the documentation from a linux worker running Julia 1.0. For more information on how to setup a build stage, see the Travis manual for Build Stages.",
"title": "Hosting Documentation"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "(Image: )",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "(Image: )",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "(Image: )",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "(Image: )",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "-----BEGIN RSA PRIVATE KEY-----\n ... base64-encoded key over several lines ...\n-----END RSA PRIVATE KEY-----",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "And the private key usually look something like this",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "Click the \"Conversions\" tab, and then click \"Export OpenSSH key\". Save that file somewhere. That file is your private key and is required for the Adding the Private Key to Travis step.\n(Image: )\nnote: Note\nDon't save your key via the \"Save private key\" button as this will save the key in the wrong format.",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "Click the \"Generate\" button, then follow the instructions and move the mouse around to create randomness.",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "Copy and paste the output somewhere. This is your private key and is required for the step Adding the Private Key to Travis.",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "Copy and paste the output somewhere. This is your public key and is required for the step Adding the Public Key to GitHub.",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "Copy the resulting output.",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "Copy the text in the box titled \"Public key for pasting into OpenSSH authorized_keys file\" and paste it somewhere for later. This is your public key and is required for the step Adding the Public Key to GitHub",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "Download and install PuTTY",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "Final Remarks",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "Finally, check that the \"Display value in build log\" is switched off and then click \"Add\". Congratulations! You've added the private key to Travis.",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "Finally, we need to save the private key somewhere.",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "First, we need to Base64 encode the private key. Open Julia, and run the command",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "Generating an SSH Key\nAdding the Public Key to GitHub\nAdding the Private Key to Travis",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "Go to https://github.com/[YOUR_USER_NAME]/[YOUR_REPO_NAME]/settings/keys and click \"Add deploy key\". You should get to a page that looks like:",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "Have \"Title\" be e.g. \"Documenter\".\nCopy and paste the public key that we generated in the Generating an SSH Key step into the \"Key\" field.\nMake sure that the \"Allow write access\" box is checked.",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "If the instructions in SSH Deploy Keys did not work for you (for example, ssh-keygen is not installed), don't worry! This walkthrough will guide you through the process. There are three main steps:",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "If you have ssh-keygen installed, but Travis.genkeys() didn't work, you can generate an SSH key as follows. First, generate a key using ssh-keygen and save it to the file privatekey:",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "If you made it this far, congratulations! You now have the private and public keys needed to set up automatic deployment of your documentation. The next steps are to add the keys to GitHub and Travis.",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "If you're using Windows, you probably don't have ssh-keygen installed. Instead, we're going to use a program called PuTTY. The first step in the process to generate a new SSH key is to download PuTTY:",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "In this section, we explain how to upload a private SSH key to Travis. By this point, you should have generated a private key and saved it to a file. If you haven't done this, go read Generating an SSH Key.",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "In this section, we explain how to upload a public SSH key to GitHub. By this point, you should have generated a public key and saved it to a file. If you haven't done this, go read Generating an SSH Key.",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "Next, go to https://travis-ci.org/[YOUR_USER_NAME]/[YOUR_REPO_NAME]/settings. Scroll down to the \"Environment Variables\" section. It should look like this:",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "Next, we need to encode the private key in Base64. Run the following command:",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "Now we need to fill in three pieces of information.",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "Now we need to generate a key.",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "Now we need to get the public key. Run the following command:",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "Now we need to save the public key somewhere.",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "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).",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "Once you're done, click \"Add key\". Congratulations! You've added the public key to GitHub. The next step is to add the private key to Travis.",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "Once you've moved the mouse enough, the window should look like:",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "PuTTY is actually a collection of a few different programs. We need to use PuTTYgen. Open it, and you should get a window that looks like:",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "The first step is to generate an SSH key. An SSH key is made up of two components: a public key, which can be shared publicly, and a private key, which you should ensure is never shared publicly.",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "The public key usually looks something like this",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "You should now be able to continue on with the Hosting Documentation.",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "julia> read(\"path/to/private/key\", String) |> Documenter.base64encode |> println",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "julia> read(\"privatekey.pub\", String) |> println",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "julia> read(\"privatekey\", String) |> base64encode |> println",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "shell> ssh-keygen -N \"\" -f privatekey",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "ssh-rsa [base64-encoded-key] [optional-comment]",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/hosting/walkthrough/#",
"page": "SSH Deploy Keys Walkthrough",
"text": "warning: Security warning\nTo 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.",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "page",
"location": "man/latex/#",
"page": "LaTeX Syntax",
"text": "",
"title": "LaTeX Syntax"
},
{
"category": "page",
"location": "man/latex/#",
"page": "LaTeX Syntax",
"text": "",
"title": "LaTeX Syntax"
},
{
"category": "page",
"location": "man/latex/#",
"page": "LaTeX Syntax",
"text": "",
"title": "LaTeX Syntax"
},
{
"category": "page",
"location": "man/latex/#",
"page": "LaTeX Syntax",
"text": "@doc raw\"\"\"\nHere's some inline maths: ``\\sqrt[n]{1 + x + x^2 + \\ldots}``.\n\nHere's an equation:\n\n``\\frac{n!}{k!(n - k)!} = \\binom{n}{k}``\n\nThis is the binomial coefficient.\n\"\"\"\nfunc(x) = # ...",
"title": "LaTeX Syntax"
},
{
"category": "page",
"location": "man/latex/#",
"page": "LaTeX Syntax",
"text": "A related issue is how to add dollar signs to a docstring. They need to be double-escaped as follows:",
"title": "LaTeX Syntax"
},
{
"category": "page",
"location": "man/latex/#",
"page": "LaTeX Syntax",
"text": "Here's an equation:",
"title": "LaTeX Syntax"
},
{
"category": "page",
"location": "man/latex/#",
"page": "LaTeX Syntax",
"text": "Here's an equation:\n\n```math\n\\frac{n!}{k!(n - k)!} = \\binom{n}{k}\n```\n\nThis is the binomial coefficient.",
"title": "LaTeX Syntax"
},
{
"category": "page",
"location": "man/latex/#",
"page": "LaTeX Syntax",
"text": "Here's some inline maths: ``\\sqrt[n]{1 + x + x^2 + \\ldots}``.",
"title": "LaTeX Syntax"
},
{
"category": "page",
"location": "man/latex/#",
"page": "LaTeX Syntax",
"text": "Here's some inline maths: sqrtn1 + x + x^2 + ldots.",
"title": "LaTeX Syntax"
},
{
"category": "page",
"location": "man/latex/#",
"page": "LaTeX Syntax",
"text": "Since some characters used in LaTeX syntax, such as $ and \\, are treated differently in docstrings. They need to be escaped using a \\ character as in the following example:",
"title": "LaTeX Syntax"
},
{
"category": "page",
"location": "man/latex/#",
"page": "LaTeX Syntax",
"text": "The following section describes how to add equations written using LaTeX to your documentation.",
"title": "LaTeX Syntax"
},
{
"category": "page",
"location": "man/latex/#",
"page": "LaTeX Syntax",
"text": "This is the binomial coefficient.",
"title": "LaTeX Syntax"
},
{
"category": "page",
"location": "man/latex/#",
"page": "LaTeX Syntax",
"text": "To avoid needing to escape the special characters the raw\"\" string macro can be used, combined with @doc:",
"title": "LaTeX Syntax"
},
{
"category": "page",
"location": "man/latex/#",
"page": "LaTeX Syntax",
"text": "\"\"\"\nHere's some inline maths: ``\\\\sqrt[n]{1 + x + x^2 + \\\\ldots}``.\n\nHere's an equation:\n\n``\\\\frac{n!}{k!(n - k)!} = \\\\binom{n}{k}``\n\nThis is the binomial coefficient.\n\"\"\"\nfunc(x) = # ...",
"title": "LaTeX Syntax"
},
{
"category": "page",
"location": "man/latex/#",
"page": "LaTeX Syntax",
"text": "\"\"\"\nThe cost was \\\\\\$1.\n\"\"\"",
"title": "LaTeX Syntax"
},
{
"category": "page",
"location": "man/latex/#",
"page": "LaTeX Syntax",
"text": "fracnk(n - k) = binomnk",
"title": "LaTeX Syntax"
},
{
"category": "page",
"location": "man/latex/#",
"page": "LaTeX Syntax",
"text": "which will be displayed as",
"title": "LaTeX Syntax"
},
{
"category": "page",
"location": "man/latex/#",
"page": "LaTeX Syntax",
"text": "which will be displayed as",
"title": "LaTeX Syntax"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "# ...\n\ndeploydocs(\n deps = Deps.pip(\"pygments\", \"mkdocs\", \"python-markdown-math\"),\n # ...\n)",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "# ...\nmarkdown_extensions:\n - mdx_math\n # ...\n\nextra_javascript:\n - https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS_HTML\n - assets/mathjaxhelper.js\n# ...",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "$ pip install python-markdown-math",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "A MkDocs build is controlled by the mkdocs.yml configuration file. Add the file with the following content to the docs/ directory:",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "Final Remarks",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "Following this guide and adding the necessary changes to the configuration files should enable properly rendered mathematical equations within your documentation both locally and when built and deployed using the Travis built service.",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "If you build the documentation on Travis you need to add",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "If you have run Documenter and it has generated a build/ directory, you can now try running mkdocs build – this should now generate the site/ directory. You should also add the docs/site/ directory into your .gitignore file, which should now look like:",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "In addition to the default native HTML output, plugin packages enable Documenter to generate output in other formats. Once the corresponding package is loaded, the output format can be specified using the format option in makedocs.",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "In the example above we include the dependencies mkdocs and python-markdown-math. The former makes sure that MkDocs is installed to deploy the documentation, and the latter provides the mdx_math markdown extension to exploit MathJax rendering of latex equations in markdown. Other dependencies should be included here.",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "It is also possible to use a prebuilt docker image to compile the .tex file. The image contains all of the required installs described in the section above. The only requirement for using the image is that docker is installed and available for the builder to call. You also need to tell Documenter to use the docker image, instead of natively installed tex which is the default. This is done with the LaTeX specifier:",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "LaTeX/PDF output requires the DocumenterLaTeX package to be available and loaded in make.jl with",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "Markdown output requires the DocumenterMarkdown package to be available and loaded. For Travis setups, add the package to the docs/Project.toml environment as a dependency. You also need to import the package in make.jl:",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "MkDocs, of course, is not the only option you have – any markdown to HTML converter should work fine with some amount of setting up.",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "The docs/mkdocs.yml file must add the python-markdown-math extension, called mdx_math, as well as two MathJax JavaScript files:",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "The following is required to build the documentation:",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "This is only a basic skeleton. Read through the MkDocs documentation if you would like to know more about the available settings.",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "This package should also be installed locally so that you can preview the generated documentation prior to pushing new commits to a repository.",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "To deploy MkDocs on Travis, you also need to provide additional keyword arguments to deploydocs. Your deploydocs call should look something like",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "To get MkDocs to display LaTeX equations correctly we need to update several of this configuration files described in the Package Guide.",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "When DocumenterLaTeX is loaded, you can set format = LaTeX() in makedocs, and Documenter will generate a PDF version of the documentation using LaTeX. The makedocs argument sitename will be used for the \\\\title field in the tex document, and if the build is for a release tag (i.e. when the \"TRAVIS_TAG\" environment variable is set) the version number will be appended to the title. The makedocs argument authors should also be specified, it will be used for the \\\\authors field in the tex document.",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "When DocumenterMarkdown is loaded, you can specify format = Markdown() in makedocs. Documenter will then output a set of Markdown files to the build directory that can then further be processed with MkDocs into HTML pages.",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "You need pdflatex command to be installed and available to Documenter.\nYou need the minted LaTeX package and its backend source highlighter Pygments installed.\nYou need the Lato and Roboto Mono fonts installed.",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "deploydocs(\n repo = \"github.com/USER_NAME/PACKAGE_NAME.jl.git\",\n deps = Deps.pip(\"mkdocs\", \"pygments\", \"python-markdown-math\"),\n make = () -> run(`mkdocs build`)\n target = \"site\"\n)",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "deps serves to provide the required Python dependencies to build the documentation\nmake specifies the function that calls mkdocs to perform the second build step\ntarget, which specified which files get copied to gh-pages, needs to point to the site/ directory",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "docs/build/\ndocs/site/",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "docs/make.jl should add the python-markdown-math dependency to allow for equations to be rendered correctly.",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "note: Note\nMarkdown output used to be the default option (i.e. when leaving the format option unspecified). The default now is the HTML output.",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "services:\n - docker",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "site_name: PACKAGE_NAME.jl\nrepo_url: https://github.com/USER_NAME/PACKAGE_NAME.jl\nsite_description: Description...\nsite_author: USER_NAME\n\ntheme: readthedocs\n\nextra_css:\n - assets/Documenter.css\n\nextra_javascript:\n - https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS_HTML\n - assets/mathjaxhelper.js\n\nmarkdown_extensions:\n - extra\n - tables\n - fenced_code\n - mdx_math\n\ndocs_dir: 'build'\n\npages:\n - Home: index.md",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "to your .travis.yml file.",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "using DocumenterLaTeX",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "using DocumenterLaTeX\nmakedocs(\n format = LaTeX(platform = \"docker\"),\n ...\n)",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/other-formats/#",
"page": "Other Output Formats",
"text": "using DocumenterMarkdown",
"title": "Other Output Formats"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "# Syntax\n\n... [`makedocs`](@ref) ...\n\n# Functions\n\n```@docs\nmakedocs\n```\n\n... [Syntax](@ref) ...\n\n... [#42](@ref) ...",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "# [Header](@id my_custom_header_name)\n\n...\n\n## Header\n\n... [Custom Header](@ref my_custom_header_name) ...",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": ":module\n:constant\n:type\n:function\n:macro",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "<svg style=\"display: block; margin: 0 auto;\" width=\"5em\" heigth=\"5em\">\n\t<circle cx=\"2.5em\" cy=\"2.5em\" r=\"2em\" stroke=\"black\" stroke-width=\".1em\" fill=\"red\" />\n (SVG)\n</svg>",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "@example blocks accept a keyword argument continued which can be set to true or false (defaults to false). When continued = true the execution of the code is delayed until the next continued = false @example-block. This is needed for example when the expression in a block is not complete. Example:",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "@example blocks automatically define ans which, as in the Julia REPL, is bound to the value of the last evaluated expression. This can be useful in situations such as the following one where where binding the object returned by plot to a named variable would look out of place in the final rendered documentation:",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "@refs may refer to docstrings or headers on different pages as well as the current page using the same syntax.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Allows code to be inserted into the final document verbatim. E.g. to insert custom HTML or LaTeX code into the output.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Also, instead of returning nothing in the example above we could have returned a new Markdown.MD object through Markdown.parse. This can be more appropriate when the filename is not known until evaluation of the block itself.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Another example is to generate markdown tables from machine readable data formats such as CSV or JSON.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "As with @index if Pages is not provided then all pages are included. The default Depth value is 2.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Automatically splices all docstrings from the provided modules in place of the code block. This is equivalent to manually adding all the docstrings in a @docs block.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "By default @example blocks are run in their own anonymous Modules to avoid side-effects between blocks. To share the same module between different blocks on a page the @example can be named with the following syntax",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Code blocks may have some content that does not need to be displayed in the final document. # hide comments can be appended to lines that should not be rendered, i.e.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "CurrentModule: module where Documenter evaluates, for example, @docs-block and @ref-links.\nDocTestSetup: code to be evaluated before a doctest, see the Setup Code section under Doctests.\nDocTestFilters: filters to deal with, for example, unpredictable output from doctests, see the Filtering Doctests section under Doctests.\nEditURL: link to where the page can be edited. This defaults to the .md page itself, but if the source is something else (for example if the .md page is generated as part of the doc build) this can be set, either as a local link, or an absolute url.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Delayed Execution of @example Blocks",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Docstring @refs can also be \"named\" in a similar way to headers as shown in the Duplicate Headers section above. For example",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Duplicate docstring references do not occur since splicing the same docstring into a document more than once is disallowed.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Each module is added in order and so all docs from Foo will appear before those of Bar. Possible values for the Order vector are",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Evaluates the code block and inserts the result into the final document along with the original source code.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Evaluates the contents of the block and inserts the resulting value into the final document.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Example:",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "First we define some functions\n\n```@example 1\nusing PyPlot # hide\nf(x) = sin(2x) + 1\ng(x) = cos(x) - x\n```\n\nand then we plot `f` over the interval from ``-π`` to ``π``\n\n```@example 1\nx = linspace(-π, π)\nplot(x, f(x), color = \"red\")\nsavefig(\"f-plot.svg\"); nothing # hide\n```\n\n![](f-plot.svg)\n\nand then we do the same with `g`\n\n```@example 1\nplot(x, g(x), color = \"blue\")\nsavefig(\"g-plot.svg\"); nothing # hide\n```\n\n![](g-plot.svg)",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Functions exported from `Foo`:\n\n```@autodocs\nModules = [Foo]\nPrivate = false\nOrder = [:function]\n```\n\nPrivate types in module `Foo`:\n\n```@autodocs\nModules = [Foo]\nPublic = false\nOrder = [:type]\n```",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Generates a list of links to docstrings that have been spliced into a document. Valid settings are Pages, Modules, and Order. For example:",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Generates a nested list of links to document sections. Valid settings are Pages and Depth.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Here the first block is not complete – the loop is missing the end. Thus, by setting continued = true here we delay the evaluation of the first block, until we reach the second block. A block with continued = true does not have any output.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Hiding Source Code",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "If no Order is provided then the order listed above is used.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "In addition to Order, a Pages vector may be included in @autodocs to filter docstrings based on the source file in which they are defined:",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "In some cases a document may contain multiple headers with the same name, but on different pages or of different levels. To allow @ref to cross-reference a duplicate header it must be given a name as in the following example",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "In the above example docstrings from module Foo found in source files that end in a.jl and b.jl are included. The page order provided by Pages is also used to sort the docstrings. Note that page matching is done using the end of the provided strings and so a.jl will be matched by any source file that ends in a.jl, i.e. src/a.jl or src/foo/a.jl.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "In the following example we use the PyPlot package to generate a plot and display it in the final document.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "In the given example, only the docstrings of the subtypes of Foo.C are shown. Instead of an anonymous function you can give the name of a function you defined beforehand, too:",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "It should be noted though that in this case Pages may not be sorted in the order that is expected by the user. Try to stick to array literals as much as possible.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "It will show up as follows, with code having been copied over verbatim to the HTML file.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Leading and trailing newlines are removed from the rendered code blocks. Trailing whitespace on each line is also removed.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Named @example Blocks",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Named @example blocks can be useful when generating documentation that requires intermediate explanation or multimedia such as plots as illustrated in the following example",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Named @repl <name> blocks behave in the same way as named @example <name> blocks.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Note that @example blocks are evaluated within the directory of build where the file will be rendered . This means than in the above example savefig will output the .svg files into that directory. This allows the images to be easily referenced without needing to worry about relative paths.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Note that @meta blocks are always evaluated in Main.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Note that appending # hide to every line in an @example block will result in the block being hidden in the rendered document. The results block will still be rendered though. @setup blocks are a convenient shorthand for hiding an entire block, including the output.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Note that depending on what the CurrentModule is set to, a docstring @ref may need to be prefixed by the module which defines it.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Note that each @eval block evaluates its contents within a separate module. When evaluating each block the present working directory, pwd, is set to the directory in build where the file will be written to, and the paths in include calls are interpreted to be relative to pwd.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Note that the values assigned to Pages, Modules, and Order may be any valid Julia code and thus can be something more complex that an array literal if required, i.e.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Objects may not be listed more than once within the document. When duplicate objects are detected an error will be raised and the build process will be terminated.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Pages = [\"syntax.md\"]",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Plain text in the \"text\" part of a link will either cross-reference a header, or, when it is a number preceded by a #, a GitHub issue/pull request. Text wrapped in backticks will cross-reference a docstring from a @docs block.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Splice one or more docstrings into a document in place of the code block, i.e.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "The Julia output streams are redirected to the results block when evaluating @example blocks in the same way as when running doctest code blocks.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "The above @autodocs block adds all the docstrings found in modules Foo and Bar that refer to functions or types to the document.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "The above @example block will splice the following into the final document",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "The following example shows how SVG code with custom styling can be included into documents using the @raw block.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "The format argument is mandatory and Documenter uses it to determine whether a particular block should be copied over to the output or not. Currently supported formats are html and latex, used by the respective writers. A @raw block whose format is not recognized is usually ignored, so it is possible to have a raw block for each output format without the blocks being duplicated in the output.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "The link that wraps the named header is removed in the final document. The text for a named @ref ... does not need to match the header that it references. Named @ref ...s may refer to headers on different pages in the same way as unnamed ones do.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "The name can be any text, not just integers as in the example above, i.e. @example foo.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "These are similar to @example blocks, but adds a julia> prompt before each toplevel expression. ; and # hide syntax may be used in @repl blocks in the same way as in the Julia REPL and @example blocks.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "These are similar to @example blocks, but both the input and output are hidden from the final document. This can be convenient if there are several lines of setup code that need to be hidden.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "This block type is evaluated within the CurrentModule module if defined, otherwise within Main, and so each object listed in the block should be visible from that module. Undefined objects will raise warnings during documentation generation and cause the code block to be rendered in the final document unchanged.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "This block type is used to define metadata key/value pairs that can be used elsewhere in the page. Currently recognised keys:",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "This can be useful to avoid having to write fully qualified names for references that are not imported into the current module, or when the text displayed in the link is used to add additional meaning to the surrounding text, such as",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "This section of the manual describes the syntax used by Documenter to build documentation.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "To ensure that all docstrings from a module are included in the final document the modules keyword for makedocs can be set to the desired module or modules, i.e.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "To filter out certain docstrings by your own criteria, you can provide function with them Filter keyword:",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "To include only the exported names from the modules listed in Modules use Private = false. In a similar way Public = false can be used to only show the unexported names. By default both of these are set to true so that all names will be shown.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Use [`for i = 1:10 ...`](@ref for) to loop over all the numbers from 1 to 10.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Used in markdown links as the URL to tell Documenter to generate a cross-reference automatically. The text part of the link can be a docstring, header name, or GitHub PR/Issue number.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "When Pages or Modules are not provided then all pages or modules are included. Order defaults to",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "When a potential docstring is found in one of the listed modules, but does not match any value from Order then it will be omitted from the document. Hence Order acts as a basic filter as well as sorter.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "When the @example block evaluates to nothing then the second block is not displayed. Only the source code block will be shown in the rendered document. Note that if any output from either stdout or stderr is captured then the results block will be displayed even if nothing is returned.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "Which will generate a markdown version of the CSV file table.csv and render it in the output format.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "[:module, :constant, :type, :function, :macro]",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "```@autodocs\nModules = [Foo, Bar]\nOrder = [:function, :type]\n```",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "```@autodocs\nModules = [Foo]\nFilter = myCustomFilterFunction\n```",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "```@autodocs\nModules = [Foo]\nFilter = t -> typeof(t) === DataType && t <: Foo.C\n```",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "```@autodocs\nModules = [Foo]\nPages = [\"a.jl\", \"b.jl\"]\n```",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "```@contents\nPages = [\"foo.md\"]\nDepth = 5\n```",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "```@docs\nDocumenter\nmakedocs\ndeploydocs\n```",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "```@eval\nusing CSV\nusing Latexify\ndf = CSV.read(\"table.csv\")\nmdtable(df,latex=false)\n```",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "```@eval\nusing PyPlot\n\nx = linspace(-π, π)\ny = sin(x)\n\nplot(x, y, color = \"red\")\nsavefig(\"plot.svg\")\n\nnothing\n```\n\n![](plot.svg)",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "```@example 1\na = 1\n```\n\n```@example 1\nprintln(a)\n```",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "```@example half-loop; continued = true\nfor i in 1:3\n j = i^2\n```\nSome text explaining what we should do with `j`\n```@example half-loop\n println(j)\nend\n```",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "```@example\na = 1\nb = 2\na + b\n```",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "```@example\nimport Random # hide\nRandom.seed!(1) # hide\nA = rand(3, 3)\nb = [1, 2, 3]\nA \\ b\n```",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "```@example\nusing Gadfly # hide\nplot([sin, x -> 2sin(x) + x], -2π, 2π)\ndraw(SVG(\"plot.svg\", 6inch, 4inch), ans); nothing # hide\n```\n\n![](plot.svg)",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "```@index\nPages = [\"foo.md\"]\nModules = [Foo, Bar]\nOrder = [:function, :type]\n```",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "```@index\nPages = map(file -> joinpath(\"man\", file), readdir(\"man\"))\n```",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "```@meta\nCurrentModule = FooBar\nDocTestSetup = quote\n using MyPackage\nend\nDocTestFilters = [r\"Stacktrace:[\\s\\S]+\"]\nEditURL = \"link/to/source/file\"\n```",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "```@raw html\n<svg style=\"display: block; margin: 0 auto;\" width=\"5em\" heigth=\"5em\">\n\t<circle cx=\"2.5em\" cy=\"2.5em\" r=\"2em\" stroke=\"black\" stroke-width=\".1em\" fill=\"red\" />\n</svg>\n```",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "```@repl\na = 1\nb = 2\na + b\n```",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "```@setup abc\nusing RDatasets\nusing DataFrames\niris = dataset(\"datasets\", \"iris\")\n```\n\n```@example abc\nprintln(iris)\n```",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "```julia\na = 1\nb = 2\na + b\n```\n\n```\n3\n```",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "```julia\njulia> a = 1\n1\n\njulia> b = 2\n2\n\njulia> a + b\n3\n```",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "if not specified. Order and Modules behave the same way as in @autodocs blocks and filter out docstrings that do not match one of the modules or categories specified.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "makedocs(\n modules = [Documenter],\n)",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "module Mod\n\n\"\"\"\nBoth of the following references point to `g` found in module `Main.Other`:\n\n * [`Main.Other.g`](@ref)\n * [`g`](@ref Main.Other.g)\n\n\"\"\"\nf(args...) = # ...\n\nend",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "note: Note\nIn most cases @example is preferred over @eval. Just like in normal Julia code where eval should be only be considered as a last resort, @eval should be treated in the same way.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "note: Note\nNamed doc @refs should be used sparingly since writing unqualified names may, in some cases, make it difficult to tell which function is being referred to in a particular docstring if there happen to be several modules that provide definitions with the same name.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "note: Note\nThe working directory, pwd, is set to the directory in build where the file will be written to, and the paths in include calls are interpreted to be relative to pwd.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "note: Note\nThe working directory, pwd, is set to the directory in build where the file will be written to, and the paths in include calls are interpreted to be relative to pwd.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "note: Note\nUnlike @example and @repl blocks, @setup requires a <name> attribute to associate it with downstream @example <name> and @repl <name> blocks.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "note: Note\nWhen more complex sorting is needed then use @docs to define it explicitly.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "nothing Results",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "stdout and stderr",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "which will cause any unlisted docstrings to raise warnings when makedocs is called. If modules is not defined then no warnings are printed, even if a document has missing docstrings.",
"title": "Syntax"
},
{
"category": "page",
"location": "man/syntax/#",
"page": "Syntax",
"text": "will generate",
"title": "Syntax"
},
{
"category": "section",
"location": "#Documenter.jl-1",
"page": "Home",
"text": "",
"title": "Documenter.jl"
},
{
"category": "section",
"location": "#Library-Outline-1",
"page": "Home",
"text": "",
"title": "Library Outline"
},
{
"category": "section",
"location": "#Manual-Outline-1",
"page": "Home",
"text": "",
"title": "Manual Outline"
},
{
"category": "section",
"location": "#Package-Features-1",
"page": "Home",
"text": "",
"title": "Package Features"
},
{
"category": "section",
"location": "#main-index-1",
"page": "Home",
"text": "",
"title": "Index"
},
{
"category": "section",
"location": "contributing/#Backports-1",
"page": "Contributing",
"text": "",
"title": "Backports"
},
{
"category": "section",
"location": "contributing/#Branches-1",
"page": "Contributing",
"text": "",
"title": "Branches"
},
{
"category": "section",
"location": "contributing/#Contributing-1",
"page": "Contributing",
"text": "",
"title": "Contributing"
},
{
"category": "section",
"location": "contributing/#Julia-1",
"page": "Contributing",
"text": "",
"title": "Julia"
},
{
"category": "section",
"location": "contributing/#Markdown-1",
"page": "Contributing",
"text": "",
"title": "Markdown"
},
{
"category": "section",
"location": "contributing/#Style-Guide-1",
"page": "Contributing",
"text": "",
"title": "Style Guide"
},
{
"category": "section",
"location": "contributing/#release-*-branches-1",
"page": "Contributing",
"text": "",
"title": "release-* branches"
},
{
"category": "section",
"location": "lib/internals/#Contents-1",
"page": "Internals",
"text": "",
"title": "Contents"
},
{
"category": "section",
"location": "lib/internals/#Index-1",
"page": "Internals",
"text": "",
"title": "Index"
},
{
"category": "section",
"location": "lib/internals/#Internal-Documentation-1",
"page": "Internals",
"text": "",
"title": "Internal Documentation"
},
{
"category": "section",
"location": "lib/internals/anchors/#Anchors-1",
"page": "Anchors",
"text": "",
"title": "Anchors"
},
{
"category": "section",
"location": "lib/internals/builder/#Builder-1",
"page": "Builder",
"text": "",
"title": "Builder"
},
{
"category": "section",
"location": "lib/internals/cross-references/#CrossReferences-1",
"page": "CrossReferences",
"text": "",
"title": "CrossReferences"
},
{
"category": "section",
"location": "lib/internals/docchecks/#DocChecks-1",
"page": "DocChecks",
"text": "",
"title": "DocChecks"
},
{
"category": "section",
"location": "lib/internals/docsystem/#DocSystem-1",
"page": "DocSystem",
"text": "",
"title": "DocSystem"
},
{
"category": "section",
"location": "lib/internals/doctests/#DocTests-1",
"page": "DocTests",
"text": "",
"title": "DocTests"
},
{
"category": "section",
"location": "lib/internals/documenter/#Documenter-1",
"page": "Documenter",
"text": "",
"title": "Documenter"
},
{
"category": "section",
"location": "lib/internals/documentertools/#DocumenterTools-1",
"page": "DocumenterTools",
"text": "",
"title": "DocumenterTools"
},
{
"category": "section",
"location": "lib/internals/documentertools/#Generator-1",
"page": "DocumenterTools",
"text": "",
"title": "Generator"
},
{
"category": "section",
"location": "lib/internals/documents/#Documents-1",
"page": "Documents",
"text": "",
"title": "Documents"
},
{
"category": "section",
"location": "lib/internals/dom/#DOM-1",
"page": "DOM",
"text": "",
"title": "DOM"
},
{
"category": "section",
"location": "lib/internals/expanders/#Expanders-1",
"page": "Expanders",
"text": "",
"title": "Expanders"
},
{
"category": "section",
"location": "lib/internals/mdflatten/#MDFlatten-1",
"page": "MDFlatten",
"text": "",
"title": "MDFlatten"
},
{
"category": "section",
"location": "lib/internals/selectors/#Selectors-1",
"page": "Selectors",
"text": "",
"title": "Selectors"
},
{
"category": "section",
"location": "lib/internals/textdiff/#TextDiff-1",
"page": "TextDiff",
"text": "",
"title": "TextDiff"
},
{
"category": "section",
"location": "lib/internals/utilities/#Utilities-1",
"page": "Utilities",
"text": "",
"title": "Utilities"
},
{
"category": "section",
"location": "lib/internals/writers/#Writers-1",
"page": "Writers",
"text": "",
"title": "Writers"
},
{
"category": "section",
"location": "lib/public/#Contents-1",
"page": "Public",
"text": "",
"title": "Contents"
},
{
"category": "section",
"location": "lib/public/#DocumenterTools-1",
"page": "Public",
"text": "",
"title": "DocumenterTools"
},
{
"category": "section",
"location": "lib/public/#Index-1",
"page": "Public",
"text": "",
"title": "Index"
},
{
"category": "section",
"location": "lib/public/#Public-Documentation-1",
"page": "Public",
"text": "",
"title": "Public Documentation"
},
{
"category": "section",
"location": "lib/public/#Public-Interface-1",
"page": "Public",
"text": "",
"title": "Public Interface"
},
{
"category": "section",
"location": "man/doctests/#Doctests-1",
"page": "Doctests",
"text": "",
"title": "Doctests"
},
{
"category": "section",
"location": "man/doctests/#Exceptions-1",
"page": "Doctests",
"text": "",
"title": "Exceptions"
},
{
"category": "section",
"location": "man/doctests/#Filtering-Doctests-1",
"page": "Doctests",
"text": "",
"title": "Filtering Doctests"
},
{
"category": "section",
"location": "man/doctests/#Fixing-Outdated-Doctests-1",
"page": "Doctests",
"text": "",
"title": "Fixing Outdated Doctests"
},
{
"category": "section",
"location": "man/doctests/#Preserving-Definitions-Between-Blocks-1",
"page": "Doctests",
"text": "",
"title": "Preserving Definitions Between Blocks"
},
{
"category": "section",
"location": "man/doctests/#REPL-Examples-1",
"page": "Doctests",
"text": "",
"title": "REPL Examples"
},
{
"category": "section",
"location": "man/doctests/#Setup-Code-1",
"page": "Doctests",
"text": "",
"title": "Setup Code"
},
{
"category": "section",
"location": "man/doctests/#Skipping-Doctests-1",
"page": "Doctests",
"text": "",
"title": "Skipping Doctests"
},
{
"category": "section",
"location": "man/doctests/#\"Script\"-Examples-1",
"page": "Doctests",
"text": "",
"title": "\"Script\" Examples"
},
{
"category": "section",
"location": "man/examples/#Documentation-repositories-1",
"page": "Examples",
"text": "",
"title": "Documentation repositories"
},
{
"category": "section",
"location": "man/examples/#Examples-1",
"page": "Examples",
"text": "",
"title": "Examples"
},
{
"category": "section",
"location": "man/examples/#Registered-1",
"page": "Examples",
"text": "",
"title": "Registered"
},
{
"category": "section",
"location": "man/guide/#Adding-Some-Docstrings-1",
"page": "Guide",
"text": "",
"title": "Adding Some Docstrings"
},
{
"category": "section",
"location": "man/guide/#Building-an-Empty-Document-1",
"page": "Guide",
"text": "",
"title": "Building an Empty Document"
},
{
"category": "section",
"location": "man/guide/#Cross-Referencing-1",
"page": "Guide",
"text": "",
"title": "Cross Referencing"
},
{
"category": "section",
"location": "man/guide/#Filtering-included-docstrings-1",
"page": "Guide",
"text": "",
"title": "Filtering included docstrings"
},
{
"category": "section",
"location": "man/guide/#Installation-1",
"page": "Guide",
"text": "",
"title": "Installation"
},
{
"category": "section",
"location": "man/guide/#Navigation-1",
"page": "Guide",
"text": "",
"title": "Navigation"
},
{
"category": "section",
"location": "man/guide/#Package-Guide-1",
"page": "Guide",
"text": "",
"title": "Package Guide"
},
{
"category": "section",
"location": "man/guide/#Pages-in-the-Sidebar-1",
"page": "Guide",
"text": "",
"title": "Pages in the Sidebar"
},
{
"category": "section",
"location": "man/guide/#Setting-up-the-Folder-Structure-1",
"page": "Guide",
"text": "",
"title": "Setting up the Folder Structure"
},
{
"category": "section",
"location": "man/hosting/#.gitignore-1",
"page": "Hosting Documentation",
"text": "",
"title": ".gitignore"
},
{
"category": "section",
"location": "man/hosting/#.travis.yml-Configuration-1",
"page": "Hosting Documentation",
"text": "",
"title": ".travis.yml Configuration"
},
{
"category": "section",
"location": "man/hosting/#Documentation-Versions-1",
"page": "Hosting Documentation",
"text": "",
"title": "Documentation Versions"
},
{
"category": "section",
"location": "man/hosting/#Hosting-Documentation-1",
"page": "Hosting Documentation",
"text": "",
"title": "Hosting Documentation"
},
{
"category": "section",
"location": "man/hosting/#Overview-1",
"page": "Hosting Documentation",
"text": "",
"title": "Overview"
},
{
"category": "section",
"location": "man/hosting/#SSH-Deploy-Keys-1",
"page": "Hosting Documentation",
"text": "",
"title": "SSH Deploy Keys"
},
{
"category": "section",
"location": "man/hosting/#The-deploydocs-Function-1",
"page": "Hosting Documentation",
"text": "",
"title": "The deploydocs Function"
},
{
"category": "section",
"location": "man/hosting/#gh-pages-Branch-1",
"page": "Hosting Documentation",
"text": "",
"title": "gh-pages Branch"
},
{
"category": "section",
"location": "man/hosting/walkthrough/#Adding-the-Private-Key-to-Travis-1",
"page": "SSH Deploy Keys Walkthrough",
"text": "",
"title": "Adding the Private Key to Travis"
},
{
"category": "section",
"location": "man/hosting/walkthrough/#Adding-the-Public-Key-to-GitHub-1",
"page": "SSH Deploy Keys Walkthrough",
"text": "",
"title": "Adding the Public Key to GitHub"
},
{
"category": "section",
"location": "man/hosting/walkthrough/#Generating-an-SSH-Key-1",
"page": "SSH Deploy Keys Walkthrough",
"text": "",
"title": "Generating an SSH Key"
},
{
"category": "section",
"location": "man/hosting/walkthrough/#If-you-do-not-have-ssh-keygen-1",
"page": "SSH Deploy Keys Walkthrough",
"text": "",
"title": "If you do not have ssh-keygen"
},
{
"category": "section",
"location": "man/hosting/walkthrough/#If-you-have-ssh-keygen-installed-1",
"page": "SSH Deploy Keys Walkthrough",
"text": "",
"title": "If you have ssh-keygen installed"
},
{
"category": "section",
"location": "man/hosting/walkthrough/#SSH-Deploy-Keys-Walkthrough-1",
"page": "SSH Deploy Keys Walkthrough",
"text": "",
"title": "SSH Deploy Keys Walkthrough"
},
{
"category": "section",
"location": "man/latex/#Display-Equations-1",
"page": "LaTeX Syntax",
"text": "",
"title": "Display Equations"
},
{
"category": "section",
"location": "man/latex/#Escaping-Characters-in-Docstrings-1",
"page": "LaTeX Syntax",
"text": "",
"title": "Escaping Characters in Docstrings"
},
{
"category": "section",
"location": "man/latex/#Inline-Equations-1",
"page": "LaTeX Syntax",
"text": "",
"title": "Inline Equations"
},
{
"category": "section",
"location": "man/latex/#latex_syntax-1",
"page": "LaTeX Syntax",
"text": "",
"title": "LaTeX Syntax"
},
{
"category": "section",
"location": "man/other-formats/#Compiling-using-docker-image-1",
"page": "Other Output Formats",
"text": "",
"title": "Compiling using docker image"
},
{
"category": "section",
"location": "man/other-formats/#Compiling-using-natively-installed-latex-1",
"page": "Other Output Formats",
"text": "",
"title": "Compiling using natively installed latex"
},
{
"category": "section",
"location": "man/other-formats/#Deployment-with-MkDocs-1",
"page": "Other Output Formats",
"text": "",
"title": "Deployment with MkDocs"
},
{
"category": "section",
"location": "man/other-formats/#Markdown-and-MkDocs-1",
"page": "Other Output Formats",
"text": "",
"title": "Markdown & MkDocs"
},
{
"category": "section",
"location": "man/other-formats/#Other-Output-Formats-1",
"page": "Other Output Formats",
"text": "",
"title": "Other Output Formats"
},
{
"category": "section",
"location": "man/other-formats/#PDF-Output-via-LaTeX-1",
"page": "Other Output Formats",
"text": "",
"title": "PDF Output via LaTeX"
},
{
"category": "section",
"location": "man/other-formats/#The-MkDocs-mkdocs.yml-file-1",
"page": "Other Output Formats",
"text": "",
"title": "The MkDocs mkdocs.yml file"
},
{
"category": "section",
"location": "man/other-formats/#\\LaTeX:-MkDocs-and-MathJax-1",
"page": "Other Output Formats",
"text": "",
"title": "LaTeX: MkDocs and MathJax"
},
{
"category": "section",
"location": "man/syntax/#@autodocs-block-1",
"page": "Syntax",
"text": "",
"title": "@autodocs block"
},
{
"category": "section",
"location": "man/syntax/#@contents-block-1",
"page": "Syntax",
"text": "",
"title": "@contents block"
},
{
"category": "section",
"location": "man/syntax/#@docs-block-1",
"page": "Syntax",
"text": "",
"title": "@docs block"
},
{
"category": "section",
"location": "man/syntax/#@eval-block-1",
"page": "Syntax",
"text": "",
"title": "@eval block"
},
{
"category": "section",
"location": "man/syntax/#@example-block-1",
"page": "Syntax",
"text": "",
"title": "@example block"
},
{
"category": "section",
"location": "man/syntax/#@index-block-1",
"page": "Syntax",
"text": "",
"title": "@index block"
},
{
"category": "section",
"location": "man/syntax/#@meta-block-1",
"page": "Syntax",
"text": "",
"title": "@meta block"
},
{
"category": "section",
"location": "man/syntax/#@raw-format-block-1",
"page": "Syntax",
"text": "",
"title": "@raw <format> block"
},
{
"category": "section",
"location": "man/syntax/#@ref-link-1",
"page": "Syntax",
"text": "",
"title": "@ref link"
},
{
"category": "section",
"location": "man/syntax/#@repl-block-1",
"page": "Syntax",
"text": "",
"title": "@repl block"
},
{
"category": "section",
"location": "man/syntax/#@setup-name-block-1",
"page": "Syntax",
"text": "",
"title": "@setup <name> block"
},
{
"category": "section",
"location": "man/syntax/#Duplicate-Headers-1",
"page": "Syntax",
"text": "",
"title": "Duplicate Headers"
},
{
"category": "section",
"location": "man/syntax/#Named-doc-@refs-1",
"page": "Syntax",
"text": "",
"title": "Named doc @refs"
},
{
"category": "section",
"location": "man/syntax/#Syntax-1",
"page": "Syntax",
"text": "",
"title": "Syntax"
},
{
"category": "type",
"location": "lib/internals/anchors/#Documenter.Anchors.Anchor",
"page": "Anchors",
"text": "Stores an arbitrary object called .object and it's location within a document.\n\nFields\n\nobject – the stored object.\norder – ordering of object within the entire document.\nfile – the destination file, in build, where the object will be written to.\nid – the generated \"slug\" identifying the object.\nnth – integer that unique-ifies anchors with the same id.\n\n\n\n\n\n",
"title": "Documenter.Anchors.Anchor"
},
{
"category": "type",
"location": "lib/internals/anchors/#Documenter.Anchors.AnchorMap",
"page": "Anchors",
"text": "Tree structure representating anchors in a document and their relationships with eachother.\n\nObject Hierarchy\n\nid -> file -> anchors\n\nEach id maps to a file which in turn maps to a vector of Anchor objects.\n\n\n\n\n\n",
"title": "Documenter.Anchors.AnchorMap"
},
{
"category": "type",
"location": "lib/internals/builder/#Documenter.Builder.CheckDocument",
"page": "Builder",
"text": "Checks that all documented objects are included in the document and runs doctests on all valid Julia code blocks.\n\n\n\n\n\n",
"title": "Documenter.Builder.CheckDocument"
},
{
"category": "type",
"location": "lib/internals/builder/#Documenter.Builder.CrossReferences",
"page": "Builder",
"text": "Finds and sets URLs for each @ref link in the document to the correct destinations.\n\n\n\n\n\n",
"title": "Documenter.Builder.CrossReferences"
},
{
"category": "type",
"location": "lib/internals/builder/#Documenter.Builder.DocumentPipeline",
"page": "Builder",
"text": "The default document processing \"pipeline\", which consists of the following actions:\n\nSetupBuildDirectory\nExpandTemplates\nCrossReferences\nCheckDocument\nPopulate\nRenderDocument\n\n\n\n\n\n",
"title": "Documenter.Builder.DocumentPipeline"
},
{
"category": "type",
"location": "lib/internals/builder/#Documenter.Builder.ExpandTemplates",
"page": "Builder",
"text": "Executes a sequence of actions on each node of the parsed markdown files in turn.\n\n\n\n\n\n",
"title": "Documenter.Builder.ExpandTemplates"
},
{
"category": "type",
"location": "lib/internals/builder/#Documenter.Builder.Populate",
"page": "Builder",
"text": "Populates the ContentsNodes and IndexNodes with links.\n\n\n\n\n\n",
"title": "Documenter.Builder.Populate"
},
{
"category": "type",
"location": "lib/internals/builder/#Documenter.Builder.RenderDocument",
"page": "Builder",
"text": "Writes the document tree to the build directory.\n\n\n\n\n\n",
"title": "Documenter.Builder.RenderDocument"
},
{
"category": "type",
"location": "lib/internals/builder/#Documenter.Builder.SetupBuildDirectory",
"page": "Builder",
"text": "Creates the correct directory layout within the build folder and parses markdown files.\n\n\n\n\n\n",
"title": "Documenter.Builder.SetupBuildDirectory"
},
{
"category": "type",
"location": "lib/internals/documents/#Documenter.Documents.Document",
"page": "Documents",
"text": "Represents an entire document.\n\n\n\n\n\n",
"title": "Documenter.Documents.Document"
},
{
"category": "type",
"location": "lib/internals/documents/#Documenter.Documents.Globals",
"page": "Documents",
"text": "Page-local values such as current module that are shared between nodes in a page.\n\n\n\n\n\n",
"title": "Documenter.Documents.Globals"
},
{
"category": "type",
"location": "lib/internals/documents/#Documenter.Documents.Internal",
"page": "Documents",
"text": "Private state used to control the generation process.\n\n\n\n\n\n",
"title": "Documenter.Documents.Internal"
},
{
"category": "type",
"location": "lib/internals/documents/#Documenter.Documents.NavNode",
"page": "Documents",
"text": "Element in the navigation tree of a document, containing navigation references to other page, reference to the Page object etc.\n\n\n\n\n\n",
"title": "Documenter.Documents.NavNode"
},
{
"category": "type",
"location": "lib/internals/documents/#Documenter.Documents.Page",
"page": "Documents",
"text": "Represents a single markdown file.\n\n\n\n\n\n",
"title": "Documenter.Documents.Page"
},
{
"category": "type",
"location": "lib/internals/documents/#Documenter.Documents.User",
"page": "Documents",
"text": "User-specified values used to control the generation process.\n\n\n\n\n\n",
"title": "Documenter.Documents.User"
},
{
"category": "type",
"location": "lib/internals/dom/#Documenter.Utilities.DOM.HTMLDocument",
"page": "DOM",
"text": "A HTML node that wraps around the root node of the document and adds a DOCTYPE to it.\n\n\n\n\n\n",
"title": "Documenter.Utilities.DOM.HTMLDocument"
},
{
"category": "type",
"location": "lib/internals/dom/#Documenter.Utilities.DOM.Node",
"page": "DOM",
"text": "Represents an element within an HTML document including any textual content, children Nodes, and attributes.\n\nThis type should not be constructed directly, but instead via (...) and [...] applied to a Tag or another Node object.\n\n\n\n\n\n",
"title": "Documenter.Utilities.DOM.Node"
},
{
"category": "type",
"location": "lib/internals/dom/#Documenter.Utilities.DOM.Tag",
"page": "DOM",
"text": "Represents a empty and attribute-less HTML element.\n\nUse @tags to define instances of this type rather than manually creating them via Tag(:tagname).\n\n\n\n\n\n",
"title": "Documenter.Utilities.DOM.Tag"
},
{
"category": "type",
"location": "lib/internals/expanders/#Documenter.Expanders.AutoDocsBlocks",
"page": "Expanders",
"text": "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 = ....\n\n```@autodocs\nModules = [Foo, Bar]\nOrder = [:function, :type]\n```\n\n\n\n\n\n",
"title": "Documenter.Expanders.AutoDocsBlocks"
},
{
"category": "type",
"location": "lib/internals/expanders/#Documenter.Expanders.ContentsBlocks",
"page": "Expanders",
"text": "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.\n\n```@contents\nPages = [\"foo.md\", \"bar.md\"]\nDepth = 1\n```\n\nThe default Depth value is 2.\n\n\n\n\n\n",
"title": "Documenter.Expanders.ContentsBlocks"
},
{
"category": "type",
"location": "lib/internals/expanders/#Documenter.Expanders.DocsBlocks",
"page": "Expanders",
"text": "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.\n\n```@docs\nDocumenter\nmakedocs\ndeploydocs\n```\n\n\n\n\n\n",
"title": "Documenter.Expanders.DocsBlocks"
},
{
"category": "type",
"location": "lib/internals/expanders/#Documenter.Expanders.EvalBlocks",
"page": "Expanders",
"text": "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.\n\n```@eval\nusing PyPlot\nx = linspace(-π, π)\ny = sin(x)\nplot(x, y, color = \"red\")\nsavefig(\"plot.svg\")\nMarkdown.parse(\"![Plot](plot.svg)\")\n```\n\n\n\n\n\n",
"title": "Documenter.Expanders.EvalBlocks"
},
{
"category": "type",
"location": "lib/internals/expanders/#Documenter.Expanders.ExampleBlocks",
"page": "Expanders",
"text": "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.\n\n```@example\na = 1\nb = 2\na + b\n```\n\n\n\n\n\n",
"title": "Documenter.Expanders.ExampleBlocks"
},
{
"category": "type",
"location": "lib/internals/expanders/#Documenter.Expanders.ExpanderPipeline",
"page": "Expanders",
"text": "The default node expander \"pipeline\", which consists of the following expanders:\n\nTrackHeaders\nMetaBlocks\nDocsBlocks\nAutoDocsBlocks\nEvalBlocks\nIndexBlocks\nContentsBlocks\nExampleBlocks\nSetupBlocks\nREPLBlocks\n\n\n\n\n\n",
"title": "Documenter.Expanders.ExpanderPipeline"
},
{
"category": "type",
"location": "lib/internals/expanders/#Documenter.Expanders.IndexBlocks",
"page": "Expanders",
"text": "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\n\n```@index\nPages = [\"foo.md\", \"bar.md\"]\n```\n\n\n\n\n\n",
"title": "Documenter.Expanders.IndexBlocks"
},
{
"category": "type",
"location": "lib/internals/expanders/#Documenter.Expanders.MetaBlocks",
"page": "Expanders",
"text": "Parses each code block where the language is @meta and evaluates the key/value pairs found within the block, i.e.\n\n```@meta\nCurrentModule = Documenter\nDocTestSetup = quote\n using Documenter\nend\n```\n\n\n\n\n\n",
"title": "Documenter.Expanders.MetaBlocks"
},
{
"category": "type",
"location": "lib/internals/expanders/#Documenter.Expanders.REPLBlocks",
"page": "Expanders",
"text": "Similar to the ExampleBlocks expander, but inserts a Julia REPL prompt before each toplevel expression in the final document.\n\n\n\n\n\n",
"title": "Documenter.Expanders.REPLBlocks"
},
{
"category": "type",
"location": "lib/internals/expanders/#Documenter.Expanders.SetupBlocks",
"page": "Expanders",
"text": "Similar to the ExampleBlocks expander, but hides all output in the final document.\n\n\n\n\n\n",
"title": "Documenter.Expanders.SetupBlocks"
},
{
"category": "type",
"location": "lib/internals/expanders/#Documenter.Expanders.TrackHeaders",
"page": "Expanders",
"text": "Tracks all Markdown.Header nodes found in the parsed markdown files and stores an Anchors.Anchor object for each one.\n\n\n\n\n\n",
"title": "Documenter.Expanders.TrackHeaders"
},
{
"category": "type",
"location": "lib/internals/selectors/#Documenter.Utilities.Selectors.AbstractSelector",
"page": "Selectors",
"text": "Root selector type. Each user-defined selector must subtype from this, i.e.\n\nabstract type MySelector <: Selectors.AbstractSelector end\n\nabstract type First <: MySelector end\nabstract type Second <: MySelector end\n\n\n\n\n\n",
"title": "Documenter.Utilities.Selectors.AbstractSelector"
},
{
"category": "type",
"location": "lib/internals/utilities/#Documenter.Utilities.Object",
"page": "Utilities",
"text": "Represents an object stored in the docsystem by its binding and signature.\n\n\n\n\n\n",
"title": "Documenter.Utilities.Object"
},
{
"category": "type",
"location": "lib/internals/writers/#Documenter.Plugin",
"page": "Writers",
"text": "abstract type Plugin end\n\nAny plugin that needs to either solicit user input or store information in a Documents.Document should create a subtype of Plugin. The subtype, T <: Documenter.Plugin, must have an empty constructor T() that initialized T with the appropriate default values.\n\nTo retrieve the values stored in T, the plugin can call Documents.getplugin. If T was passed to makedocs, the passed type will be returned. Otherwise, a new T object will be created.\n\n\n\n\n\n",
"title": "Documenter.Plugin"
},
{
"category": "type",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.HTML",
"page": "Writers",
"text": "HTML(kwargs...)\n\nSets the behavior of HTMLWriter.\n\nKeyword arguments\n\nprettyurls (default true) – allows toggling the pretty URLs feature.\n\nBy default (i.e. when prettyurls is set to true), Documenter creates a directory structure that hides the .html suffixes from the URLs (e.g. by default src/foo.md becomes src/foo/index.html, but can be accessed with via src/foo/ in the browser). This structure is preferred when publishing the generate HTML files as a website (e.g. on GitHub Pages), which is Documenter's primary use case.\n\nIf prettyurls = false, then Documenter generates src/foo.html instead, suitable for local documentation builds, as browsers do not normally resolve foo/ to foo/index.html for local files.\n\nTo have pretty URLs disabled in local builds, but still have them enabled for the automatic CI deployment builds, you can set prettyurls = get(ENV, \"CI\", nothing) == \"true\" (the specific environment variable you will need to check may depend on the CI system you are using, but this will work on Travis CI).\n\ndisable_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.\n\nedit_branch specifies which branch, tag or commit the \"Edit on GitHub\" links point to. It defaults to master. If it set to nothing, the current commit will be used.\n\ncanonical specifies the canonical URL for your documentation. We recommend you set this to the base url of your stable documentation, e.g. https://juliadocs.github.io/Documenter.jl/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.\n\nanalytics can be used specify the Google Analytics tracking ID.\n\nassets can be used to include additional assets (JS, CSS, ICO etc. files). See below for more information.\n\nDefault and custom assets\n\nDocumenter 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.\n\nThe HTML output also links certain custom assets to the generated HTML documents, specifically 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).\n\nFor 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.\n\nAdditional JS, ICO, and CSS assets can be included in the generated pages using the assets keyword for makedocs. assets must be a Vector{String} and will include each listed asset in the <head> of every page in the order in which they are listed. 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, or .css. Adding an ICO asset is primarilly useful for setting a custom favicon.\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.HTML"
},
{
"category": "type",
"location": "lib/internals/writers/#Documenter.Writers.HTMLWriter.HTMLContext",
"page": "Writers",
"text": "HTMLWriter-specific globals that are passed to domify and other recursive functions.\n\n\n\n\n\n",
"title": "Documenter.Writers.HTMLWriter.HTMLContext"
},
{
"category": "type",
"location": "lib/internals/writers/#Documenter.Writers.LaTeXWriter.LaTeX",
"page": "Writers",
"text": "LaTeXWriter.LaTeX(; kwargs...)\n\nOutput format specifier that results in LaTeX/PDF output. Used together with makedocs, e.g.\n\nmakedocs(\n format = LaTeX()\n)\n\nThe makedocs argument sitename will be used for the \\title field in the tex document, and if the build is for a release tag (i.e. when the \"TRAVIS_TAG\" environment variable is set) the version number will be appended to the title. The makedocs argument authors should also be specified, it will be used for the \\authors field in the tex document.\n\nKeyword arguments\n\nplatform sets the platform where the tex-file is compiled, either \"native\" (default) or \"docker\". See Other Output Formats for more information.\n\n\n\n\n\n",
"title": "Documenter.Writers.LaTeXWriter.LaTeX"
}
]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment