Re: [cmake-developers] Properly Documenting a CMake Module
That's what I was looking for! Thanks!!! On Thu, Feb 14, 2019 at 9:04 AM wrote: > > > > Am 14.02.2019 um 14:53 schrieb Timothy Wrona : > > > > How does Sphinx know to go parse that ".cmake" file? Does Sphinx > recognize the „cmake-module" keyword in a special way and know what to do > with it? > > it’s from a Sphinx module that you can find the in the CMake sources > Utilities/Sphinx/cmake.py. Or you can install this file using pip: > > > pip install sphinxcontrib-moderncmakedomain > > When configuring Sphinx, you have to name the extensions to use in > Sphinx's configuration file (conf.py) and add the name of the extension > (sphinxcontrib.moderncmakedomain) to the extensions array. > > best regards, > > Torsten > -- 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: https://cmake.org/mailman/listinfo/cmake-developers
Re: [cmake-developers] Properly Documenting a CMake Module
> Am 14.02.2019 um 14:53 schrieb Timothy Wrona : > > How does Sphinx know to go parse that ".cmake" file? Does Sphinx recognize > the „cmake-module" keyword in a special way and know what to do with it? it’s from a Sphinx module that you can find the in the CMake sources Utilities/Sphinx/cmake.py. Or you can install this file using pip: > pip install sphinxcontrib-moderncmakedomain When configuring Sphinx, you have to name the extensions to use in Sphinx's configuration file (conf.py) and add the name of the extension (sphinxcontrib.moderncmakedomain) to the extensions array. best regards, Torsten signature.asc Description: Message signed with OpenPGP -- 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: https://cmake.org/mailman/listinfo/cmake-developers
Re: [cmake-developers] Properly Documenting a CMake Module
Hi Gregor, It looks like there's still a little bit of magic here. All those "Help/.rst" files just have a single line in them that says: .. cmake-module:: ../../Modules/.cmake How does Sphinx know to go parse that ".cmake" file? Does Sphinx recognize the "cmake-module" keyword in a special way and know what to do with it? Thanks, Tim -- 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: https://cmake.org/mailman/listinfo/cmake-developers
Re: [cmake-developers] Properly Documenting a CMake Module
Hello, On 14.02.19 04:39, Timothy Wrona wrote: 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. The standard modules have a shadow hierarchy at Help/module. For example https://gitlab.kitware.com/cmake/cmake/blob/master/Help/module/GNUInstallDirs.rst contains .. cmake-module:: ../../Modules/GNUInstallDirs.cmake There's no magic happening. Thanks, Gregor -- 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: https://cmake.org/mailman/listinfo/cmake-developers
Re: [cmake-developers] Properly Documenting a CMake Module
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 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 > 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 >> wrote: >> >>> >>> >>> > Am 13.02.2019 um 13:42 schrieb Brad King via cmake-developers < >>> cmake-developers@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. >>> >> -- 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: https://cmake.org/mailman/listinfo/cmake-developers
Re: [cmake-developers] Properly Documenting a CMake Module
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 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 > wrote: > >> >> >> > Am 13.02.2019 um 13:42 schrieb Brad King via cmake-developers < >> cmake-developers@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. >> > -- 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: https://cmake.org/mailman/listinfo/cmake-developers
Re: [cmake-developers] Properly Documenting a CMake Module
Thanks for the info and the links! I will start looking into it. :) On Wed, Feb 13, 2019 at 7:50 AM Torsten Robitzki wrote: > > > > Am 13.02.2019 um 13:42 schrieb Brad King via cmake-developers < > cmake-developers@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. > -- 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: https://cmake.org/mailman/listinfo/cmake-developers
Re: [cmake-developers] Properly Documenting a CMake Module
> Am 13.02.2019 um 13:42 schrieb Brad King via cmake-developers > : > > 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. signature.asc Description: Message signed with OpenPGP -- 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: https://cmake.org/mailman/listinfo/cmake-developers
Re: [cmake-developers] Properly Documenting a CMake Module
On 2/12/19 6:37 PM, Timothy Wrona wrote: > a way to document custom CMake modules so that they work with the > "cmake --help-module " command There is no way to do this. The only reason --help-module exists at all is because prior to 3.0 the documentation was generated by the CMake binary itself, and people were used to the option being available. It is only for builtin modules and only available for legacy reasons, and may one day go away in favor of the man pages and html docs. 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. If you get that working we'd welcome a MR to add docs describing how, perhaps in https://gitlab.kitware.com/cmake/cmake/blob/master/Help/dev/documentation.rst -Brad -- 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: https://cmake.org/mailman/listinfo/cmake-developers
Re: [cmake-developers] Properly Documenting a CMake Module
Note: I have additionally posted this question to stack overflow so if you would like to answer there rather than email it may help a larger audience: https://stackoverflow.com/questions/54660549/what-is-the-proper-way-to-document-a-cmake-module On Tue, Feb 12, 2019 at 6:37 PM Timothy Wrona wrote: > A quick Google search (...actually many rather extensive Google searches) > have not been able to explain how to properly document a CMake module. > > What I'm looking for is a way to document custom CMake modules so that > they work with the "cmake --help-module " command. Is there > any standard way of doing this? Can anyone point me to some good examples? > The documentation process seems oddly not well documented. Haha. > > How are modules that work with "cmake --help-module" documented? > > Any help is appreciated. > > Thanks, > Tim > -- 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: https://cmake.org/mailman/listinfo/cmake-developers
[cmake-developers] Properly Documenting a CMake Module
A quick Google search (...actually many rather extensive Google searches) have not been able to explain how to properly document a CMake module. What I'm looking for is a way to document custom CMake modules so that they work with the "cmake --help-module " command. Is there any standard way of doing this? Can anyone point me to some good examples? The documentation process seems oddly not well documented. Haha. How are modules that work with "cmake --help-module" documented? Any help is appreciated. Thanks, Tim -- 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: https://cmake.org/mailman/listinfo/cmake-developers
