doc: implement meta.doc

[sandydoo]

@k3yss

This is basically what NixOS does. The meta attribute is allowed by the module system, but not defined by default, so we can hijack it for our needs. Every module now has a meta.doc field that can be populated.

I tried doing a submodule for languages, but there's some sort of error about nested options that needs investigating.

languages = lib.mkOption {
  type = types.attrsOf (types.submodule ({...}: {
    freeformType = types.attrsOf (types.submodule ({...}: {
      imports = [ ./doc.nix ];
    }));
  }));
};

The tricky bit is that we define the nav manually in mkdocs.yml. I'm not sure how to tell it to pick up all files within a directory. We might need to write a small plugin.

[sandydoo]

It might be more convenient to write docs in a separate markdown file and then point meta.doc to it.

Technically, we don't really need this machinery right now. If we just want to add language guides, then those markdown files can live in docs. 🤷

[k3yss]

I am also in favor of writing the docs in separate markdown file. I think it's better if we generate the docs dynamically, as we do now; otherwise, we won't have any connection between the .nix files and .md files, which could make the codebase difficult to navigate for future contributors.

Also how would we include the option references that we currently employ with this format as that too will be dynamically generated?

[cloudflare-workers-and-pages[bot]]

Deploying devenv with    Cloudflare Pages

Latest commit:	23e0e6c
Status:	✅  Deploy successful!
Preview URL:	https://497e0677.devenv.pages.dev
Branch Preview URL:	https://add-doc-meta.devenv.pages.dev

View logs

[sandydoo]

I think it's better if we generate the docs dynamically, as we do now; otherwise, we won't have any connection between the .nix files and .md files

Well, we generate the reference docs (and some other bits), but everything else, like guides, lives in /docs. That's why I'm curious what the goal is with this setup. If we make meta.doc point to a markdown file, then it can live next to the nix module it describes. But we don't really need nix to find those files and copy them over to /docs.

Also how would we include the option references that we currently employ with this format as that too will be dynamically generated?

The reference options are generated separately in devenv-generate-doc-options. This doesn't affect that. You can reference options in the meta.doc if you need to though (see diff).

[k3yss]

But we don't really need nix to find those files and copy them over to /docs.

I think if the docs are stored in the /docs directory and we point to it using meta.doc we will be fine. But we should implement a conditional to only render the docs if it is referenced via meta.doc, else throw an error for the doc being not referenced or not render it on the website.

[domenkozar]

I wonder if we get any benefit from this over just docs/languages/python.dm?

[sandydoo]

I wonder if we get any benefit from this over just docs/languages/python.dm?

If we just want to add language guides, then those markdown files can live in docs. 🤷

Yeah, that's what I'm saying.

[k3yss]

Should we close this @sandydoo