From 3dbe7da8dac9a4671de80fdbb2a9b5cb2b6f148f Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Wed, 27 Mar 2024 03:54:45 +0000 Subject: [PATCH] build based on f934130 --- previews/PR10/.documenter-siteinfo.json | 2 +- previews/PR10/api/index.html | 14 +++++++------- previews/PR10/creating/index.html | 2 +- previews/PR10/formats/index.html | 2 +- previews/PR10/index.html | 2 +- previews/PR10/objects.inv | Bin 805 -> 809 bytes previews/PR10/usage/index.html | 2 +- 7 files changed, 12 insertions(+), 12 deletions(-) diff --git a/previews/PR10/.documenter-siteinfo.json b/previews/PR10/.documenter-siteinfo.json index f830987..0c5b087 100644 --- a/previews/PR10/.documenter-siteinfo.json +++ b/previews/PR10/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.10.2","generation_timestamp":"2024-03-27T03:50:40","documenter_version":"1.3.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.10.2","generation_timestamp":"2024-03-27T03:54:41","documenter_version":"1.3.0"}} \ No newline at end of file diff --git a/previews/PR10/api/index.html b/previews/PR10/api/index.html index 38c9052..dc373ca 100644 --- a/previews/PR10/api/index.html +++ b/previews/PR10/api/index.html @@ -5,11 +5,11 @@ ".toml" => MIME("application/toml"), ".txt.gz" => MIME("text/x-intersphinx+gzip"), ".toml.gz" => MIME("application/toml+gzip"), -)

See Inventory File Formats for details.

source
DocInventories.Inventory — Type

An inventory of link targets in a project documentation.

inventory = Inventory(
+)

See Inventory File Formats for details.

source
DocInventories.Inventory — Type

An inventory of 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 InventoryItems in items. If items is not given, the resulting empty inventory can have InventoryItems added afterwards via push!.

Attributes

  • project: The name of the project
  • version: The version of the project (e.g., "1.0.0")
  • root_url: The root URL to which the item.uri of any InventoryItem 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.
  • sorted: A boolean to indicate whether the items are sorted by their name attribute, allowing for efficient lookup. This is true for all inventories loaded from a URL or file and false for manually instantiated inventories.

Note that source and sorted are informational attributes only and are ignored when comparing two Inventory objects.

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

source
DocInventories.InventoryFormatError — Type

An error indicating an issue with an inventory file.

throw(InventoryFormatError(msg))
source
DocInventories.InventoryItem — Type

An 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 = InventoryItem(
+)

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 InventoryItems in items. If items is not given, the resulting empty inventory can have InventoryItems added afterwards via push!.

Attributes

  • project: The name of the project
  • version: The version of the project (e.g., "1.0.0")
  • root_url: The root URL to which the item.uri of any InventoryItem 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.
  • sorted: A boolean to indicate whether the items are sorted by their name attribute, allowing for efficient lookup. This is true for all inventories loaded from a URL or file and false for manually instantiated inventories.

Note that source and sorted are informational attributes only and are ignored when comparing two Inventory objects.

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

source
DocInventories.InventoryFormatError — Type

An error indicating an issue with an inventory file.

throw(InventoryFormatError(msg))
source
DocInventories.InventoryItem — Type

An 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 = InventoryItem(
     ":domain:role:`name`" => uri;
     dispname=<name>,
     priority=(<domain == "std" ? -1 : 1>)
@@ -17,14 +17,14 @@
     "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 = InventoryItem(":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 an Inventory, for item access in an Inventory, and with find_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 important
    • 2 (or higher): object is unimportant
    • -1 (or lower): object is "hidden" (may be omitted from search). Used by default for all objects in the std 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 the item. Must not contain whitespace. May end with "$" to indicate a placeholder for name (usually as "#$", for an HTML anchor matching name).

  • dispname: A full plain text representation of the object. May be "-" if the display name is identical to name (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

  • uri – Extract the full URI, resolving the $ placeholder and prepending a root_url, if applicable.
  • dispname – Extract the dispname, resolving the "-" shorthand, if applicable.
  • spec – Return the specification string ":domain:role:`name`" associated with the item
source
DocInventories.auto_mime — Method

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

source
DocInventories.convert — Method

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

source
DocInventories.dispname — Method

Obtain the full display name for an InventoryItem.

display_name = dispname(item)

returns item.dispname with "-" expanded to item.name.

source
DocInventories.find_in_inventory — Method

Find an item in the inventory.

item = find_in_inventory(
+)

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 = InventoryItem(":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 an Inventory, for item access in an Inventory, and with find_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 important
    • 2 (or higher): object is unimportant
    • -1 (or lower): object is "hidden" (may be omitted from search). Used by default for all objects in the std 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 the item. Must not contain whitespace. May end with "$" to indicate a placeholder for name (usually as "#$", for an HTML anchor matching name).

  • dispname: A full plain text representation of the object. May be "-" if the display name is identical to name (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

  • uri – Extract the full URI, resolving the $ placeholder and prepending a root_url, if applicable.
  • dispname – Extract the dispname, resolving the "-" shorthand, if applicable.
  • spec – Return the specification string ":domain:role:`name`" associated with the item
source
DocInventories.auto_mime — Method

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

source
DocInventories.convert — Method

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

source
DocInventories.dispname — Method

Obtain the full display name for an InventoryItem.

display_name = dispname(item)

returns item.dispname with "-" expanded to item.name.

source
DocInventories.find_in_inventory — Method

Find 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: The Inventory to search.
  • name: The value of the name attribute of the InventoryItem to find. Must match exactly.
  • domain: If not empty, restrict search to items with a matching domain attribute.
  • role: If not empty, restrict search to items with a matching role attribute.
  • quiet: If false (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 returning nothing.
  • include_hidden_priority: Whether or not to consider items with a negative priority attribute. If "hidden" items are included (default), they are sorted by the absolute value of the priority. That is, items with priority=-1 and priority=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.

source
DocInventories.root_url — Method

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

source
DocInventories.save — Method

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

source
DocInventories.set_metadata — Method

Modify the project and version metadata of an inventory or inventory file.

new_inventory = set_metadata(
+)

returns the top priority InventoryItem matching the given name. If the inventory contains no matching item, returns nothing.

Arguments

  • inventory: The Inventory to search.
  • name: The value of the name attribute of the InventoryItem to find. Must match exactly.
  • domain: If not empty, restrict search to items with a matching domain attribute.
  • role: If not empty, restrict search to items with a matching role attribute.
  • quiet: If false (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 returning nothing.
  • include_hidden_priority: Whether or not to consider items with a negative priority attribute. If "hidden" items are included (default), they are sorted by the absolute value of the priority. That is, items with priority=-1 and priority=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.

source
DocInventories.root_url — Method

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

source
DocInventories.save — Method

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

source
DocInventories.set_metadata — Method

Modify the project and version metadata of an inventory or inventory file.

new_inventory = set_metadata(
     inventory;
     version=inventory.version,
     project=inventory.project
@@ -33,6 +33,6 @@
     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.)

source
DocInventories.show_full — Method
show_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.

source
DocInventories.show_full — Method
show_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.

source
DocInventories.spec — Method

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

source
DocInventories.split_url — Method

Split 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://".

source
DocInventories.uri — Method
uri_str = uri(inventory, key)

is equivalent to uri(inventory[key]; root_url=inventory.root_url).

source
DocInventories.uri — Method
uri_str = uri(item; root_url="")

fully expands item.uri and prepends root_url.

source
+)

modifies the project and/or version in the given inventory file (objects.inv, inventory.toml, etc.)

source
DocInventories.show_full — Method
show_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.

source
DocInventories.show_full — Method
show_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.

source
DocInventories.spec — Method

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

source
DocInventories.split_url — Method

Split 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://".

source
DocInventories.uri — Method
uri_str = uri(inventory, key)

is equivalent to uri(inventory[key]; root_url=inventory.root_url).

source
DocInventories.uri — Method
uri_str = uri(item; root_url="")

fully expands item.uri and prepends root_url.

source
diff --git a/previews/PR10/creating/index.html b/previews/PR10/creating/index.html index a3f18c8..1af4e14 100644 --- a/previews/PR10/creating/index.html +++ b/previews/PR10/creating/index.html @@ -31,4 +31,4 @@ [[std.doc]] dispname = "Python (programming language)" name = "Python" -uri = "Python_(programming_language)"

The requirements for the file are in the description of the TOML Format, but should be fairly intuitive.

In general, custom inventory files should be stored as an uncompressed .toml file. This makes them much easier to maintain with a text editor. In addition, these inventories will presumably be checked into a git repository, which will be much more efficient with uncompressed (diffable!) text-based files.

In contrast, inventories that are deployed (put online so that other projects may download them to resolve links) should always be compressed, either as an objects.inv file or as an inventory.toml.gz file.

+uri = "Python_(programming_language)"

The requirements for the file are in the description of the TOML Format, but should be fairly intuitive.

In general, custom inventory files should be stored as an uncompressed .toml file. This makes them much easier to maintain with a text editor. In addition, these inventories will presumably be checked into a git repository, which will be much more efficient with uncompressed (diffable!) text-based files.

In contrast, inventories that are deployed (put online so that other projects may download them to resolve links) should always be compressed, either as an objects.inv file or as an inventory.toml.gz file.

diff --git a/previews/PR10/formats/index.html b/previews/PR10/formats/index.html index e123cb4..71f472b 100644 --- a/previews/PR10/formats/index.html +++ b/previews/PR10/formats/index.html @@ -8,4 +8,4 @@ name = "<name>" uri = "<uri>" dispname = "<dispname>" -priority = <priority>

The four lines for name, uri, dispname, and priority may occur in any order. Also, for items with the default priority (-1 for the std domain, 1 otherwise), the priority line may be omitted. If dispname is equal to name (usually indicated by dispname="-"), the dispname line may also be omitted.

The item-blocks may be grouped/separated by blank lines. In .toml files generated by DocInventories.save("inventory.toml", inventory) items will be grouped into blocks with the same [[<domain>.<role>]] with a blank line between each block.

Any TOML parser should read a .toml file with the above structure into a nested dictionary, so that item_dict = toml_data[domain][role][i] corresponds to the i'th inventory item with the given domain and role. That item_dict will then map "name", "uri", and potentially "dispname" and "priority" to their respective values.

A compressed TOML file can be written with, e.g., DocInventories.save("inventory.toml.gz", inventory). With compression, the size of the file should be comparable (albeit slightly larger) than the compressed objects.inv format.

Size Comparison

In the following table, we compare the size of the inventory file of different projects in kilobytes, for the various output formats.

ProjectNo. of Objects.txt.toml.inv.toml.gz
Documenter49854.7 kB66.0 kB8.5 kB8.7 kB
Julia3602250.0 kB324.6 kB45.0 kB45.9 kB
Matplotlib104311113.5 kB1327.2 kB106.2 kB111.1 kB
Python165051086.9 kB1401.3 kB141.1 kB147.2 kB
+priority = <priority>

The four lines for name, uri, dispname, and priority may occur in any order. Also, for items with the default priority (-1 for the std domain, 1 otherwise), the priority line may be omitted. If dispname is equal to name (usually indicated by dispname="-"), the dispname line may also be omitted.

The item-blocks may be grouped/separated by blank lines. In .toml files generated by DocInventories.save("inventory.toml", inventory) items will be grouped into blocks with the same [[<domain>.<role>]] with a blank line between each block.

Any TOML parser should read a .toml file with the above structure into a nested dictionary, so that item_dict = toml_data[domain][role][i] corresponds to the i'th inventory item with the given domain and role. That item_dict will then map "name", "uri", and potentially "dispname" and "priority" to their respective values.

A compressed TOML file can be written with, e.g., DocInventories.save("inventory.toml.gz", inventory). With compression, the size of the file should be comparable (albeit slightly larger) than the compressed objects.inv format.

Size Comparison

In the following table, we compare the size of the inventory file of different projects in kilobytes, for the various output formats.

ProjectNo. of Objects.txt.toml.inv.toml.gz
Documenter49854.7 kB66.0 kB8.5 kB8.7 kB
Julia3602250.0 kB324.6 kB45.0 kB45.9 kB
Matplotlib104311113.5 kB1327.2 kB106.2 kB111.1 kB
Python165051086.9 kB1401.3 kB141.1 kB147.2 kB
diff --git a/previews/PR10/index.html b/previews/PR10/index.html index a851180..1b9bc93 100644 --- a/previews/PR10/index.html +++ b/previews/PR10/index.html @@ -1,2 +1,2 @@ -Home · DocInventories.jl
GitHub

DocInventories.jl

Github v0.4.0

DocInventories.jl is a package for reading and writing inventory files such as the objects.inv file written by Documenter.jl ≥ v1.3.0 and Sphinx.

These inventory files are used by DocumenterInterLinks.jl and InterSphinx to enable linking between the documentation of two projects.

The DocInventories package also allows to convert the objects.inv format to an inventory.toml format that is designed to be human-readable and to allow maintaining custom inventories by hand. The package is intended for use in the REPL, to interactively explore inventory files, and as a backend for DocumenterInterLinks.

Installation

As usual, that package can be installed via

] add DocInventories

in the Julia REPL, or by adding

DocInventories = "43dc2714-ed3b-44b5-b226-857eda1aa7de"

to the relevant Project.toml file.

Contents

  • Documenter.jl — The default documentation generator in the Julia ecosystem. As of version 1.3.0, Documenter automatically generates and deploys a (Sphinx-format) objects.inv file that enables linking into a project's documentation.
  • DocumenterInterLinks.jl – A plugin for Documenter to enable linking to any other project that has an inventory file, i.e., any project using a recent version of Documenter to build its documentation, or any project using Sphinx. It is the Julia-equivalent of Sphinx' Intersphinx plugin.
  • Sphinx – The default documentation generator in the Python ecosystem. Sphinx originated the objects.inv inventory file format now also generated for Julia projects by Documenter.
  • sphobjinv – The Python-equivalent of this project, allowing to read, explore and manipulate the data in objects.inv inventory file. Note that this does not include support for the inventory.toml format, which is unique to DocInventories.
+Home · DocInventories.jl
GitHub

DocInventories.jl

Github v0.4.0+dev

DocInventories.jl is a package for reading and writing inventory files such as the objects.inv file written by Documenter.jl ≥ v1.3.0 and Sphinx.

These inventory files are used by DocumenterInterLinks.jl and InterSphinx to enable linking between the documentation of two projects.

The DocInventories package also allows to convert the objects.inv format to an inventory.toml format that is designed to be human-readable and to allow maintaining custom inventories by hand. The package is intended for use in the REPL, to interactively explore inventory files, and as a backend for DocumenterInterLinks.

Installation

As usual, that package can be installed via

] add DocInventories

in the Julia REPL, or by adding

DocInventories = "43dc2714-ed3b-44b5-b226-857eda1aa7de"

to the relevant Project.toml file.

Contents

  • Documenter.jl — The default documentation generator in the Julia ecosystem. As of version 1.3.0, Documenter automatically generates and deploys a (Sphinx-format) objects.inv file that enables linking into a project's documentation.
  • DocumenterInterLinks.jl – A plugin for Documenter to enable linking to any other project that has an inventory file, i.e., any project using a recent version of Documenter to build its documentation, or any project using Sphinx. It is the Julia-equivalent of Sphinx' Intersphinx plugin.
  • Sphinx – The default documentation generator in the Python ecosystem. Sphinx originated the objects.inv inventory file format now also generated for Julia projects by Documenter.
  • sphobjinv – The Python-equivalent of this project, allowing to read, explore and manipulate the data in objects.inv inventory file. Note that this does not include support for the inventory.toml format, which is unique to DocInventories.
diff --git a/previews/PR10/objects.inv b/previews/PR10/objects.inv index 8931ed7ec7380d3f65dd5de64017a54d1e7cf8b7..e3adeb94548aababb1d4b4dc339ce0d06735267a 100644 GIT binary patch delta 15 WcmZ3=wvugv7mIdEYS~7w+e`o|Jq3FJ delta 10 RcmZ3

The search results will be sorted taking into account the priority field of the items.

Manipulating Inventories

Inventory objects are immutable, with the exception that new InventoryItems can be added to an existing Inventory using push! and append!.

Beyond that, DocInventories.set_metadata can modify the metadata (project and version) both of an Inventory object and an inventory file on disk, but the operation is in-place only for files.

These tools are primarily intended to tweak the inventories automatically generated by Documenter.makedocs, e.g., to set a custom version for a dev-release (alternatively to the inventory_version option in Documenter.HTMLWriter.HTML in Documenter >= 1.3.0), or to use a different project name than the standard project in makedocs. These modifications should be made after the call to Documenter.makedocs, but before Documenter.deploydocs.

Saving Inventories to File

An inventory can be written to file using the DocInventories.save function. For example, to write the inventory in TOML Format, use

DocInventories.save("$(tempname()).toml", inventory)

The MIME type is derived from the extension of the file name, according to the mapping in DocInventories.MIME_TYPES. The MIME-type can also be passed explicitly to save, independent of the file name:

DocInventories.save(tempname(), inventory; mime="application/toml")

It is also possible to write with compression by appending a .gz file extension:

DocInventories.save("$(tempname()).toml.gz", inventory)

See Inventory File Formats for a description of all available output formats.

  • 1We conflate Sphinx' "object types" and "roles". Technically, a Sphinx domain (like the Python py domain) has object types (e.g., function) which in turn have one or more associated roles that are used when referencing the object (e.g., func). DocInventories has no formal definition of domains/types/roles, so it considers types and roles identical. Consequently, a Sphinx reference ":py:func:`matplotlib.pyplot.subplots`" would correspond to the DocInventories spec ":py:function:`matplotlib.pyplot.subplots`".
+ InventoryItem(":std:doc:`manual/workflow-tips`" => "manual/workflow-tips/", dispname="Workflow Tips")

The search results will be sorted taking into account the priority field of the items.

Manipulating Inventories

Inventory objects are immutable, with the exception that new InventoryItems can be added to an existing Inventory using push! and append!.

Beyond that, DocInventories.set_metadata can modify the metadata (project and version) both of an Inventory object and an inventory file on disk, but the operation is in-place only for files.

These tools are primarily intended to tweak the inventories automatically generated by Documenter.makedocs, e.g., to set a custom version for a dev-release (alternatively to the inventory_version option in Documenter.HTMLWriter.HTML in Documenter >= 1.3.0), or to use a different project name than the standard project in makedocs. These modifications should be made after the call to Documenter.makedocs, but before Documenter.deploydocs.

Saving Inventories to File

An inventory can be written to file using the DocInventories.save function. For example, to write the inventory in TOML Format, use

DocInventories.save("$(tempname()).toml", inventory)

The MIME type is derived from the extension of the file name, according to the mapping in DocInventories.MIME_TYPES. The MIME-type can also be passed explicitly to save, independent of the file name:

DocInventories.save(tempname(), inventory; mime="application/toml")

It is also possible to write with compression by appending a .gz file extension:

DocInventories.save("$(tempname()).toml.gz", inventory)

See Inventory File Formats for a description of all available output formats.

  • 1We conflate Sphinx' "object types" and "roles". Technically, a Sphinx domain (like the Python py domain) has object types (e.g., function) which in turn have one or more associated roles that are used when referencing the object (e.g., func). DocInventories has no formal definition of domains/types/roles, so it considers types and roles identical. Consequently, a Sphinx reference ":py:func:`matplotlib.pyplot.subplots`" would correspond to the DocInventories spec ":py:function:`matplotlib.pyplot.subplots`".