Decode Sphinx crossreferencing inventories 'objects.inv'

This page

What is this about?

Most Sphinx documentation projects offer an inventory of link targets in a file named objects.inv. It is usually locate in the root folder and can be downloaded via https://www.project-domain.tld/objects.inv. TYPO3 CMS Core ChangeLog documentation has such an inventory: https://docs.typo3.org/c/typo3/cms-core/master/en-us/objects.inv The purpose of such an inventory is to allow symbolic linking from another Sphinx project. Note that the target documentation has no idea about who in the world is linking to it. The Sphinx "Intersphinx" mechanism provides that possibility. To use that in an arbitrary Sphinx project you define an "intersphinx mapping", which could be t3changelog = https://docs.typo3.org/c/typo3/cms-core/master/en-us/ in this case. Afterwards you can pick one of the target labels and link to that spot in the changelog manual without caring about URLs. And, if the authors of the changelog decide to move things around your link will still be valid once your manual received a new rendering". A link to a target would be written as:

:ref:`t3changelog:THE-LABEL`

The amazing thing is, that the link text, that is shown, automatically will be that of the headline in the destination manual.

How to decode objects.inv?

This is Sphinx know-how to decode and read that file. So let's directly use Sphinx for that purpose. Read about this in the Sphinx docs: Showing all links of an Intersphinx mapping file

Here is a sample command that does the trick:

OBJECTS_INV_URL=https://docs.typo3.org/c/typo3/cms-core/master/en-us/objects.inv
docker run --rm -t --entrypoint /bin/bash \
   t3docs/render-documentation \
   -c "source /ALL/userhome/.bashrc;python -m sphinx.ext.intersphinx $OBJECTS_INV_URL"

# Result is a long list in text format shown in the terminal.

What's going on here? Explanation:

docker run t3docs/render-documentation

We are running our Docker container.

--rm

We want to have that container removed right after finishing.

-t

Connect the output to our tty (terminal).

--entrypoint /bin/bash

We specify the bash as shell. Don't put the command to execute here!

-c

For the bash we specify that the following is a command to be executed.

source /ALL/userhome/.bashrc

Inside the container /ALL/venv is our current folder. A Python virtual environment is prepared in the container, but it isn't activated. source /ALL/userhome/.bashrc activates that environment.

;

Join two commands.

python -m sphinx.ext.intersphinx

Have Python run the intersphinx module as a "__main__" program. In that case the module provides code that does a very simple dump of an link inventory. Not sophisticated, but works.

https://docs.typo3.org/c/typo3/cms-core/master/en-us/objects.inv

This is the inventory we want to have downloaded and queried. In TYPO3 we are following the usual convention that it's named objects.inv and is located in the root path of a manual.

About inventories

Watch out: There are at least two lists of labels. One is for :doc:… linking and one is for :ref:… linking.

Example: Looking for '75625'

Q: How do I know whether there is a label containing '75625' in the core changelog?

A: The docker container can answer that:

docker run --rm -t --entrypoint /bin/bash \
   t3docs/render-documentation \
   -c "source /ALL/userhome/.bashrc;python -m sphinx.ext.intersphinx  \
   https://docs.typo3.org/c/typo3/cms-core/master/en-us/objects.inv"  \
   | grep 75625

Shows Changelog/8.1/Deprecation-75625-DeprecatedCacheClearingOptions Deprecation: #75625 - Deprecated cache clearing options: Changelog/8.1/Deprecation-75625-DeprecatedCacheClearingOptions.html

So the answer is: Changelog/8.1/Deprecation-75625-DeprecatedCacheClearingOptions

The following command finds this in one go. It finds the line, removes tabs and returns the first word (non-blank string):

docker run --rm -t --entrypoint /bin/bash \
   t3docs/render-documentation \
   -c "source /ALL/userhome/.bashrc;python -m sphinx.ext.intersphinx  \
   https://docs.typo3.org/c/typo3/cms-core/master/en-us/objects.inv"  \
   | grep 75625 | sed 's/\t//' | grep -Eo "^[^ ]*"

# shows:
Changelog/8.1/Deprecation-75625-DeprecatedCacheClearingOptions

Now you can use this string for symbolic linking. The file is the target of the link:

:doc:`t3changelog:Changelog/8.1/Deprecation-75625-DeprecatedCacheClearingOptions`

This target key is made up of: ⓐ url-mapping-key ⓑ ':' ⓒ relative path ⓓ slug of the document title

The slug is [A-Za-z0-9-_] only. It is case sensitive but forgiving. That means, Sphinx is looking for an exact match and if there isn't on it looks again, this time case insensitive. The first title in a reST file is its document title, which is transformed into the slug (=key). The document title of the target page is used as link text in the created link:

../_images/decode-01.png