[cmake-developers] Properly Documenting a CMake Module

[Timothy Wrona]

Okay so I dug a little deeper into this and it definitely looks like sphinx
is the correct tool to use, but I still have one problem.

I would like sphinx to be able to extract ".rst" formatted comments
directly out of my cmake source files to produce the documentation but I
can't seem to figure out how.

The standard modules that ship with cmake all have this ".rst" section at
the top that seems to magically get extracted and turned into online
documentation with sphinx, but I just can't figure out how they do it.

Is there a simple way to use sphinx to extract these comments without
writing my own tool to do it? I mean it wouldn't be hard to script, but if
there is a standard way I would prefer to use what everyone else uses
rather than reinvent the wheel.

Thanks,
Tim

On Wed, Feb 13, 2019, 8:59 AM Timothy Wrona <tjwrona1992 at gmail.com wrote:

> I am going to quote your response in an answer on my stack overflow
> question so others may find this information too.
>
> On Wed, Feb 13, 2019 at 8:57 AM Timothy Wrona <tjwrona1992 at gmail.com>
> wrote:
>
>> Thanks for the info and the links! I will start looking into it. :)
>>
>> On Wed, Feb 13, 2019 at 7:50 AM Torsten Robitzki <Torsten at robitzki.de>
>> wrote:
>>
>>>
>>>
>>> > Am 13.02.2019 um 13:42 schrieb Brad King via cmake-developers <
>>> cmake-developers at cmake.org>:
>>> >
>>> > The online docs, like those at https://cmake.org/cmake/help/v3.14
>>> > do publish a `/objects.inv` to support intersphinx:
>>> >
>>> >  http://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
>>> >
>>> > This was done on request of some users so I haven't looked into how
>>> > that works, but one should be able to use sphinx to generate one's
>>> > own documentation and still cross-reference CMake’s online docs.
>>>
>>> I can confirm that this works as expected. Used it by myself.
>>>
>>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://cmake.org/pipermail/cmake-developers/attachments/20190213/db14f768/attachment.html>