JakubAndrysek / MkDoxy

📖 Automatically generates API documentation for your project based on Doxygen comments and code snippets in your markdown files.
https://mkdoxy.kubaandrysek.cz/
MIT License
60 stars 16 forks source link

Code sections don't work #79

Closed Wumpf closed 3 months ago

Wumpf commented 7 months ago

Code tags as used here https://github.com/matusnovak/doxybook/blob/master/example/src/animal.h#L50 don't work properly right now, resulting in https://mkdoxy-demo.kubaandrysek.cz/animal/classexample_1_1Animal/#detailed-description

I tried using `` instead but to no avail, it keeps on interpreting the content as regular markdown (#include` becomes a caption etc)

JakubAndrysek commented 7 months ago

I quickly looked into the code but did not find how to fix it. In parent project everything works properly: Doxybook project - Github

r-braun commented 3 months ago

I looked through the code and I think I found the cause: Code blocks are converted to mardown by the MdCodeBlock class' render method in markdown.py. But this render method doesn't surround the output with ```. This is instead done "manually" a few jinja templates, for example in memDef.jinja2:

```{{node.code_language}}
{{node.codeblock}}
Later, in the same file the node's details are rendered (the `@details` block of a doxygen comment):
```jinja2
{% if node.has_details -%}
{{node.details}}
{%- endif -%}

The problem is, that node.detail may contain code blocks that aren't surrounded by ``` yet (since the intention is to add those in the tenplate), which results in code blocks not working in the details section.

I think a quick patch could be to simply add the ``` blocks in MdCodeBlock's render method and remove them from the jinja templates, but this would loose the code_language, meaning there would be no syntax hichlighting in code blocks.

A more thorough fix in addition to the above could be to pass the code_language down to the render method and add it there or maybe to write a jinja2 filter that adds the active code_language to plain ``` blocks and apply that filter to any sections that may contain code blocks.

r-braun commented 3 months ago

@JakubAndrysek Thank you for addressing my PR so quickly and fixing the linter errors (sorry about that, I'm so used to using ', I didn't even consider the rest of the code uses ")

JakubAndrysek commented 3 months ago

It is ok, new PR does not run automatically with GitHub tests that shows the linting message.

In the future, I would like to setup Git hook that will inform you about linting and results from tests before commit.

Thank you for your time. Jacob