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

Fix tables markdown for classes in gendoc #137

Open
wants to merge 4 commits into
base: master
Choose a base branch
from

Conversation

fmeynadier
Copy link

@fmeynadier fmeynadier commented Jan 24, 2024

Hello,

Thanks for this useful tool. This pull request proposes an update of the markdown template for classes in gendoc, with which I had some issues.

The first commit is simply removing some leading spaces that caused pandoc (as well as the github markdown renderer) to consider the subsequent HTML-formatted table as a code block, hence escaping the html tags and special characters, and causing the actual html code to be displayed instead of a table when rendered as html.

Then I tried to switch to the usual way to encode tables in markdown, thus avoiding the HTML tags. I had to tweak the jinja tags to avoid newlines that broke the markdown table format.

Last I noticed missing parenthesis after the "description" item, causing the reference to the function appear instead of the returned value.

I hope you will find these suggestions useful.

In current markdown template, in the "Instances of" section, the current
implementation is rendered as "code block" by github and by pandoc.

I think this is because of the indentation of the html bits. html tags
and special characters are escaped by pandoc, i.e. the html source reads

```
table border="1" cellspacing="3" cellpadding="5" class="classproperties table-hover ">
<pre><code>&lt;tr&gt;
    &lt;th height=&quot;40&quot;&gt;Property&lt;/th&gt;&lt;th&gt;Description&lt;/th&gt;&lt;th&gt;Expected Type&lt;/th&gt;
&lt;/tr&gt;

[etc...]
```

I have reindented the template file so that the table is correctly included as
html, this seems to fix the issue.

Another way forward would be not to include html tables here, but use
the generally accepted markdown syntax for tables. An issue is to render
the 3-column span. Maybe split tables...
An attempt to move away from html tags, to let mardown-to-html renderers
use their own style.
Note the dash in the jinja markup to avoid harmful newlines.
Since Python 3.2, configparser.SafeConfigParser is deprecated
It has been removed in Python 3.11
Simply calling configparser.ConfigParser works in python 3.12
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