I just tried mdx: ✔

Community
1

I’ve just updated my printbox library (collaboration with @zozozo) to provide a better API, and used mdx to use the readme as a series of tests. It’s really nice, so thanks to the devs of mdx!

11 Likes
2

@c-cube I would avoid the details element in the README for the examples: it makes them unlinkable.

1 Like
3

Oh, good point, I didn’t realize. Thanks.

4

Glad to hear it! I’m looking into integrating md2mld into it as well, so that it can output ocamldoc front matter from a single README as well.

Just one headsup: I’d like to rename the binary to ocamlmdx to make it easier to package up in distros, so there’s a tracking issue here: https://github.com/realworldocaml/mdx/issues/100

5 Likes
5

Cool! Let me know if I can help in some ways.

6

PR to mdx very welcome if you want to give it a shot :slight_smile: I thought that it would be nice to have a single dune rule that:

  • compiled and promoted a README.md
  • wrote out an index.mld file from the README.md
  • rewrites an opam description: field to keep it in sync

I haven’t thought through how multi-opam packages would work – we’d need some structure in the README similar to how topkg interprets the first line for a synopsis.

7

Thanks. I have been thinking without success about the correct way to generate a comprehensive index (I also wanted the user to be able to specify folders as sets of documentation pages), do you have any recommendation for that?

I will look at what topkg does and play around with that idea as well.

8

I think the main guiding principle should be the elimination of redundant documentation, and mechanically generating as much as possible (e.g. mdx).

I played briefly with a ‘standard template’ model that Dune could automatically generate. This could have all the expected pieces for a new user in the README

  • name and synopsis on the first line (as topkg does)
  • first para introduction to core library
  • installation instructions:
    • how to install deps with opam
    • how to build with dune
    • description of all the packages in this repository, with a para for each
  • usage
  • license information
  • how to contribution and seek help (

If the tool has markers for these sections, the Dune could generate the template and dune-release could extract the information to update the various opam synopsis and description fields also.

I’ve got a WIP dune tree to add this metadata (e.g. spdx license information) to dune-project so that the LICENSE file could also be generated and eventually so opam metadata could be generated, but for now just parsing existing files might be enough.

(These are thoughts written in a morning rush, so I’m happy to elaborate more later :slight_smile:

3 Likes
9

Your library is fun.
However, at some point, you can dump your data to a csv file and open it in a spreadsheet. :wink:

1 Like
10

Well I don’t think csv supports trees inside boxes inside boxes, with multi-line text :wink:

1 Like