Future of this repository after RFC 145

[infinisil]

RFC 145 is almost accepted. This repository currently implements the doc comment parsing in Nixpkgs. What should happen to this repository after the RFC is accepted?

Pinging the RFC author and shepherds, did you have anything in mind? @hsjobeki @DavHau @sternenseemann @asymmetric

Note that @asymmetric agreed to let me take over maintenance of this repository, but I'd also be on-board to either help change it as necessary for the RFC, or to help out maintenance of a new repository.

I mainly don't want to end up with two repositories doing almost the same thing, both needing maintenance :)

[tazjin]

with two repositories doing almost the same thing

Which one would be the other one?

[hsjobeki]

What should happen to this repository after the RFC is accepted?

Lets discuss an envisioned migration path:

First nixdoc currently plays an important role in rendering the nixpkgs manual. Unfortunately concerns are not strictly seperated. see here

From my view nixdoc is a static analysis tool, that also pre-renders parts of the nixpkgs manual. Unfortunately making predictions how the nixpkgs manual is rendered. Those predicitions make it very hard to change the manual rendering, as both now making predictions on each other and rendering depends on those.

I think in the mid term nixdoc should support the new format in parallel, and also have a JSON output, that allows other projects (than the nixpkgs manual) to use it.

Support for the old format should then be removed entirely once nixpkgs has been migrated. Example PR here

For the nixpkgs migration to happen, we have to support both formats for a while, as we cannot (or should not) change everything at once.

How it could work in details:

• Detect usage of markdown e.g. via headings # H1 or even markdown parsing.

  • If the comment is /** */just return the markdown.
  • If comment is /* */ or # -> old format. Legacy (current) rendering happens, with retrieval of "function arguments".

• We should also add a json output (e.g. --json flag) that allows easy experiments with other renderings. (Other than the current manual)

I mainly don't want to end up with two repositories doing almost the same thing, both needing maintenance :)

For now, we don't have any other tool doing the same thing right? And support in native nix is still WIP or not even started yet.

[hsjobeki]

I think the long term goal could be to either archive this repo, or make it a small cargo package, that downstream users can use with rnix-parser. (only for static retrieving of doc-comments from a given ast or sth.)

[infinisil]

Just saw you open https://github.com/nix-community/nixdoc/pull/91 :clap:

[infinisil]

Now addressed with https://github.com/nix-community/nixdoc/pull/91 :)