[CMake] Announcing CMake BASIS, a set of CMake based project interoperability and automation tools

[Andrew Hundt]

On Mon, Jan 27, 2014 at 3:30 PM, Matthew Woehlke <
mw_triad at users.sourceforge.net> wrote:
>
> Possibly :-). I'd tend to agree with Stephen that this isn't the best
> place to get into a discussion of git history rewriting. But I'll also drop
> https://help.github.com/articles/remove-sensitive-data as a possible
> place to start looking.


Thanks! I also agree.


>  So far, out of what you listed, the documentation related stuff is most
>>> interesting to me as an upstream trying to find upstreamable (or
>>> generally
>>> useful) stuff in BASIS, or trying to find the gaps in cmake which are
>>> suitable for closing in cmake itself.
>>>
>>
>>   Great, I too believe the basis_add_doc(), basis_add_doxygen_doc(), and
>> basis_add_sphinx_doc() functions and related files would be perfect
>> candidates to put in the "Modules" folder of CMake itself after whatever
>> other minor tweaks are necessary.
>>
>
> I didn't look at it yet, but to be "optimally" useful I would hope that an
> implementation of generating doxygen documentation would:
>

What we have won't be "optimally" useful, but it is "very" useful. I think
if it is integrated the additional steps to reach "optimal" usefulness
could be added over time.


>
> - allow the user to specify the doxyfile.in (probably as a well-known
> variable; most projects will want to set it once) in addition to having a
> default one
>

This is implemented. :-)


>
> - implement two-step generation of tag files followed by the actual
> documentation


> - allow the user to provide a list of library names to be used as input
> tag files (assuming those targets use the same mechanism to generate
> documentation)


> - implement the above in a manner that allows the user some mechanism to
> define 'custom' targets with their own tag file(s) for external
> documentation


> - allow for circular linking (this is why tags and doc need to be separate
> steps; the tags have no dependencies, but the docs depend on the referenced
> tags; splitting the two avoids creating dependency cycles)
>

These steps seem like a fairly complicated and specialized use case rather
than a typical one. Perhaps I am mistaken?


>
> In particular, I have a project where I want to be able to link to Qt
> documentation, but due to deficiencies in how Qt generates its tag file, I
> actually need to generate my own supplementary tag file. I want to be able
> to use this just by listing "Qt" as a documentation dependency.
>

The current version of the doxygen component wraps the support provided in
a normal doxyfile and also provides several filters which allow a few extra
languages to be documented, including the CMake language itself.

Here is the full documentation of the doxygen
component<http://opensource.andreasschuh.com/cmake-basis/apidoc/latest/DocTools_8cmake.html#a6a37a66eb28f7969ef27b004f8faaa3a>and
the sphinx
component<http://opensource.andreasschuh.com/cmake-basis/apidoc/latest/DocTools_8cmake.html#a628468ae6c7b29570a73a2d63eebf257>,
of course the documentation I link to was generated in doxygen using the
very tools we are discussing. :-)

Cheers!
Andrew Hundt
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.cmake.org/pipermail/cmake/attachments/20140128/7286d113/attachment-0001.html>