Lexicon

Exported

doctest(modname::Module)

Run code blocks in the docstrings of the specified module modname. Returns a Summary of the results.

Code blocks may be skipped by adding an extra newline at the end of the block.

Example:

doctest(Lexicon)

source: Lexicon/src/doctest.jl:100

query(f::Function, sig)

Search loaded documentation for methods of generic function f that match sig. Optionally, provide an index (1-based) to view an individual entry if several different ones are found.

source: Lexicon/src/query.jl:157

query(f::Function, sig, index)

Search loaded documentation for methods of generic function f that match sig. Optionally, provide an index (1-based) to view an individual entry if several different ones are found.

source: Lexicon/src/query.jl:157

save(file::AbstractString, index::Lexicon.Index, config::Lexicon.Config)

Saves an API-Index to file.

source: Lexicon/src/render.jl:173

save(file::AbstractString, modulename::Module, config::Lexicon.Config)

Write the documentation stored in modulename to the specified file. The format is guessed from the file's extension. Currently supported formats are HTML and markdown.

Example:

using Lexicon
save("docs/api/Lexicon.md", Lexicon);

using Lexicon, Docile, Docile.Interface
index  = Index()
update!(index, save("docs/api/Lexicon.md", Lexicon));
update!(index, save("docs/api/Docile.md", Docile));
update!(index, save("docs/api/Docile.Interface.md", Docile.Interface));
# save a joined Reference-Index
save("docs/api/api-index.md", index);

MkDocs

Beginning with Lexicon 0.1 you can save documentation as pre-formatted markdown files which can then be post-processed using 3rd-party programs such as the static site generator MkDocs.

For details on how to build documentation using MkDocs please consult their detailed guides and the Docile and Lexicon packages. A more customized build process can be found in the Sims.jl package.

Seealso Projects using Docile / Lexicon

Example:

The documentation for this package can be created in the following manner. All commands are run from the top-level folder in the package.

using Lexicon
index = save("docs/api/Lexicon.md", Lexicon);
save("docs/api/index.md", Index([index]); md_subheader = :category);
run(`mkdocs build`)

From the command line, or using run, push the doc/site directory to the gh-pages branch on the package repository after pushing the changes to the master branch.

git add .
git commit -m "documentation changes"
git push origin master
git subtree push --prefix site origin gh-pages

One can also use the MkDocs option gh-deploy - consult their guides.

using Lexicon
index = save("docs/api/Lexicon.md", Lexicon);
save("docs/api/index.md", Index([index]); md_subheader = :category);
run(`mkdocs gh-deploy --clean`)

If this is the first push to the branch then the site may take some time to become available. Subsequent updates should appear immediately. Only the contents of the doc/site folder will be pushed to the branch.

The documentation will be available from https://USER_NAME.github.io/PACKAGE_NAME/FILE_PATH.html.

source: Lexicon/src/render.jl:162

Lexicon.Config

User adjustable Lexicon configuration.

Options

General Options

  • category_order (default: [:module, :function, :method, :type, :typealias, :macro, :global, :comment]) Categories to include in the output in the defined order.
  • include_internal (default: true): To exclude documentation for non-exported objects, the keyword argument include_internal = false should be set. This is only supported for markdown.
  • metadata_order (default: [:source]) Metadata to include in the output in the defined order. To not output any metadate metadata_order = Symbol[] should be set.

HTML only options

  • mathjax (default: false): If MathJax support is required then the optional keyword argument mathjax = true can be given to the save method. MathJax uses \(...\) for in-line maths and \[...\] or $$...$$ for display equations.

Markdown only options

Valid values for the mdstyle_* options listed below are either 1 to 6 # characters or 0 to 2 * characters.

  • mdstyle_header (default: "#"): style for the documentation header and API-Index modules header.
  • mdstyle_objname (default: "####"): style for each documented object.
  • mdstyle_meta (default: "*"): style for the metadata section on each documentation entry.
  • mdstyle_subheader (default: "##"): style for the documentation and API-Index subheader.

  • mdstyle_index_mod (default: "##"): style for the API-Index module header.

  • md_subheader (default: :simple): Valid options are ":skip, :simple, :category"

    • md_subheader=:simple adds documentation and API-Index subheaders "Exported" / "Internal".
    • md_subheader=:category adds documentation and API-Index subheaders per category.
    • md_subheader=:skip adds no subheaders to the documentation and API-Index and can be used for documentation which has only few entries.

  • md_index_modprefix (default: "MODULE: "): This option sets for the API-Index Page a "prefix" text before the modulename. md_genindex_module_prefix = "" if only the modulename should be displayed.

  • md_permalink (default: true): Adds a a permalink to each definition. To disable it the keyword argument md_permalink = false should be set.

Any option can be user adjusted by passing keyword arguments to the save method.

Config Usage

There are 3 ways to define user adjusted configuration settings.

Config

using Lexicon

# get default `Config`
config = Config()

# get a new adjusted `Config`
config = Config(md_permalink = false, mathjax = true)

Document save method

The document save method accepts also a 'Config' as argument or supplies internaly a default one. Similar to the above 'Config usage' one can also pass otional args... which will overwrite a deepcopy of config but not change config itself. This allows using the same base configuration settings multiple times.

using Lexicon

# 1. get a new adjusted `Config`
config = Config(md_permalink = false, mathjax = true)

# 2.using the adjusted `Config`
save("docs/api/Lexicon.md", Lexicon, config);

# 3.overwrite a deepcopy of `config`
save("docs/api/Lexicon.md", Lexicon, config; md_permalink = true);

# 4. This uses the same configuration as set in '1.' (md_permalink is still `false`)
save("docs/api/Lexicon.md", Lexicon, config);

The document save also supplies a default 'Config'.

using Lexicon

# 1. using the default supplied Config of method `save`
save("docs/api/Lexicon.md", Lexicon);

# 2. this is the same as '1.'
config = Config()
save("docs/api/Lexicon.md", Lexicon, config);

The next three examples are all using the same configuration to save Lexicon

using Lexicon

# 1.
config = Config(md_permalink = false, mathjax = true)
save("docs/api/Lexicon.md", Lexicon, config);

# 2.
config = Config()
save("docs/api/Lexicon.md", Lexicon, config; md_permalink = false, mathjax = true);

# 3.
save("docs/api/Lexicon.md", Lexicon; md_permalink = false, mathjax = true);

API-Index save method

The API-Index save method works similar to the above Document save method

source: Lexicon/src/render.jl:11

Lexicon.EachEntry

Iterator type for Metadata Entries with sorting options.

Constructors

EachEntry(docs::Metadata; order = [:category, :name, :source])

Arguments

  • docs : main input

Optional keyword arguments

  • order : indicators of sorting order, given in priority, options include:
  • :category - category of Entries
  • :exported - whether the item is exported or unexported
  • :name - name of Entries
  • :source - source location of Entries uses both the file path and line number

In addition to symbols, items in order can be functions of the form (x,y) = ... where x is the documented item, and y is the Entry. The function should return a quantity to be compared when sorting.

Main methods

An iterable, supports start, next, and done. next returns a (key, value) pair where the key is the ObjectId key, and value is the Entry.

Example

using Lexicon, Docile, Docile.Interface
d = metadata(Docile);

# Collect the source location of each Entry sorted by the default
# (:category then :name then :source).
res = [v.data[:source][2] for (k,v) in EachEntry(d)]

source: Lexicon/src/filtering.jl:127

@query(args...)

Create a Query object from the provided args. The resulting query can then be run to retrieve matching results from currently loaded documentation.

This is a low-level interface. For everyday usage in the REPL rather use the built-in ? mode, which Lexicon hooks into automatically.

The first argument must be the expression to search for. Supported expressions include method calls, macros, constants, types, functions, and strings. An optional integer argument may be used to only show documentation from one of several results.

Example:

q = @query Lexicon.@query
run(q)

q = @query Lexicon.save 2
run(q)

Note: When searching documentation for an operator (+, -, etc.) it should be enclosed in parentheses:

q = @query (+) 4
run(q)

source: Lexicon/src/query.jl:98

Internal

calculate_score(query, text, object)

Basic text importance scoring.

source: Lexicon/src/query.jl:178

call(::Type{Lexicon.Config})

Returns a default Config. If any args... are given these will overwrite the defaults.

using Lexicon
config = Config(md_permalink = false, mathjax = true)

source: Lexicon/src/render.jl:50

call(::Type{Lexicon.EachEntry}, docs::Docile.Legacy.Metadata)

Constructor.

Example

using Lexicon, Docile, Docile.Interface
docs = metadata(Docile);
EachEntry(docs::Metadata; order = [:category, :name, :source])

source: Lexicon/src/filtering.jl:143

filter(docs::Docile.Legacy.Metadata)

Filter Metadata based on categories or file source.

Arguments

  • docs : main input

Optional keyword arguments

  • categories : categories to include in the result; can include any of [:module, :function, :method, :type, :typealias, :macro, :global, :comment]; defaults to all but :comment

  • files : vector of file names where entries originated to include in the result; full pathnames are searched; can include partial paths; defaults to all

Returns

  • ::Metadata : the filtered result

Example

using Lexicon, Docile, Docile.Interface
d = metadata(Docile);

# Filter entries with categories of :macro and :type
entries( filter(d, categories = [:macro, :type]) )

# Filter entries from the file types.jl
entries( filter(d, files = ["types.jl"]) )

source: Lexicon/src/filtering.jl:40

filter(f::Function, docs::Docile.Legacy.Metadata)

Filter Metadata based on a function.

Arguments

  • f : a function that filters Entries and returns a Bool; the function signature should be f(x::Entry).
  • docs : main input

Returns

  • ::Metadata : the filtered result

Example

using Lexicon, Docile, Docile.Interface
d = metadata(Docile);

# Filter entries with all categories except :type
res = filter(d) do e
    category(e) != :type
end

source: Lexicon/src/filtering.jl:77

Lexicon.Match

An entry and the set of all objects that are linked to it.

source: Lexicon/src/query.jl:32

Lexicon.Query

Holds the parsed user query.

Fields:

  • objects: The objects that will be searched for in metadata.
  • mods: Modules to be searched through for documentation.
  • index: 1-based, for picking an individual entry to display out of a list.

source: Lexicon/src/query.jl:13

Lexicon.QueryResults

Stores the matching entries resulting from running a query.

source: Lexicon/src/query.jl:42

Queryable

Types that can be queried.

source: Lexicon/src/query.jl:2