Removed HTML tags from Markdown trait export

[Mailaender]

This is a workaround for mkdocs/mkdocs#2400, but I thought it might actually be nicer as Markdown is easier for humans to read compared to hard-coded HTML tags.

[pchote]

Looks reasonable, but have you tested it works? I usually find it takes 5+ attempts to get tables to actually render whenever I try to make one.

The other doc generating commands should be changed to match.

[Mailaender]

I tested with @retext-project and @mkdocs locally.

[abcdefg30]

Works nicely.

The other doc generating commands should be changed to match.

That is still open, isn't it?

[Mailaender]

If you insist. As MarkDown forbidds linebreaks in tables I had to come up with something else for the Lua page.

[pchote]

What do you mean? Do you have a before and after image? Some quick searching suggests that <br> should work fine in tables...

[Mailaender]

| Test

line break	Test

Test without line break	Test

[Mailaender]

I came up with forced tables for the Lua API to preserve your original layout although I think headerless tables were a really bad choice here. It really gave me a hard time here and it isn't very readable in .md viewers.

[pchote]

Test line break using <br />	Test

[abcdefg30]

Github renders the triple * directly and not as bold text:

Using only **text** fixed the issue for me.

[Mailaender]

Should be fixed now.

[abcdefg30]

Unfortunately, there seems to be some kind of issue with line breaks(?):

[abcdefg30]

I put the output file I got at https://gist.github.com/abcdefg30/6610bdfaa06e4c00dd209a71dd83aa0c, then you can hopefully easily see the spots with that issue. (Or is that a bug in the GitHub Markdown renderer?)

[Mailaender]

A Markdown table is required to have a header, which is why @pchote original design is causing trouble here:

|---|---|
| int BuildTime(string type, string queue = nil) | Returns the build time (in ticks) of the requested unit type.
An optional second value can be used to exactly specify the producing queue type. |
| int Cost(string type) | |
| Actor Create(string type, bool addToWorld, LuaTable initTable) | Create a new actor. initTable specifies a list of key-value pairs that defines the initial parameters for the actor's traits. |
| int CruiseAltitude(string type) | Returns the cruise altitude of the requested unit type (zero if it is ground-based). |

won't work.

[Mailaender]

I simply added headers with contents as GitHub flavored Markdown and many others don't support headerless tables. https://stackoverflow.com/questions/17536216/create-a-table-without-a-header-in-markdown

[pchote]

GitHub flavored markdown does support headerless table, I demonstrated this in the comment above: #19403 (comment).

Edit: I see, that was the header.

[matjaeck]

Since the previous comment has been marked off-topic:

An alternative way to highlight code in HTML-tables is:

<table>
<tr><th>Property</th><th>Default Value</th><th>Type</th><th>Description</th></tr>
<tr><td>ValidTypes</td><td></td><td>Set of String</td><td>Accepted <code>DeliversCash</code> types. Leave empty to accept all types. </td></tr>
<tr><td>ValidRelationships</td><td>Ally</td><td>PlayerRelationship</td><td>Player relationships the owner of the delivering actor needs. </td></tr>
<tr><td>Sounds</td><td></td><td>Collection of String</td><td>Play a randomly selected sound from this list when accepting cash. </td></tr>
</table>

<code>DeliversCash</code>

This is valid HTML, perhaps someone misread the comment…

Edit: Deleted some formatting changes and actual off-topic moderation-related content since i just wanted to drop this information here and not engage in discussions. Maybe it helps, maybe not.

[Mailaender]

But then there is nothing Markdown left and both @github and @readthedocs take that as input. The HTML is compiled from it.

[pchote]

Why do we care about eliminating html from this? Surely the goal should be in having the best quality rendered output.

[abcdefg30]

Lgtm once that is fixed, I don't think we need or should go back now.

[pchote]

Looks fine aside from two points:

[Mailaender]

Updated.

[Mailaender]

Updated.

[pchote]

I'm not sure if the last push broke it or if I just didn't notice it before, but the output of the lua player properties/commands all end up on one line (the other two lua types are output correctly).

[Mailaender]

Should be fixed now.

[pchote]

https://github.com/OpenRA/OpenRA/wiki/Changelog-(bleed)/_compare/1ba8ef8295057e785907ca0a964dd1aea78698d8