Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Extend CMakeModule to parse markdown #35

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

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