On 2014-01-08 15:35, Brad King wrote:
On 01/08/2014 01:52 PM, Matthew Woehlke wrote:
On 2013-12-19 11:21, Brad King wrote:
Sphinx does not support magic cross-referencing to external documents.
If that's really true, that's a pretty big drawback of docutils vs. e.g.
doxygen, which has very good support for external references.
I can't say for sure it is not possible. Perhaps there is a way to
export Sphinx Domain objects for reference by external documents
whose build configuration references a specific publication URL of
the upstream objects, but I'm not familiar with it.
Neither am I :-), but I would be surprised if there isn't some
implementation somewhere. I will try to look into this some time and
will get back to you if I find anything.
This places a significant maintenance burden on projects and leads to
their being umpteen copies of the CMake reST additions.
Ideally someone would create a dedicated CMake reST documentation
project like the CMakeDocUtils package in your example.
I debated whether or not to suggest that in the previous mail due to not
knowing how it would work out with the CMake project itself. But...
CMake's copy could be a downstream client just like any other project
that wants to document CMake domain objects.
...since it seems that CMake would be amenable to using this, then I
agree, this is probably the best solution.
I think we are on the same page now; thanks for a productive discussion!
With this approach projects could provide documented modules even if
they do not build with CMake (e.g. Qt5).
That's a good point :-).
Do you really anticipate that the syntax for declaring documentation is
going to change?
Yes. The new documentation system is very young and will likely
change as it matures.
To be clear, I meant *only* the '#.rst' syntax (i.e. the code to extract
the reST markup from a CMake module). I would not expect *that* to
change again?
Stuff within the reST domain, sure, I can see that changing.
--
Matthew
--
Powered by www.kitware.com
Visit other Kitware open-source projects at
http://www.kitware.com/opensource/opensource.html
Please keep messages on-topic and check the CMake FAQ at:
http://www.cmake.org/Wiki/CMake_FAQ
Follow this link to subscribe/unsubscribe:
http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
