dotnet
Broken examples after update
Describe the bug
After update from 2.74.0 to 2.74.1, examples are broken. See https://github.com/json-api-dotnet/JsonApiDotNetCore/pull/1415#issuecomment-1837126296.
To Reproduce
- Clone the repo at https://github.com/json-api-dotnet/JsonApiDotNetCore
cd docs./build-dev.ps1- In the browser, navigate to Getting Started > API > JsonApiOptions
Expected behavior No broken HTML.
Did you try on Ubuntu?
You can see the diff by downloading and extracting the documentation artifact from https://github.com/json-api-dotnet/JsonApiDotNetCore/actions/runs/7055097802 and https://github.com/json-api-dotnet/JsonApiDotNetCore/actions/runs/7208009175.
The next screenshot shows the diff:
Here's what it looks like in Chrome:
Well, it does not render entirely correct in v2.74.0 on Windows either:
/// <summary>
/// Whether to use relative links for all resources. <c>false</c> by default.
/// </summary>
/// <example>
/// <code><![CDATA[
/// options.UseRelativeLinks = true;
/// ]]></code>
/// <code><![CDATA[
/// {
/// "type": "articles",
/// "id": "4309",
/// "relationships": {
/// "author": {
/// "links": {
/// "self": "/api/shopping/articles/4309/relationships/author",
/// "related": "/api/shopping/articles/4309/author"
/// }
/// }
/// }
/// }
/// ]]></code>
/// </example>
bool UseRelativeLinks { get; }
This is broken even worse in v2.75.1.
What it should look like (from https://www.jsonapi.net/api/JsonApiDotNetCore.Configuration.JsonApiOptions.html, which was built using v2.74.0), except for the incorrect curly indent:
What it does look like in v2.75.1 instead:
The first red arrow is new: it copies the class/interface-level comment and puts that as documentation for bool.
The source code comments can be found at: https://github.com/json-api-dotnet/JsonApiDotNetCore/blob/master/src/JsonApiDotNetCore/Configuration/IJsonApiOptions.cs#L57-L79
The docfx output for v2.75.1 is available as a downloadable build artifact at https://github.com/json-api-dotnet/JsonApiDotNetCore/actions/runs/7633561767?pr=1440. Extract documentation.zip and edit file JsonApiDotNetCore.Configuration.JsonApiOptions.html, which contains the following HTML snippet:
<div class="codewrapper">
<pre><code class="lang-csharp hljs">public bool UseRelativeLinks { get; set; }</code></pre>
</div>
<h4 class="section">Property Value</h4>
<dl class="parameters">
<dt><a class="xref" href="https://learn.microsoft.com/dotnet/api/system.boolean">bool</a></dt>
<dd>Global options that configure the behavior of JsonApiDotNetCore.</dd>
</dl>
<h4 class="section" id="JsonApiDotNetCore_Configuration_JsonApiOptions_UseRelativeLinks_examples">Examples</h4>
<pre><code> <pre><code class="lang-csharp">options.UseRelativeLinks = true;</code></pre><pre><code class="lang-csharp">{
</code></pre>
<p>"type": "articles",
"id": "4309",
"relationships": {
"author": {
"links": {
"self": "/api/shopping/articles/4309/relationships/author",
"related": "/api/shopping/articles/4309/author"
}
}
}
}</p>
Specifically, the part:
<pre><code> <pre><code class="lang-csharp">options.UseRelativeLinks = true;</code></pre><pre><code class="lang-csharp">{
</code></pre>
explains why it's rendered incorrectly. The text inside <pre> should not be escaped.
@yufeih Can you take another look? Please let me know what else you need to reproduce this.
Environment
Google Chrome version: 120.0.6099.225 (Official Build) (64-bit)
> dotnet --info
.NET SDK:
Version: 8.0.101
Commit: 6eceda187b
Workload version: 8.0.100-manifests.1c08acc9
Runtime Environment:
OS Name: Windows
OS Version: 10.0.22631
OS Platform: Windows
RID: win-x64
Base Path: C:\Program Files\dotnet\sdk\8.0.101\
.NET workloads installed:
Workload version: 8.0.100-manifests.1c08acc9
There are no installed workloads to display.
Host:
Version: 8.0.1
Architecture: x64
Commit: bf5e279d92
.NET SDKs installed:
8.0.101 [C:\Program Files\dotnet\sdk]
.NET runtimes installed:
Microsoft.AspNetCore.App 6.0.26 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
Microsoft.AspNetCore.App 8.0.1 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
Microsoft.NETCore.App 6.0.26 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.NETCore.App 8.0.1 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.WindowsDesktop.App 6.0.26 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]
Microsoft.WindowsDesktop.App 8.0.1 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]
Other architectures found:
x86 [C:\Program Files (x86)\dotnet]
registered at [HKLM\SOFTWARE\dotnet\Setup\InstalledVersions\x86\InstallLocation]
Environment variables:
Not set
global.json file:
Not found
HTML escape problems seem to occur when using both examples and `
Minimum reproducible source code
namespace Examples;
public interface IJsonApiOptions
{
/// <summary>
/// Whether to use relative links for all resources. <c>false</c> by default.
/// </summary>
/// <example>
/// <code><![CDATA[
/// options.UseRelativeLinks = true;
/// ]]></code>
/// <code><![CDATA[
/// {
/// "type": "articles",
/// "id": "4309",
/// "relationships": {
/// "author": {
/// "links": {
/// "self": "/api/shopping/articles/4309/relationships/author",
/// "related": "/api/shopping/articles/4309/author"
/// }
/// }
/// }
/// }
/// ]]></code>
/// </example>
public bool UseRelativeLinks { get; }
}
public class JsonApiOptions : IJsonApiOptions
{
/// <inheritdoc/>
public bool UseRelativeLinks { get; }
}
I've created a minimal repro at https://github.com/dotnet/docfx/issues/9736.