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
