Markdown -> Ocamldoc conversion

[jfrolich]

Work in progress.

I am not stoked to introduce Str here, there's probably a better way to do this, I just wanted it to make it work first.

You can test it with the following:

create file test.md:

# this is a markdown test document

This is _important_ or **very important**, let's try the `code` fences.

```
let x = "bla"
```

Hello this is a ordered list

1. One
2. Two
3. Three

And this is a unordered list

- One
- Two
- Three

## Another header

Blah blah blah

> This is some quote

And this is a link [Hello](https://reasonml.org).

    another code block?

<https://reasonml.org> <-- A link

<module:Module> <-- An explicit cross reference

<ref:Module> <-- An inferred cross reference

Now get the result with the following command:

dune build && ./_build/default/tests/omd_ocamldoc.exe test.md

It yields:

{0 this is a markdown test document}

This is {e important} or {b very important}, let's try the [code] fences.

{[
let x = "bla"
]}

Hello this is a ordered list

+ One
+ Two
+ Three

And this is a unordered list

- One
- Two
- Three

{1 Another header}

Blah blah blah

{v
This is some quote
v}

And this is a link {{: https://reasonml.org} Hello}.

{[
another code block?
]}

{{: https://reasonml.org} https://reasonml.org} <-- A link

{!module:Module} <-- An explicit cross reference

{!Module} <-- An inferred cross reference

[nojb]

Thanks! Could you say a few words about the intended use-case for this?

[jfrolich]

We are looking to support markdown syntax for documentation in Reason to make documenting code more accessible for newcomers. As markdown is ubiquitous, ocamldoc is just another indirection that adds friction. Additionally markdown has proven itself to be much more readable in plain text, so that is more ergonomic when reading source code instead of generated documentation from ocamldoc.

If you don't think this printer should be in scope of omd that is fine.

By the way. Did you think about creating a markdown output, this will allow creating a pretty printer for markdown (automatic prose-wrapping)?

[jfrolich]

By the way. Did you think about creating a markdown output, this will allow creating a pretty printer for markdown (automatic prose-wrapping)?

There is a pretty extensive test suite with input/output snapshots in the prettier repo: https://github.com/prettier/prettier/tree/master/tests/markdown.

[nojb]

We are looking to support markdown syntax for documentation in Reason to make documenting code more accessible for newcomers. As markdown is ubiquitous, ocamldoc is just another indirection that adds friction. Additionally markdown has proven itself to be much more readable in plain text, so that is more ergonomic when reading source code instead of generated documentation from ocamldoc.

Sounds like a good idea, indeed.

If you don't think this printer should be in scope of omd that is fine.

Well, on the one hand, it sounds like a cute addition. On the other, it look like something slightly specific that can very well be coded client-side, and I am a bit reticent to add a feature that will be used by a single project. I would like to think about this a bit more.

By the way. Did you think about creating a markdown output, this will allow creating a pretty printer for markdown (automatic prose-wrapping)?

Yes, we used to have a Markdown backend, but I removed it because it was incomplete/buggy. However, recently someone else also requested a markdown backend, so am planning to put it back in (but haven't done so yet).

[mseri]

Nice, this would allow getting rid of https://github.com/mseri/md2mld

The rationale there was that many packages have extensive README that would be nice to bundle as documentation introductions or tutorials (instead of always relegating them to the repository)

[jfrolich]

this would allow getting rid of https://github.com/mseri

Yes!

[shonfeder]

We'll revisit this once we've stabilized the AST and have some answers to #205.

In the meantime, I wonder if it would make sense to connect with the ocamldoc maintainers to see how they feel about this kind of feature, and if they have any opinions/suggestions on how to execute in way that would work best with the rest of the ecosystem.

[mseri]

Sure! @jfrolich in the meantime, feel free to submit any improvement from this PR that you may need to md2mld