dotnet / docfx

Static site generator for .NET API documentation.
https://dotnet.github.io/docfx/
MIT License
4.09k stars 867 forks source link

Processing Code Examples <code> generating extremely strange formatting. #10417

Open mxcolin opened 16 hours ago

mxcolin commented 16 hours ago

I've tired various different ways of formatting code examples, both within <example> tags and outside them. Either way there just doesn't seem to be a way to reproduce consistent formatting. At times, random <p> tags are added to the HTML, at other times a single space becomes 6 spaces in the resulting HTML, I've tried numerous ways to get this working and there just doesn't seem to be a way that reliably works. The output is always skewed. Missing newlines, newlines when I don't want them. Extra tabs I didn't add, no tabs where I wanted tabs. This is very broken. I've tried new lines before the code blocks, that doesn't help.

Here's a simple example:

/// <code>
/// using (var m = new MyClass())
/// {
///     var s = m.Method("Guess the formatting");
/// }
/// </code>

This results in some extra tabs appearing I didn't ask for. Image Or a more complex example:

/// <code>
/// var myobj = new MyClass { Hostname = "server", Port = 3306, Username = "user", Password = "pwd1234" };
/// 
/// using (var m = new MyClass(myobj))
/// {
///     // Load a pre existing schema into a Schema object
///     var s = m.LoadSchema("my_schema");
/// }
/// </code>

in this case my new lines and tabs are all removed???: Image

The strange thing with this second example is that the HTML code has a <p> tag generated within the <code> tag like so:

<pre><code class="lang-csharp">var myobj = new MyClass { Hostname = "server", Port = 3306, Username = "user", Password = "pwd1234" };
<p>using (var m = new MyClass(myobj))
{
// Load a pre existing schema into a Schema object
var s = m.LoadSchema(&quot;my_schema&quot;);
}</p></code></pre>
mxcolin commented 16 hours ago

Same problem with 2.78.1

mxcolin commented 15 hours ago

More complex examples result in a whole other set of failures such as HTML code bleeding into the display:

Image

paulushub commented 12 hours ago

See #10385, being fixed through #10390