Documentation

[minikN]

One thing that always bothered me about RDE was the lack of documentation. You'd have to browse the source code to actually understand how a feature works and what it is doing.

I think this (https://migalmoreno.com/projects/ordenada.html#configuration-options) is already solving half the issue. However, I feel like this doesn't cover everything there is to know. For example, the screenshot/video capture scripts you added in the sway module are not documented that way.

I feel like it'll be nice to either have a manual (markdown/pdf/html/latex/wiki/whatever) that covers each module, that it provides and how it may interact with other modules

[migalmoreno]

Indeed, documentation is also something that I really appreciate. Currently Ordenada only exposes the modules options via nixosOptionsDocs here. This tool only lets you export to JSON, Markdown, and manpages formats so I'm currently using org-export to export these to Org, and shipping them in a docs package. You can try to build it yourself with nix build .#docs from the project root which should create a result directory with Markdown and Org files (though upon testing it now, it seems like df5f7ba broke the evaluation of modules, so you might need to do it with an earlier commit).

Then, I'm importing this docs package in my blog and appending the list of options to an existing project page. You might want to read this blog post I wrote a couple of months ago about how I approached this.

Some of the solutions that I came across in the Nix ecosystem before going for this solution this were:

• nixos-wsl and stylix use mdBook
• nixarr uses a custom website-builder based on Pandoc to convert Markdown documents to HTML
• Home Manager and NixOS use nixos-render-docs which renders Markdown and manpages formats.

At the end of the day, they are all some sort of static site generators. I went with a custom solution because I wanted to keep using Haunt so that I could use Org to eventually write the project documentation. However, at the moment it only displays the README + the options from the docs package.

I don't want to have to include the modules documentation inside the README, so my suggested approach would be to create a docs/ top level directory with Org mode wiki files for features + general documentation and going one of two options at build step:
A) We switch to one of the above static site generators, export the files in docs/ to Markdown (with org-export, I've tried Pandoc but it doesn't work well for Org->Md exports) like we do for the options
B) We keep files in Org mode format and write a custom Haunt wiki builder which reads files from docs (or any arbitrary project directory), and builds a similar page layout to that one found in the other SSGs (sidebar with hierarchical table of contents and links to every page).

Honestly, I'd like to go with B because I'd rather not write the docs in Markdown, and I don't want to deal with Org to Markdown exports quirks, or having to specify site settings in YAML/TOML/etc, but I can't properly estimate how much effort it would take. Using the org-mode-reader + Haunt would also allow us to not have to use JS to syntax highlight code blocks, since everything is done at build time by Emacs. Either way, we could also totally detach the Ordenada page from my personal site and create a separate site with a domain hosted on GitHub pages.

[minikN]

With the approaches you mentioned, would we write the documentation for a module separated from the module code?

There doesn't seem to be a default for function parameter documentation (like JSDoc for JS) in the nix language (AFAIK).

The approach I'd aim for would be to generate the documentation for a module directly from the code, if possible.

IDK how difficult it'd be but maybe we can place a multiline comment in a module with special syntax and parse it to create the docs for a module (ideally export it into one file, following with the options docs for the same module).

Maybe like

### @name Home module
### @desc Description of home module
###
### @example Showing of some functionality
### Some text
### ```
### some code
### ```
### @end
### @example Some other example
### ...
### @end

But I don't know how difficult that would be, maybe there is an easier approach. In any case, I'd like to (somehow) include all documentation for a module inside the .nix file for that module itself. That would make having the docs up-to-date with thr implementation easier in the future, as long as we are dilligent about it in future PRs of course.

With the new sub folders I created in my last PR we could also introduce a hierarchy for the module documentation. E.g. in modules/default.nix we could write down the general module docs (in modules/wm/default.nix general wm modules docs and so on). Maybe we could even create links / indexes based on the folder structure.

Again, IDK how feasible this would be, but leaving technicalities to one side, this would be the end goal IMO in terms of documentation.

[minikN]

I could easily write a parser for that using JS, that creates a folder with .md files that we can then post-process with your approach to create .org files. But idk if we want to introduce JS just for that, but I think doing it in nix itself would be a daunting task for me :D