markdown generator

[lubegasimon]

Todo:

• Remove redundant h6 level after the last variant of a constructor. Also the
  spacing between h6 and items is not neat.

    ######             type days  = 
    
    ######               | Mon  
    
    first day of the week.
    
    ######               | Tue  
    
    Second day of the week.
    
    ######       (** This is the bug! *)

• Entity and Rawmarkup branches for Inline.t are not yet handled in inline function.

Help needed!

• Reasonably use a single back tick and double back ticks for code spanning.
  In cases where source code contains ‘`’, we want to wrap the content in double back ticks,
  other wise, wrap the content in single back ticks.

• at-tag keys and definitions should not be rendered on separate lines (This is one one the properties of blocks,
  that is, blocks must be separated by an empty line). That is,

@author : 

John Doe

should be rendered as @author : John Doe.

The unwanted behaviour is because the definition of the at-tag is type blocks
— John Doe, where as @author : is inlines, as a consequence, if anything
is to be combined to the definition, it must be blocks.
(I don’t think there is a workaround for this, but I will be happy to see how it can be improved)

• There are unwanted spaces rendered between some inlines. For example
  module Bar : sig ... end should instead be module Bar : sig … end.
  For clarity, in the output, there are two spaces between module and Bar, two spaces
  between Bar and :, and three spaces after end. I think I’m wrongly treating the output
  of the document library.
  If someone is ready to take on this, I will be happy to see it improved. However, I advise to do
  this after the next list item.

• The use of join and item_prop isn't nice , it should perhaps be heading instead

• Entirely get rid of join (iff there is a better alternative to combine inlines).

[lubegasimon]

After some offline discussion previously with @Julow, we agreed to drop the concept of adding back ticks to everything that appears as OCaml code as that would cause cluttering of the markdown output, thus making it unreadable and leading to unexpected poor rendering. In that case, we decided to let OCaml code be formatted using the h6 level.

For example;

module type Foo = sig
  type foo
end

would be formatted as (without backpacks) —

  ######       module type Foo = sig
  
  ######           type foo
  
  ######       end

and the preview is —

whereas, it would be formatted as (with back ticks) —

  ######       `module type Foo = sig`
  
  ######           `type foo`
  
  ######       `end`

and the preview for that is —

[lubegasimon]

‘ocam-ci' is failing because of \ in OCaml’s nbsp and I am not sure how to escape it.

[EmileTrotignon]

This looks like a big PR, and should probably not be part of 2.4