# How does cmake-docs use Sphinx to parse comments in CMake files?
**URL:** https://discourse.cmake.org/t/how-does-cmake-docs-use-sphinx-to-parse-comments-in-cmake-files/8593
**Category:** Development
**Created:** [July 25, 2023, 4:33am UTC](https://discourse.cmake.org/t/how-does-cmake-docs-use-sphinx-to-parse-comments-in-cmake-files/8593 "2023-07-25T04:33:08Z")
**Posts on this page:** 6
**Page:** 1
### Author:  [@hwhsu1231](https://discourse.cmake.org/u/hwhsu1231)
#### Post date: [July 25, 2023, 4:33am UTC](https://discourse.cmake.org/t/how-does-cmake-docs-use-sphinx-to-parse-comments-in-cmake-files/8593/1 "2023-07-25T04:33:09Z")
Excuse me, CMake Team.
I’ve noticed before that many CMake files in Kitware/CMake have comments in the following format in their headers (ex. [FindPython.cmake](https://github.com/Kitware/CMake/blob/master/Modules/FindPython.cmake)):
```cmake
#[====================[.rst:
#]====================]
```
And these comments eventually end up in the CMake Documentation (ex. [FindPython](https://cmake.org/cmake/help/latest/module/FindPython.html)). This is similar to how Doxygen parses C/C++ comments. Since I didn’t see that [Sphinx Documentation](https://www.sphinx-doc.org/en/master/) has built-in support for this kind of parsing, I’m guessing that CMake has implemented its own mechanism to parse these types of comments? If so, how?
---
### Author:  [@brad.king](https://discourse.cmake.org/u/brad.king)
#### Post date: [July 25, 2023, 4:04pm UTC](https://discourse.cmake.org/t/how-does-cmake-docs-use-sphinx-to-parse-comments-in-cmake-files/8593/2 "2023-07-25T16:04:38Z")
We implement a Sphinx extension module that adds a [`cmake-module`](https://gitlab.kitware.com/cmake/cmake/-/blob/v3.27.0/Utilities/Sphinx/cmake.py#L744) directive. The directive is [used](https://gitlab.kitware.com/cmake/cmake/-/blob/v3.27.0/Help/module/GNUInstallDirs.rst?plain=1) by each `Help/module/*.rst` file to parse documentation blocks out of a `.cmake` file.
---
### Author:  [@vardarirrgan1](https://discourse.cmake.org/u/vardarirrgan1)
#### Post date: [January 12, 2024, 8:42pm UTC](https://discourse.cmake.org/t/how-does-cmake-docs-use-sphinx-to-parse-comments-in-cmake-files/8593/3 "2024-01-12T20:42:42Z")
That’s a pretty handy Sphinx extension. Should admirers just borrow the script in accordance with its `BSD 3-Clause License`, or is it available in some packaged form (with associated package update semantics)?
---
### Author:  [@jtxa](https://discourse.cmake.org/u/jtxa)
#### Post date: [January 13, 2024, 2:57am UTC](https://discourse.cmake.org/t/how-does-cmake-docs-use-sphinx-to-parse-comments-in-cmake-files/8593/4 "2024-01-13T02:57:15Z")
A ready-to-use pip extension was created here:
[https://github.com/scikit-build/moderncmakedomain](https://github.com/scikit-build/moderncmakedomain)
---
### Author:  [@Ryanf55](https://discourse.cmake.org/u/Ryanf55)
#### Post date: [January 21, 2024, 7:52pm UTC](https://discourse.cmake.org/t/how-does-cmake-docs-use-sphinx-to-parse-comments-in-cmake-files/8593/5 "2024-01-21T19:52:00Z")
Do the sphinx comments have any relation to the docs used here?
>
I’ve seen this used many places. Perhaps it’s the legacy format?
>
---
### Author:  [@hwhsu1231](https://discourse.cmake.org/u/hwhsu1231)
#### Post date: [January 24, 2024, 8:03am UTC](https://discourse.cmake.org/t/how-does-cmake-docs-use-sphinx-to-parse-comments-in-cmake-files/8593/6 "2024-01-24T08:03:31Z")
About the code snippets @Ryanf55 mentioned in [ament\_package.cmake](https://github.com/ament/ament_cmake/blob/a6a7e0c775545e6f13d767b6012b72ec358248c6/ament_cmake_core/cmake/core/ament_package.cmake#L16-L45), I haven’t found a clue, but I guess maybe it is related to this project, [CMakePP/CMinx](https://github.com/CMakePP/CMinx).
Comparing the syntax that CMakePP/CMinx uses, they look so similar:
- [Documenting a Module — CMinx v1.1.9 documentation](https://cmakepp.github.io/CMinx/documenting/module.html)
- [Documenting a Function — CMinx v1.1.9 documentation](https://cmakepp.github.io/CMinx/documenting/function.html)
- [Documenting a Macro — CMinx v1.1.9 documentation](https://cmakepp.github.io/CMinx/documenting/macro.html)
- [Documenting a Variable — CMinx v1.1.9 documentation](https://cmakepp.github.io/CMinx/documenting/variable.html)
A simple example taken from CMinx Documentation:
```cmake
#[[[
# This function has very basic documentation.
#
# This function's description stays close to idealized formatting and does not
# do anything fancy.
#
# :param person: The person this function says hi to
# :type person: string
#]]
function(say_hi_to person)
message("Hi ${person}")
endfunction()
```