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/
>From 2f06136d7b18f14899b8bb7238837d877f1e2328 Mon Sep 17 00:00:00 2001
From: "Daniele E. Domenichelli" <daniele.domeniche...@iit.it>
Date: Wed, 18 Jun 2014 11:57:47 +0200
Subject: [PATCH] Utilities/Sphinx: Fix issues with intersphinx
targetid is now just the name, therefore a module can now be linked
by another project using intersphinx in this way:
:cmake:module:`ModuleName`
---
Utilities/Sphinx/cmake.py | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/Utilities/Sphinx/cmake.py b/Utilities/Sphinx/cmake.py
index 0e8f280..6ef55ad 100644
--- a/Utilities/Sphinx/cmake.py
+++ b/Utilities/Sphinx/cmake.py
@@ -182,7 +182,7 @@ class CMakeTransform(Transform):
if make_index_entry:
title = self.parse_title(env.docname)
# Insert the object link target.
- targetid = '%s:%s' % (objtype, title)
+ targetid = '%s' % title
targetnode = nodes.target('', '', ids=[targetid])
self.document.insert(0, targetnode)
# Insert the object index entry.
@@ -200,7 +200,7 @@ class CMakeObject(ObjectDescription):
return sig
def add_target_and_index(self, name, sig, signode):
- targetid = '%s:%s' % (self.objtype, name)
+ targetid = '%s' % name
if targetid not in self.state.document.ids:
signode['names'].append(targetid)
signode['ids'].append(targetid)
@@ -299,7 +299,7 @@ class CMakeDomain(Domain):
def resolve_xref(self, env, fromdocname, builder,
typ, target, node, contnode):
- targetid = '%s:%s' % (typ, target)
+ targetid = '%s' % target
obj = self.data['objects'].get(targetid)
if obj is None:
# TODO: warn somehow?
--
2.0.0
--
Powered by www.kitware.com
Please keep messages on-topic and check the CMake FAQ at:
http://www.cmake.org/Wiki/CMake_FAQ
Kitware offers various services to support the CMake community. For more
information on each offering, please visit:
CMake Support: http://cmake.org/cmake/help/support.html
CMake Consulting: http://cmake.org/cmake/help/consulting.html
CMake Training Courses: http://cmake.org/cmake/help/training.html
Visit other Kitware open-source projects at
http://www.kitware.com/opensource/opensource.html
Follow this link to subscribe/unsubscribe:
http://public.kitware.com/mailman/listinfo/cmake-developers
