Creating and Using a Custom objects.inv¶
The workflow presented here is introduced in the context of manually assembling an objects inventory, but the functionality is mainly intended for use downstream of a web-scraping or other automated content-extraction tool.
A (possibly obsolete) representative example of such a custom objects.inv can be found at the GitHub repo here.
Note
These instructions are for sphobjinv v2.0; the prior instructions for v1.0 can be found here.
Identify the head of the URI to the documentation.
Construct an
Inventory
containing all of the objects of interest. Theuri
anddispname
values can be entered with or without the standard abbreviations.Create an empty
Inventory
:>>> import sphobjinv as soi >>> inv = soi.Inventory() >>> print(inv) <Inventory (manual): None vNone, 0 objects>
Define the
project
andversion
attributes:>>> inv.project = 'foobar' >>> inv.version = '1.5' >>> print(inv) <Inventory (manual): foobar v1.5, 0 objects>
Append new
DataObjStr
instances toobjects
as needed to populate the inventory:>>> o = soi.DataObjStr(name='baz', domain='py', role='class', ... priority='1', uri='api.html#$', dispname='-') >>> print(o) <DataObjStr:: :py:class:`baz`> >>> inv.objects.append(o) >>> print(inv) <Inventory (manual): foobar v1.5, 1 objects> >>> inv.objects.append(soi.DataObjStr(name='baz.quux', domain='py', ... role='method', priority='1', uri='api.html#$', dispname='-')) >>> inv.objects.append(soi.DataObjStr(name='quuux', domain='py', ... role='function', priority='1', uri='api.html#$', dispname='-')) >>> print(inv) <Inventory (manual): foobar v1.5, 3 objects>
Note
The role values here must be the full role names (“block directives”), described as the “directives” in the Sphinx documentation for domains, and not the abbreviated forms (“inline directives”) used when constructing cross-references.
Thus, for example, a
DataObjStr
corresponding to a method on a class should be constructed with role=’method’, not role=’meth’.
Export the
Inventory
in compressed form.Generate the text of the inventory file with
data_file()
, optionally contracting theuri
anddispname
fields:>>> text = inv.data_file(contract=True)
Compress the file text:
>>> ztext = soi.compress(text)
Save to disk:
>>> soi.writebytes('objects_foobar.inv', ztext)
Transfer the compressed file to its distribution location.
- If only local access is needed, it can be kept local.
- If external access needed, upload to a suitable host.
Add an element to the
intersphinx_mapping
parameter inconf.py
.The key of the element is an arbitrary name, which can be used to specify the desired documentation set to be searched for the target object, in the event of a name collision between one or more documentation projects; e.g.:
:meth:`python:str.join`
The value of the element is a
tuple
of length two:- The first element of the value tuple is the head URI for the
documentation repository,
identified in step (1),
to which the
uri
of given object is appended when constructing anintersphinx
cross-reference. - The second element of the value tuple can be
None
, in which case the objects.inv file is assumed to be at the repository head URI. Otherwise, this element is the complete address of the distribution location of the compressed inventory file, from step (4), whether a local path or a remote URL.
- The first element of the value tuple is the head URI for the
documentation repository,
identified in step (1),
to which the
Examples:
intersphinx_mapping = { # Standard reference to web docs, with web objects.inv 'python': ('https://docs.python.org/3.5', None), # Django puts its objects.inv file in a non-standard location 'django': ('http://docs.djangoproject.com/en/dev/', 'https://docs.djangoproject.com/en/dev/_objects/'), # Drawing the Sphinx objects.inv from a local copy, but referring to the 1.7 web docs 'sphinx': ('http://www.sphinx-doc.org/en/1.7/', '/path/to/local/objects.inv', }