On 2013-12-19 11:21, Brad King wrote:
On 12/18/2013 12:13 PM, Matthew Woehlke wrote:
Does this mean one cannot e.g. use the CMake extensions and/or link to
topics in CMake's documentation (provided a known location of the same)?
Correct. Sphinx does not support magic cross-referencing to external
documents. Generating such links would require folding the document
into the build process of CMake itself. Without that the links have
to be spelled out like any other external hyperlinks (http://...).
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.
Considering that docutils is supposed to be the de-facto standard for
documenting Python, which has all sorts of external modules, I'd be
surprised if there isn't a solution to this problem already existing.
Even if not, from what I know of reST, it wouldn't be all that difficult
to create one. (At worst, you'd need to introduce a new interpreted text
role for external links, but that's not exactly the end of the world.
And if you reuse doxygen's tagfile format, suddenly you can link to
doxygen-generated C++ doxygen from reST :-). Again, assuming that hasn't
already been done...)
So a file that comes in a project needs to be documented with the
documentation of the project. Every project has that problem with
all its file types.
Sure. I just feel like this should be solvable like:
find_package(CMakeDocUtils)
include(${CMakeDocUtilsUseFile})
cmake_generate_documentation(...)
...where ideally CMakeDocUtils is provided by CMake itself (albeit free
to rely on being able to find other external tools, e.g. Python).
Other projects will have to do their own thing.
If they want to copy and re-use the infrastructure out of the
CMake source tree they are free to do so but will have to maintain
it themselves.
This places a significant maintenance burden on projects and leads to
their being umpteen copies of the CMake reST additions. For small
projects, this could even end up being more "code" that the project
itself! I fail to see how this is in any way other than a Bad Thing.
Another approach is to use sed+rst2html to extract
and process .rst markup from inside .cmake file comments.
Do you really anticipate that the syntax for declaring documentation is
going to change? I would think that, at the very least, something to
extract the reST text from a CMake module should be provided by CMake.
(Again, I'll assert that such utility does NOT need to be self-contained
and is free to depend on e.g. Python being available.)
From the perspective as a user wanting to do this, the question is if I
spend a *lot* of effort reinventing the wheel in my own project, which
may initially get the job done but incurs an ongoing maintenance burden
(and/or rapidly bitrots), or do I spend that effort taking CMake's
existing documentation support and making it available to external
users, so that it benefits *everyone* and distributes the maintenance
burden?
Hopefully that helps to understand my perspective.
Thanks,
--
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
