Project description

Migrate module docs to markdown.

Pandoc should be able to mix and match 🤞

Suggested pipeline

• XML
  • -> custom XSLT ->
• Markdown with arbitrarily formatted snippets
  • -> pandoc ->
• anything.

Suggested migration path

1. Implement the pipeline, so we support multiple languages
2. Start the conversion to description = lib.docMD "...", etc
3. Forbid non-wrapped description (and other such attrs)
4. Switch the default to markdown, remove the lib.docMD calls.
5. Optionally, simplify the pipeline

From the broader ecosystem perspective, it would be good to keep the flexible pipeline, as we can use it to dismantle the cottage industry of custom module docs generators. It's a matter of wrapping it with the right pandoc syntax.

Technical details

(just to get a feel for it)

description = lib.docDB "This is <literal>docbook</literal>.";

->

description = { type = "doc"; lang = "docbook"; text = "This is <literal>docbook</literal>."; };

->

Some XML

->

Markdown:

    Description:

    ```{=docbook}
    This is <literal>docbook</literal>.
    ```

Alternatives

• Maybe XML + XSLT should be JSON + Python. @pennae has already converted some things to python as part of their eval performance work.

Metadata

• homepage URL: module system does not have a dedicated homepage
• source URL: lib/, nixos/, pkgs/
• license: mit, bsd, gpl2+ , ...
• platforms: unix, linux, darwin, ...