Skip to content

Conversation

@LecrisUT
Copy link

@LecrisUT LecrisUT commented Jul 11, 2023

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:

  • Parse #[===[.md: as a valid module directive
  • 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 LecrisUT marked this pull request as ready for review January 2, 2024 20:33
@LecrisUT LecrisUT changed the title [WIP] Extend CMakeModule to parse markdown Extend CMakeModule to parse markdown Jan 2, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant