A Decoder for objects.inv¶

What’s it about?¶

This post is about a commandline tool that converts Sphinx inventories (objects.inv) into something human readable.

The Intersphinx mechanism uses an ‘objects.inv’ inventory which usually resides in the root folder of a documentation project. Unfortunately it’s not directly readable by humans.

New tool¶

I have created a decoder that creates readable output. It is a one file commandline utility: Download from here. It’s very new so maybe it needs a bit more of testing and elaboration.

Available on docs.typo3.org¶

Minimal help is displayed if parameters or options don’t fit:

Use option –help for more help:

-- info explains a bit more:

Usage on your machine¶

Of course you can run that script elsewhere as well. You may have to install Mako-templating. That should be an easy oneliner: (sudo) pip install mako.

Output Formats¶

Currently you can produce html, csv and json as output. I manually created some examples:

As infile I used the inventory of the TYPO3 CMS Sphinx extension.

And here are the output examples: html, json (shown as text), csv (shown as text).

Why?¶

It helps to find out what targets are available in foreign documentation projects.

Example usage in the TYPO3 domain¶

$ python decode_sphinx_inventory.py http://typo3.org/api/typo3cms/ -O targets_api62.html

:ref:`t3api:TYPO3\CMS\Install\Controller\Action\Ajax\CoreUpdateVerifyChecksum`

:ref:`t3api:typo3\cms\install\controller\action\ajax\coreupdateverifychecksum`

Excourse: How to generate the inventory¶

About generation of objects.inv for the TYPO3 API:

• https://git.typo3.org/Documentation/ApiTypo3Org.git/blob/HEAD:/Classes/Intersphinx.php
• used in phing: https://git.typo3.org/Documentation/ApiTypo3Org.git/blob/HEAD:/Phing/typo3cms-master.xml#l36

Xavier Perseguers says:

So you need to run doxygen with an xml output (as described) and then you have the PHP code for the objects.inv file.

Commands To Decode The TYPO3 API¶

New on Dec 17, 2015: Output format ‘ref’:

mkdir tempdir
cd tempdir

decode_sphinx_inventory.py http://api.typo3.org/typo3cms/current/html/ -f html -O objects.inv.current.html
decode_sphinx_inventory.py http://api.typo3.org/typo3cms/current/html/ -f json -O objects.inv.current.json
decode_sphinx_inventory.py http://api.typo3.org/typo3cms/current/html/ -f csv  -O objects.inv.current.csv
decode_sphinx_inventory.py http://api.typo3.org/typo3cms/current/html/ -f ref  -O objects.inv.current.rst

decode_sphinx_inventory.py http://api.typo3.org/typo3cms/62/html/ -f html -O objects.inv.62.html
decode_sphinx_inventory.py http://api.typo3.org/typo3cms/62/html/ -f json -O objects.inv.62.json
decode_sphinx_inventory.py http://api.typo3.org/typo3cms/62/html/ -f csv  -O objects.inv.62.csv
decode_sphinx_inventory.py http://api.typo3.org/typo3cms/62/html/ -f ref  -O objects.inv.62.rst

To filter a ‘ref’ file:

python decode_sphinx_inventory.py http://api.typo3.org/typo3cms/62/html/ -f ref  -O objects.inv.62.rst
cat objects.inv.62.rst | grep -i 'TYPO3\\\\CMS\\\\Core\\\\Resource\\\\'

Result:

:ref:`t3api62:TYPO3\\CMS\\Core\\Resource\\AbstractFile`
:ref:`t3api62:TYPO3\\CMS\\Core\\Resource\\AbstractFile::copyTo`
:ref:`t3api62:TYPO3\\CMS\\Core\\Resource\\AbstractFile::delete`

...

:ref:`t3api62:TYPO3\\CMS\\Core\\Resource\\StorageRepository::testCaseSensitivity`
:ref:`t3api62:TYPO3\\CMS\\Core\\Resource\\Utility\\BackendUtility`
:ref:`t3api62:TYPO3\\CMS\\Core\\Resource\\Utility\\ListUtility`