[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