[CMake] Documenting CMakeLists.txt and custom or local .cmake files

[Philip Miller]

I was hoping to get a little guidance on my question of how to document my CMakeLists.txt and other .cmake files. Any suggestions of how, as a cmake user, one may take advantage of the sphinx documentation scheme that cmake uses for its documentation?

-----Original Message-----
From: CMake [mailto:cmake-bounces at cmake.org] On Behalf Of Philip Miller
Sent: Wednesday, April 06, 2016 10:52 PM
To: cmake at cmake.org
Subject: [CMake] Documenting CMakeLists.txt and custom or local .cmake files

Two days ago I posted this question on StackOverflow, http://stackoverflow.com/q/36415261/3154588. I have not gotten an answer there, so I thought I would ask on this list. 

What are good ways to document my project ``CMakeLists.txt`` files and local project ``.cmake`` files? There is a two year old question/answer http://stackoverflow.com/q/21628833/3154588 that I am essentially asking here again. The answer contains the statement 

> Currently, CMake 3.0 is under development which will get a new documentation system based on Sphinx and reStructuredText. I guess that this will bring new ways to document your modules.

I have looked at the [cmake developer documentation](https://cmake.org/cmake/help/v3.5/manual/cmake-developer.7.html?highlight=sphinx#id2), but this *new documentation system* seems geared towards the documentation of cmake itself. I do not see how I can use this to document my user-defined project ``CMakeLists.txt`` files or local ``.cmake`` files. 

I am hoping that since the cmake project internally has various sphinx directives and roles that there is was some way as a user I could take advantage of this internal usage of sphinx. I would like to be able to have some *markup* in my ``CMakeLists.txt`` files and local ``.cmake`` files without having to reinvent the wheel. There are related efforts in other projects. For example the ROS catkin project seems to offer the most complete approach that I have seen, but that is fairly heavyweight not easy to use for non-ROS projects. (As an example, look at their [extracted cmake api page](http://docs.ros.org/api/catkin/html/dev_guide/generated_cmake_api.html).) The simplest, is the [sphinx-contrib](https://bitbucket.org/birkenfeld/sphinx-contrib/) cmakedomain, but that relies on a separate rst source doc rather than an *autodoc* approach with markup comments. 

I appreciate any help.
Sincerely,
Phil
-- 

Powered by www.kitware.com

Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ

Kitware offers various services to support the CMake community. For more information on each offering, please visit:

CMake Support: http://cmake.org/cmake/help/support.html
CMake Consulting: http://cmake.org/cmake/help/consulting.html
CMake Training Courses: http://cmake.org/cmake/help/training.html

Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html

Follow this link to subscribe/unsubscribe:
http://public.kitware.com/mailman/listinfo/cmake