DEPRECATION WARNING
This documentation is not using the current rendering mechanism and is probably outdated. The extension maintainer should switch to the new system. Details on how to use the rendering mechanism can be found here.
Advanced cross-links¶
Disclaimer
This is an advanced topic that you should skip unless you want to enable cross-link to virtually any website.
This section first describes the format of index file objects.inv
being used by Intersphinx and then shows how to
automatically generate such a file for a Doxygen-based API documentation.
Format of objects.inv
¶
An index file objects.inv
consists of two parts; one in plain text, at the beginning, followed by a ZLIB-compressed
list of references:
# Sphinx inventory version 2
# Project: My project
# Version: 1.0.0
# The remainder of this file is compressed using zlib.
... zlib-compressed content ...
The first line is checked by Intersphinx to ensure the file has correct format. We only describe version 2 of this index format.
The ZLIB-compressed list of reference has following structure:
<anchor name #1> std:label -1 <target url #1> <title of the anchor #1>
<anchor name #2> std:label -1 <target url #2> <title of the anchor #2>
<anchor name #3> std:label -1 <target url #3> <title of the anchor #3>
- <anchor name>
- Lower-case name of the anchor. You may use special characters such as "-" (dash), "_" (underscore) and "\" (backslash) to separate words.
- <target url>
Relative URL to the page, ended either by:
#
: to point to the top of the page (e.g.,admonitions.html#
)#$
: to point to the page and append<anchor name>
(as instructed by$
)#some-anchor
: to point to an arbitrary anchor in the target page (e.g.,admonitions.html#0145384da
)
- <title of the anchor>
Default title to be used when cross-link does not include an alternative title:
Automatic title: :ref:`prefix:my-anchor` Alternative title: :ref:`My alternative title <prefix:my-anchor>`
Warning
Make sure the last entry of the ZLIB-compressed content ends with a trailing linefeed as well.
Doxygen documentation¶
What is Doxygen?
Doxygen is the de facto standard tool for generating documentation from annotated C++ sources, but it also supports other popular programming languages such as C, Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and UNO/OpenOffice flavors), Fortran, VHDL, Tcl, and to some extent D.
—Dimitri van Heesch
The goal of cross-linking to Doxygen is to be able to write something like that in a developer document:
Please see class :ref:`t3cmsapi:TYPO3\\CMS\\Core\\Utility\\GeneralUtility`
for details.
When instantiating a class from a TYPO3 extension, you should not use PHP keyword
``new`` but call :ref:`t3cmsapi:TYPO3\\CMS\\Core\\Utility\\GeneralUtility::makeInstance`
instead.
Expected result is:
Please see class t3cmsapi:TYPO3\CMS\Core\Utility\GeneralUtility for details.
When instantiating a class from a TYPO3 extension, you should not use PHP keyword
new
but call t3cmsapi:TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance instead.
The problem with Doxygen is that it generates cryptic file names which are hard to link to manually. Fortunately we
found a way to prepare an index file objects.inv
by parsing the XML output of an API documentation.
You need both the HTML and the XML versions of the documentation. Getting XML output is just a matter of adding:
GENERATE_XML = YES
to your Doxygen configuration file. Then generate the API documentation as usual. You should end up with a html
and a xml
output directories (with default settings).
Then run following script:
#!/bin/bash
SOURCE_DIR=./xml
OUTPUT_DIR=./html
PROJECT="<name of the project>"
VERSION="<version>"
# BEWARE: Header is actually needed by Intersphinx!!! (1st line to be exact)
cat > $OUTPUT_DIR/objects.inv <<EOT
# Sphinx inventory version 2
# Project: $PROJECT
# Version: $VERSION
# The remainder of this file is compressed using zlib.
EOT
TMPFILE=`mktemp /tmp/sphinx-objects-inv.XXXXXX` || exit 1
# A few general anchors as specified by:
# - Intersphinx
cat >> $TMPFILE <<EOT
modindex std:label -1 annotated.html# Classes
genindex std:label -1 classes.html# Class Index
EOT
# - Doxygen
cat >> $TMPFILE <<EOT
namespaces std:label -1 namespaces.html# Namespaces
hierarchy std:label -1 hierarchy.html# Class Hierarchy
functions std:label -1 functions.html# Class Members
functions-func std:label -1 functions_func.html# Functions
variables std:label -1 functions_vars.html# Variables
deprecated std:label -1 deprecated.html# Deprecated List
todo std:label -1 todo.html# Todo List
test std:label -1 test.html# Test List
pages std:label -1 pages.html# Related Pages
examples std:label -1 examples.html# Examples
EOT
# - TYPO3 Documentation Team
cat >> $TMPFILE <<EOT
start std:label -1 index.html# $PROJECT
EOT
for XML in $(find $SOURCE_DIR -type f -name \*.xml | grep "/class_");
do
echo "Processing $XML"
FILE=$(cat $XML | xmlstarlet sel -t -v "//doxygen/compounddef/@id")
CLASS_INTERNAL_NAME=$(cat $XML \
| xmlstarlet sel -t -v "//doxygen/compounddef/compoundname")
CLASS_NAME="${CLASS_INTERNAL_NAME//::/\\}"
if [[ "$CLASS_NAME" == *\\* ]]; then
LABEL_CLASS_NAME="\\$CLASS_NAME"
else
LABEL_CLASS_NAME="$CLASS_NAME"
fi
# Pseudo anchor for the whole class
ANCHOR=$(echo "$CLASS_NAME" | tr '[A-Z]' '[a-z]')
echo "$ANCHOR std:label -1 $FILE.html# $LABEL_CLASS_NAME" >> $TMPFILE
for ID in $(cat $XML \
| xmlstarlet sel -t -v "//doxygen/compounddef//memberdef[@kind='function']/@id");
do
# Beware there's a "1" (for colon) at the beginning of the anchor
METHOD_ANCHOR=$(echo $ID | sed "s/^${FILE}_1//")
METHOD=$(cat $XML \
| xmlstarlet sel -t -v "//doxygen/compounddef//memberdef[@id='$ID']/name")
if [ -n "$METHOD" ]; then
# Pseudo anchor for the method
ANCHOR2=$(echo "$ANCHOR::$METHOD" | tr '[A-Z]' '[a-z]')
echo -n "$ANCHOR2 std:label -1 $FILE.html#$METHOD_ANCHOR " >> $TMPFILE
echo "$LABEL_CLASS_NAME::$METHOD()" >> $TMPFILE
fi
done
done
# Compress the index
php -r "echo gzcompress(file_get_contents('$TMPFILE'));" >> $OUTPUT_DIR/objects.inv
rm $TMPFILE
The index file objects.inv
will be stored along your HTML documentation. You should then deploy this HTML
directory to your website and cross-link to it as usual.