moderncmakedomain icon indicating copy to clipboard operation
moderncmakedomain copied to clipboard

Extend CMakeModule to parse markdown

Open LecrisUT opened this issue 11 months ago • 0 comments

According to the discussion in https://gitlab.kitware.com/cmake/cmake/-/issues/24934#note_1367903, I am not sure if the intent is to migrate cmake upstream to import this module, so probably I will open an equivalent MR there. But for now I need some help with designing this:

  • [x] Parse #[===[.md: as a valid module directive
  • [x] Render parsed markdown. (I think this works in the initial commit, but it should handle titles properly). Maybe this also requires to switch between a rst and myst renderer accordingly. Didn't see an example that selects appropriate renderers
  • [ ] ~~Render only top-most documentation as the module documentation. Other internal sections, e.g. for function() should be separate. Maybe they should be in node.children? This is to make it more like python docs format or doxygen~~. This would rather need a re-design to use auto-api similar to matlab/python.

The goal is to be able to render a file like this: my_module.cmake

#[===[.md
# my_module

Some documentation about module
]==]

some_module_content()

function(module_function arg1)
    #[===[.md
    # module_function

    Summary of module_function

    ## Synopsis
    ...
    ]===]
    ...
endfunction()

Currently it doesn't handle nested documentations, i.e. they are all merged together. Example

LecrisUT avatar Jul 11 '23 15:07 LecrisUT