How to combine `CMinx` and `CMakeTest` ?

[dschiller]

Functionality

Actually I need to workaround like:

#[[[
Testing `buildserver_helper.cmake`
#]]
function(test_buildserver_helper)
endfunction()
ct_add_test(NAME test_buildserver_helper)
function(${test_buildserver_helper})
   ...
endfunction()

Otherwise I get errors like:

Writing RST files to /Users/dirk.schiller/Work/Coding/CPP/tests/docs/docs
ANTLR runtime and generated code versions disagree: 4.8!=4.7.2
ANTLR runtime and generated code versions disagree: 4.8!=4.7.2
Traceback (most recent call last):
  File "main.py", line 13, in <module>
  File "cminx/__init__.py", line 57, in main
  File "cminx/__init__.py", line 93, in document
  File "cminx/__init__.py", line 122, in document_single_file
  File "cminx/documenter.py", line 58, in __init__
  File "antlr4/tree/Tree.py", line 151, in walk
  File "antlr4/tree/Tree.py", line 149, in walk
  File "antlr4/tree/Tree.py", line 163, in enterRule
  File "cminx/parser/CMakeParser.py", line 264, in enterRule
  File "cminx/parser/aggregator.py", line 119, in enterDocumented_command
NotImplementedError: Documentation cannot be generated for:
#[[[
Testing `buildserver_helper.cmake`
#]]
ct_add_test(NAMEtest_buildserver_helper)
[68529] Failed to execute script main

With this:

#[[[
Testing `buildserver_helper.cmake`
#]]
ct_add_test(NAME test_buildserver_helper)
function(${test_buildserver_helper})
   ...
endfunction()

Indenting

Seems there is also an indenting issue:

#[[[
# Testing `buildserver_helper.cmake`
#]]
function(test_buildserver_helper)
endfunction()
ct_add_test(NAME test_buildserver_helper)
function(${test_buildserver_helper})

    #[[[
    # Verify that the global option `BUILDSERVER` defaults to `OFF`  # <<< The first `#` will be displayed
    #]]                                                                    in the created html
    function(test_option_BUILDSERVER_is_OFF)
    endfunction()
    ct_add_section(NAME test_option_BUILDSERVER_is_OFF)
    function(${test_option_BUILDSERVER_is_OFF})
        ct_assert_equal(BUILDSERVER OFF)
    endfunction()

endfunction()

[ryanmrichard]

For the functionality issue, CMinx assumes you are documenting the code which immediately follows the comment. In your case you have a line of code between the two. I think in this scenario, the user needs to tell us what function they're actually documenting (I feel like it's a slippery slope if we assume it's the next function/macro as they may think they're documenting ct_add_test or something). I would do this using standard reST:

#[[[
.. function:: buildserver_helper

   Testing `buildserver_helper.cmake`
#]]
ct_add_test(NAME test_buildserver_helper)
function(${test_buildserver_helper})

This is what CMinx automatically generates anyways. I'm not sure if that requires any modifications to CMinx; maybe to register that there is documentation for the function?

For the indenting issue, If I'm understanding you correctly the HTML has a line like:

Verify that the global option `BUILDSERVER` defaults to `OFF`  #

and you want it to be:

Verify that the global option `BUILDSERVER` defaults to `OFF`

(no # sign at the end). If it's not the case already we could define, CMinx options like "line_start" and "line_end" (would need better names than that) which respectively define optional strings that should be stripped off of the beginning and end of a doc-comment line; optional, in this case meaning that if the strings doesn't appear, the line should just be processed as normal. I'd default both of them to #.

[dschiller]

The line is - forget the right # - it was only for documenting:

   # Verify that the global option `BUILDSERVER` defaults to `OFF`

If the line is without indent like:

# This is a comment

Then it works like expected.

If it is like:

   # This is a comment

Then the left # will be printed in the resulting html document

[AutonomicPerfectionist]

I've added support for documenting CMakeTest test and section definitions in #35.

As for indenting, I had assumed the same as Ryan, now that I understand what you mean that has also been fixed in #35

[dschiller]

Both works. Thanks a lot!