Add HTML code element for code samples to enable syntax highlight.

[yazeedobaid]

Motivation

Enabling syntax highlights on XML documentation code samples will make it easy for readers and users of an API to understand the code samples quickly and without much effort. The current published version of fsdocs enable syntax highlight on comments written in markdown format. However, following the guidelines in F# Recommended XML doc extensions for F# documentation tooling RFC produces an output that has no syntax highlight nor we can add syntax highlight to it due to the HTML structure that the samples are written on, the structure is not the convention so, other libraries will not detect it.

Following the conventions from syntax highlighting libraries like highlightjs and prismjs and w3.org site samples, the code samples should be put in a code element inside the pre element.

This PR attempt to add this to enable syntax lighlight.

Fixes #761

Example

For example, for the following standard XML documentation code:

/// <summary>
/// A test module...
/// <example>
/// <code lang="fsharp">
///         let files =
///                [ "build"; "docs" ]
///                |> List.map (fun n -> sprintf "%s.zip" n)
/// </code>
/// </example>
/// </summary>

The result after using the tool to generate API documentation is as follows:

<pre>
+    <code class="fsharp language-fsharp">
        let files =
            [ "build"; "docs" ]
            |> List.map (fun n -> sprintf "%s.zip" n)
+    </code>
</pre>

Note that the language on XML code element has transferred and been mapped to the corresponding HTML element for syntax highlighters to get and operate on. In this way, users can pull a syntax highlighter and it will work out of the box.

By this, the XML documentation will be kept with no changes. However, the output HTML will be as follows with changes highlighted.

[nhirschey]

This added extra spaces to the api docs code output, making the format less visually pleasing (see #644 (comment)).

@yazeedobaid, one option might be to use the code for generating fssnip highlighted class used elsewhere in the library to style F# code. This is the built-in F# syntax highlighting used by the rest of the F# Formatting library (see screenshot below inspecting the F# formatting website).

[yazeedobaid]

@nhirschey I looked at PR #762 and the trim for the new line still exists. Please see this line. Maybe it is caused by a css rule that got applied after the addition of the code element inside the pre element?

The change in PR 762 was for the examples in API docs not for examples in literate scripts. FSDocs back then didn't parse the example as shown in the literate script, as you can see the code is parsed and divided into HTML elements based on F# sytnax highlighter, that was not the case for examples from API docs. The example was nested under a pre HTML element as a raw text. Please see original issue that demonistrate why the change was done.

[nhirschey]

Yup, there's css styles being applied, and I think the nesting of those styles is messing it up.

I saw your issue, I agree that syntax highlighting in API reference is useful. An fsdocs website can have F# code examples in the API reference (what you were addressing in your PR) and in other pages on the site (what is currently highlighted by this library's custom syntax highlighter). My suggestion is that we use this library's custom syntax highlighter for the API reference too. It would provide a consistent look across all F# code in a docs site generated by this library.

[yazeedobaid]

Yeah, sure I agree with that.