Excellent template but how do I generate the docs to my C library within the repository so that I can know how it would look like.

[jymchng]

As titled and thank you for doing this.

[friendlyanon]

The situation in general around documentation is not quite satisfying to me. See these issues: https://github.com/friendlyanon/cmake-init/issues?q=is%3Aissue+is%3Aopen+label%3Adocs

[jymchng]

I also agree that the docs.cmake and docs-ci.cmake are quite fragile.

For example, I use cmake-format to format my .cmake files and I like to UPPERCASE all my commands.

Hence, this code snippet will fail:

# ---- Process project() call in CMakeLists.txt ----

FILE(READ "${src}/CMakeLists.txt" content)
MESSAGE(STATUS "[INFO] `\${src}/CMakeLists.txt` = ${src}/CMakeLists.txt")

STRING(FIND "${content}" "project(" index)
IF(index EQUAL "-1")
    MESSAGE(FATAL_ERROR "Could not find \"project(\"")
ENDIF()
STRING(SUBSTRING "${content}" "${index}" -1 content)

STRING(FIND "${content}" "\n)\n" index)
IF(index EQUAL "-1")
    MESSAGE(FATAL_ERROR "Could not find \"\\n)\\n\"")
ENDIF()
STRING(SUBSTRING "${content}" 0 "${index}" content)

Since in my ${src}/CMakeLists.txt, my PROJECT(...) would be capitalized`.

[jymchng]

Or maybe you can add in a comment like so:

# ---- Process project() call in CMakeLists.txt ----
# The aim is to obtain the entire 
# ```
# project (
    # PROJECT_NAME
    # ...
    # ...
# )
# ```
# call out from your `${src}/CMakeLists.txt` file

So that users can edit the codes in docs-ci.json accordingly to fit how the project(...) call looks like.

[friendlyanon]

I like to UPPERCASE all my commands

Please don't do that. Use commands as they are documented. This also makes grepping for them difficult. In that case, the docs scripts breaking are absolutely a positive thing.

[jymchng]

@friendlyanon Is it a standard practice to leave the functions / calls as case insensitive?

I will heed your advice since I am only 1 week old into Cmake.

By the way, is it also standard practice to use the top level makefile as a command runner?

Thank you.

[friendlyanon]

Is it a standard practice to leave the functions / calls as case insensitive?

I'm unsure what this means. If the documentation of if() references it as if(), then use it as if(). Same goes for commands like FetchContent_MakeAvailable().

is it also standard practice to use the top level makefile as a command runner?

Not sure what this means either. The root level CMakeLists.txt is the entrypoint into your build. It's by convention in the root directory for ease of use and exposure.