rescript-tools-doc-md [WIP]

Description

Library to convert an extracted docs json into markdown. This work explores the possibilities of generating easily usable documentation basd on rescript files.

Inspired by a rescript forum post announcing @rescript/tools by zth I started tinkering with the idea for this project.
This is still work in progress and I'm thankful for any feedback.

There are several milestones to my vision of a basic general purpose rescript code generator:

1. library to transform type RescriptTools.Docgen.doc into a markdown string (current efforts focus on this)
2. "orchestrator" to handle fs operations
   • (optionally) parse any needed config
   • parse rescript.json for source-dirs
   • read any of those rescript files into a docgen json
   • modify docs to split it up into several chunks - if more & smaller md files are desired
   • use the library to get a markdown string from the json representation
   • write the generated markdown to disk
3. potentially integrate above into @rescript/tools cli, if everything fits

Note: 2. may be the beginning for a general purpose rescript (code) generator library

This project builds heavily upon @rescript/tools.

Example

To see how it works, take a look at the test directory. Based on @rescript/core: src/RescriptCore.res, npm run makeTestJson is used to generate test/CoreDoc.json using rescript-tools.

The result of applying this lib can be seen in test/result.md

Installation

npm install

Build

• Build: npm run build
• Clean: npm run clean
• Build & watch: npm run dev

Test

Print test md to stdout:

npm run test

Print test md to file:

npm run testToFile

Open Issues

• render doc.name
• render doc.deprecated
• render doc.docstrings
• render value doc.items
  • render name / id
  • render docstrings
  • render depecated
  • render signature
• render type doc.items
  • render name / id
  • render deprecated
  • render docstrings
  • render signature
  • render detail
• render module doc.items
  • render name / id
  • render deprecated
  • render docstrings
  • render items
• render module alias doc.items
  • render name / id
  • render docstrings
  • render items
• docstrings may also include markdown (e.g. ## Examples) -> this markdown syntax should be manipulatet to match the current heading level?
• unescaped \n
• don't escape special chars (e.g. >) in codeblocks inside of docstringrequire'lspconfig'.ocamllsp.setup{}s
• docgen for module types
• docgen for functors
• docgen for first class modules
• meaningfull overall structure of md