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. > 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. It would be maintained and distributed separately from the rest of CMake and make its own compatibility guarantees (perhaps even coming with Sphinx). CMake's copy could be a downstream client just like any other project that wants to document CMake domain objects. With this approach projects could provide documented modules even if they do not build with CMake (e.g. Qt5). > 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. -Brad -- 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
