[cmake-developers] Sphinx documentation and intersphinx
Daniele E. Domenichelli
daniele.domenichelli at gmail.com
Wed Jun 18 11:03:31 EDT 2014
Hello all,
I am trying to use sphinx intersphinx extension[1] to generate links to
CMake documentation, but I found a couple of issues:
1) The "objects.inv" file cannot be downloaded from CMake
documentation[2], therefore I have to generate it and include it in my
project. Is it possible to make it available?
2) I was trying to use it in the same way that it is used in cmake, i.e.
(1) :cmake:module:`ModuleName`
but unfortunately, in order to generate the links, I have to do
something like
(2) :cmake:module:`module:ModuleName`
and also the link label becomes "module:ModuleName" (I was expecting
"ModuleName" only, as in CMake documentation).
So one option is to set the label for the link, for example
(3) :cmake:module:`ModuleName <module:ModuleName>`
works and is displayed as I would expect. Nontheless I find this
redundant and not really intuitive, so I investigated some more...
This seems to be caused by the targetid in cmake.py that is always
generated as
targetid = '%s:%s' % (type, name)
By changing it to be just the name, and regenerating the documentation
and including the new "objects.inv" I was able to obtain the behaviour
that I was expecting when using (1), but unfortunately I get some
warnings for conflicts with some properties when building the CMake
documentation, and even though the generated documentation seems to be
unaffected, there are issues with the _external_ documentation. For
example only one of those will be correctly linked, and the other one
won't be a link:
:cmake:prop_tgt:`COMPILE_FLAGS`
:cmake:prop_sf:`COMPILE_FLAGS`
But both of these currently work:
:cmake:prop_tgt:`COMPILE_FLAGS <prop_tgt:COMPILE_FLAGS>`
:cmake:prop_sf:`COMPILE_FLAGS <prop_sf:COMPILE_FLAGS>`
Attached you can find a small patch that I used for testing this.
What is your opinion? How should I use it? Should I just use the long
version?
Cheers,
Daniele
[1]http://sphinx-doc.org/latest/ext/intersphinx.html
[2]http://cmake.org/cmake/help/v3.0/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0001-Utilities-Sphinx-Fix-issues-with-intersphinx.patch
Type: text/x-patch
Size: 1784 bytes
Desc: not available
URL: <http://public.kitware.com/pipermail/cmake-developers/attachments/20140618/25aa0702/attachment.bin>
More information about the cmake-developers
mailing list