API
The DocInventories
package exports two names:
All other names should either be imported explicitly, e.g.,
using DocInventories: uri, spec
for uri
and spec
, or used with the DocInventories
prefix, e.g., DocInventories.save
.
In typical usage, the following non-exported I/O routines would be commonly used:
DocInventories.MIME_TYPES
— ConstantDefault map of file extensions to MIME types.
MIME_TYPES = Dict(
+ ".txt" => MIME("text/x-intersphinx"),
+ ".inv" => MIME("application/x-intersphinx"),
+ ".toml" => MIME("application/toml"),
+ ".txt.gz" => MIME("text/x-intersphinx+gzip"),
+ ".toml.gz" => MIME("application/toml+gzip"),
+)
DocInventories.Inventory
— TypeAn inventory link targets in a project documentation.
inventory = Inventory(
+ source;
+ mime=auto_mime(source),
+ root_url=root_url(source)
+)
loads an inventory file from the given source
, which can be a URL or the path to a local file. If it is a URL, the options timeout
(seconds to wait for network connections), retries
(number of times to retry) and wait_time
(seconds longer to wait between each retry) may be given. The source
must contain data in the given mime type. By default, the mime type is derived from the file extension, via auto_mime
.
The Inventory
acts as a collection of InventoryItems
, representing all the objects, sections, or other linkable items in the online documentation of a project.
Alternatively,
inventory = Inventory(; project, version="", root_url="", items=[])
with a mandatory project
argument instantiates an inventory
with the IventoryItems
in items
. If items
is not given, the resulting empty inventory
can have InventoryItems
added afterwards via push!
.
Attributes
project
: The name of the projectversion
: The version of the project (e.g.,"1.0.0"
)root_url
: The root URL to which theitem.uri
of anyInventoryItem
is relative. If not empty, should start with"https://"
and end with a slash.source
: The URL or filename from which the inventory was loaded, or a comment if the inventory was constructed otherwise.sorted
: A boolean to indicate whether the items are sorted by theirname
attribute, allowing for efficient lookup. This istrue
for all inventories loaded from a URL or file andfalse
for manually instantiated inventories.
Item access
Items can be accessed via iteration (for item in inventory
), by numeric index (inventory[1]
, inventory[2]
, … inventory[end]
), or by lookup: inventory[name]
or inventory[spec]
, where spec
is a string of the form ":[domain:]role:`name`"
, see the discussion of spec
in InventoryItem
. The lookup delegates to find_in_inventory
with quiet=true
and takes into account item.priority
.
Search
The inventory can be searched by calling inventory(search; include_hidden_priority=true)
. This returns a list of all items that contain search
in spec(item)
or repr(item; context=(:full => true))
. Typically, search
would be a string or a Regex
. Some examples for common searches:
- A
spec
of the form":domain:role:`name`"
, in full, partially, or as a regex. - Part of a url of a page in the project's documentation, as a string
- The title of a section as it appears somewhere in the project's documentation.
The search results are sorted by abs(item.priority)
. If include_hidden_priority=false
, negative item.priority
values are omitted.
Methods
find_in_inventory(inventory, name)
– find a single item in theinventory
save(filename, inventory; mime=auto_mime(filename))
– write theinventory
to a file in any supported output format.show_full(inventory)
– show the unabbreviated inventory in the REPL (ideally viaTerminalPager
)uri(inventory, key)
– obtain the full URI for an item from theinventory
.push!(inventory, items...)
– addInventoryItems
to an existinginventory
.append!(inventory, collections...)
– add collections ofInventoryItems
to an existinginventory
.collect(inventory)
– convert the inventory to a standardVector
ofInventoryItems
.set_metadata(inventory)
– Modify theproject
andversion
metadata.sort(inventory)
– convert an unsorted inventory into a sorted one.
DocInventories.InventoryFormatError
— TypeAn error indicating an issue with an inventory file.
throw(InventoryFormatError(msg))
DocInventories.InventoryItem
— TypeAn item inside an Inventory
.
item = InventoryItem(; name, role, uri, priority=1, domain="jl", dispname="-")
represents a linkable item inside a project documentation, referenced by name
. The domain
and role
take their semantics from the Sphinx project, see Attributes for details on these parameters, as well as priority
and dispname
. The uri
is relative to a project root, which should be the Inventory.root_url
of the inventory
containing the InventoryItem
.
For convenience, an InventoryItem
can also be instantiated from a mapping spec => uri
, where spec=":domain:role:`name`"
borrows from Sphinx' cross-referencing syntax:
item = IventoryItem(
+ ":domain:role:`name`" => uri;
+ dispname=<name>,
+ priority=(<domain == "std" ? -1 : 1>)
+)
The domain
is optional: if spec=":role:`name`"
, the domain
is "std"
for role="label"
or role="doc"
, and "jl"
otherwise. The role
is mandatory for code objects. For non-code objects,
item = IventoryItem(
+ "title" => uri;
+ dispname=<title>,
+ priority=-1
+)
indicates a link to a section header in the documentation of a project. The name
will be a sluggified version of the title, making the item
equivalent to item = IventoryItem(":std:label:`name`" => uri; dispname=title, priority=-1)
.
Attributes
name
: The object name for referencing. For code objects, this should be the fully qualified name. For section names, it may be a slugified version of the section title. It must have non-zero length.domain
: The name of a Sphinx domain. Should be"jl"
for Julia code objects (default),"py"
for Python code objects, and"std"
for text objects such as section names. Must have non-zero length, and must not contain whitespace or a colon.role
: A domain-specific role (type). Must have nonzero length and not contain whitespace.priority
: An integer flag for placement in search results. Used when searching in anInventory
, for item access in anInventory
, and withfind_in_inventory
. The following flag values are supported:1
: the "default" priority. Used by default for all objects not in the"std"
domain (that is, all "code" objects such as those in the"jl"
domain).0
: object is important2
(or higher): object is unimportant-1
(or lower): object is "hidden" (may be omitted from search). Used by default for all objects in thestd
domain (section titles)
See
find_in_inventory
for details. The above semantics match those used by Sphinx.uri
: A URI for the location of the object's documentation, relative to the location of the inventory file containing theitem
. Must not contain whitespace. May end with"$"
to indicate a placeholder forname
(usually as"#$"
, for an HTML anchor matchingname
).dispname
: A full plain text representation of the object. May be"-"
if the display name is identical toname
(which it should be for code objects). For section titles, this should be the plain text of the title, without formatting, but not slugified.
Methods
DocInventories.auto_mime
— MethodDetermine the MIME type of the given file path or URL from the file extension.
mime = auto_mime(source)
returns a MIME
type from the extension of source
. The default mapping is in MIME_TYPES
.
Unknown or unsupported extensions throw an ArgumentError
.
DocInventories.convert
— MethodConvert an inventory file.
DocInventories.convert("objects.inv", "inventory.toml")
converts the input file "objects.inv"
in the Sphinx Inventory Format to the TOML Format "inventory.toml"
.
This is a convenience function to simply load an Inventory
from the input file and write it to the output file. Both the input and output file must have known file extensions. The project
and version
metadata may be given as additional keyword arguments to be written to the output file, see set_metadata
.
DocInventories.dispname
— MethodObtain the full display name for an InventoryItem
.
display_name = dispname(item)
returns item.dispname
with "-"
expanded to item.name
.
DocInventories.find_in_inventory
— MethodFind an item in the inventory.
item = find_in_inventory(
+ inventory,
+ name;
+ domain="",
+ role="",
+ quiet=false,
+ include_hidden_priority=true
+)
returns the top priority InventoryItem
matching the given name
. If the inventory
contains no matching item, returns nothing
.
Arguments
inventory
: TheInventory
to search.name
: The value of thename
attribute of theInventoryItem
to find. Must match exactly.domain
: If not empty, restrict search to items with a matchingdomain
attribute.role
: If not empty, restrict search to items with a matchingrole
attribute.quiet
: Iffalse
(default), log a warning if the item specification is ambiguous (the top priority item of multiple candidates is returned). If no matching item can be found, an error will be logged in addition to returningnothing
.include_hidden_priority
: Whether or not to consider items with a negativepriority
attribute. If "hidden" items are included (default), they are sorted by the absolute value of thepriority
. That is, items withpriority=-1
andpriority=1
are considered to be equivalent.
Note that direct item lookup as inventory[spec]
where spec
is a string of the form "[:[domain:]role:]`name`"
is available as a simplified way to call find_in_inventory
with quiet=true
.
DocInventories.root_url
— MethodObtain the root url from an inventory source.
url = root_url(source; warn=true)
returns the root url as determined by split_url
if source
starts with "https://"
or "http://"
, or an empty string otherwise (if source
is a local file path). An empty root url will emit a warning unless warn=false
.
DocInventories.save
— MethodWrite the Inventory
to file in the specified format.
DocInventories.save(filename, inventory; mime=auto_mime(filename))
writes inventory
to filename
in the specified MIME type. By default, the MIME type is derived from the file extension of filename
via auto_mime
.
DocInventories.set_metadata
— MethodModify the project
and version
metadata of an inventory or inventory file.
new_inventory = set_metadata(
+ inventory;
+ version=inventory.version,
+ project=inventory.project
+)
returns a new Inventory
with a modified version
and/or project
attribute.
set_metadata(
+ filename;
+ mime=auto_mime(filename),
+ project=Inventory(filename).project,
+ version=Inventory(filename).version,
+)
modifies the project
and/or version
in the given inventory file (objects.inv
, inventory.toml
, etc.)
DocInventories.show_full
— Methodshow_full(item) # io=stdout
+show_full(io, item)
is equivalent to
show(IOContext(io, :full => true), "text/plain", item)
and shows the InventoryItem
with all attributes.
DocInventories.show_full
— Methodshow_full(inventory) # io=stdout
+show_full(io, inventory)
is equivalent to
show(IOContext(io, :limit => false), "text/plain", inventory)
and shows the entire inventory
without truncating the list of items. This may produce large output, so you may want to make use of the TerminalPager
package.
DocInventories.spec
— MethodReturn the specification string of an InventoryItem
.
item_spec = spec(item)
returns a string of the form ":domain:role:`name`"
using the attributes of the given item
.
DocInventories.split_url
— MethodSplit a URL into a root URL and a filename.
root_url, filename = split_url(url)
splits url
at the last slash. This behaves like splitdir
, but operates on URLs instead of file paths. The URL must start with "https://"
or "http://"
.
DocInventories.uri
— Methoduri_str = uri(inventory, key)
is equivalent to uri(inventory[key]; root_url=inventory.root_url)
.
DocInventories.uri
— Methoduri_str = uri(item; root_url="")
fully expands item.uri
and prepends root_url
.