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

Add syntax color to ocamldoc markup #1365

Merged
merged 13 commits into from
Jan 31, 2024

Conversation

dlesbre
Copy link
Contributor

@dlesbre dlesbre commented Jan 23, 2024

A few ocamldoc markup had syntax color, but most didn't. This PR adds color to most markup, using the similar markup in markdown for the textmate scope. For reference, I used the following:

Changes

Before this PR, only few constructs had syntax coloring:

  • @tags
  • [inline code] (note that inline code is rendered using ocaml's syntax highlighting, and not semantic highlighting. Depending on theme, the colors may be very different from the rest of the file).

I added the following:

  • {b bold] {1 heading] {i italic] {e emph} (colored the same as their markdown equivalents)
  • {^ exponent} {_ index}, likely not colored in most themes (named markup.exponent.ocamldoc)
  • {m math} and {math math-block}, odoc extension, colored the same as latex math (which is support.class for some reason...)
  • {[ocaml code block]}
  • {v verbatim v} and {@lang[ other language code block]} (odoc extension), colored as markdown code block
  • {{: link}link-text}
  • {!reference} and {!type:reference], as well as {{!reference}alt-text}. I'm not really satisfied with the later though, as I can't color both reference as ocaml code and alt-text as markup (tm grammar don't have a begin/middle/end sadly).
  • Lists both simple (leading -) and complex {ul {li item}}
  • Target specific formatting {%latex: latex code%} and {%html: html code %} as well as others (rendered as verbatim code)
  • tags specific syntaxes for @raise Exn, @raises Exn, @param id, @see "document", @see 'file' and @see <url>

I haven't added the following:

  • {C center}, {L left} and {R right} (not supported by odoc)
  • {!indexlist} (not supported by odoc)
  • html tags (not supported by odoc)

Test comment

Here is a comment showing off the new color highlights that can be used to test them with different themes:

(** This is a test documentation comment:
  @see <https://v2.ocaml.org/manual/ocamldoc.html#s%3Aocamldoc-comments>
       for ocamldoc syntax reference
  @see <https://ocaml.github.io/odoc/odoc_for_authors.html>
       for odoc (implementation of the reference, plus a few extensions, like math)

  Basic markup:
    {1 heading}
    {b bold} {i italic} {e emph} {m math}
    {^ exponent} {_ index} (these are maked, but not colored by most themes)
    {v verbatim v}
    {C center} {R right} {L left} (There are unmarked and uncolored)
    {math
      math block
    }

  Tags:
    @tag
    @raise Exn description    @raises Exn description
    @param id description
    @see 'filename'           @see "document-name"       @see <link>

  Code:
    [let foo x = x]
    {[
      let foo x = x
    ]}
    Other language are an odoc extension. I haven't added any language specific
    code, so this python snippet isn't highlighted as python, only as verbatim.
    {@python[
      def hello() -> None:
          print("hello world!")
    ]}

  References and links:
    [foo] {!foo} {!module:Foo} {!modules: Foo Bar}
    {{: https://example.com}Example link}
    {{!foo}The foo function}
    {{!module:Foo} the Foo module}

  Lists:
    - simple
    - unorderd list
    + simple
    + numbered list
    {ul {- full}
        {li list {b with bold text} }}
    {ol {- ordered}
        {li list}}

  Target specific blocks:
    {% here is some latex \foo $1$ %}
    {%latex: some more latex $x = x+1$ %}
    {%html: <p>hello</p><a href="https://example.com">example link</a> %}
*)

Copy link
Collaborator

@mnxn mnxn left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for the very detailed PR. The highlighting changes look great!

I only have a few implementation comments:

syntaxes/ocamldoc.json Outdated Show resolved Hide resolved
syntaxes/ocamldoc.json Outdated Show resolved Hide resolved
@dlesbre dlesbre force-pushed the ocamldoc-syntax-color branch from 9f09c40 to b650be5 Compare January 30, 2024 08:17
@dlesbre dlesbre force-pushed the ocamldoc-syntax-color branch from b650be5 to 3ba7180 Compare January 30, 2024 11:05
@dlesbre
Copy link
Contributor Author

dlesbre commented Jan 30, 2024

I've also added a small change to fix #1014, (simply removing the global scope name comment.other.ocamldoc from the ocamldoc.json. It won't changes the color of comments in .ml/.mli files since its already added in ocaml.json, but it removes the color from mld files.

Copy link
Collaborator

@mnxn mnxn left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice work!

@smorimoto smorimoto merged commit 6c45266 into ocamllabs:master Jan 31, 2024
7 checks passed
@smorimoto smorimoto mentioned this pull request Jan 31, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants