Jul 28, 2014 Tags: Sphinx, T3Docs

A Decoder for objects.inv

A new commandline tool to decode Sphinx inventories.

Updated on Dec 17, 2015

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

Note: A note for those TYPO3 insiders that have access to the docs server srv123: It’s installed there and can be run from the commandline.

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

RESOLVEME://files/001.png

Use option –help for more help:

RESOLVEME://files/002.png

-- info explains a bit more:

RESOLVEME://files/003.png

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

Thinking

Hhm, addressing specifically the TYPO3 community: Shouldn’t we place a human readable version next to our objects.inv files right away?

Excourse: How to generate the inventory

Updated on Mar 31, 2015

About generation of objects.inv for the TYPO3 API:

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`

Comments

comments powered by Disqus

Previous topic

Server to Server Copy using WGET with FTP

Next topic

Per Page Internationalization for ABlog

Tags

Archives

Languages

Recent Posts

This Page