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.x; the prior instructions for v1.0 can be found here.

  1. Identify the head of the URI to the documentation.

  2. Construct an Inventory containing all of the objects of interest. The uri and dispname 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): <no project> <no version>, 0 objects>
      
    • Define the project and version attributes:

      >>> inv.project = 'foobar'
      >>> inv.version = '1.5'
      >>> print(inv)
      <Inventory (manual): foobar v1.5, 0 objects>
      
    • Append new DataObjStr instances to objects 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’.

  3. Export the Inventory in compressed form.

    • Generate the text of the inventory file with data_file(), optionally contracting the uri and dispname fields:

      >>> text = inv.data_file(contract=True)
      
    • Compress the file text:

      >>> ztext = soi.compress(text)
      
    • Save to disk:

      >>> soi.writebytes('objects_foobar.inv', ztext)
      
  4. 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.

  5. Add an element to the intersphinx_mapping parameter in conf.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 an intersphinx 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.

    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': ('https://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 current web docs
        'sphinx': ('https://www.sphinx-doc.org/en/master/', '/path/to/local/objects.inv'),
    }