Thoughts on template documentation

[quarkQuark]

I may be misunderstanding how they're intended to work, but how come ./templates/module/homeCat.nix and ./templates/module/systemCat.nix are in the same directory?

I can't see someone wanting to download and use a system module and a home module at the same time. But I'm also not on NixOS so I might be missing how system modules work.

Also, I was thinking about how to deduplicate documentation writing for templates.

• Is :help nixCats.templates actually worth having? It's not something people should need to keep checking once they have nixCats installed, and Neovim doesn't really give a better viewing experience than a README if it's just a Nix expression containing the descriptions.

• If there is a reason to keep it, is there any Nix-y (or convenient GitHub action–y) way of generating it from either ./README.md or a new ./templates/README.md?

[BirdeeHub]

Hmmmm

We could move the templates thing out of the neovim docs and into the web docs/readme they just need to be somewhere. I think I was just too lazy to make a whole new page on the website for it, although its probably about due for that.

The two module demonstrations are in the same template directory because of... idk actually. Theyre both modules? They should probably be in separate templates now that I think about it.

Im not sure if theres a nixy way to generate the template explanations into a markdown file or similar. I should try to do that sometime. I was able to find a way to generate the utils/default.nix into docs, and the module options, but both were done via separate tools. Im sure there is a way to do it with the templates set, but idk what it is.

I have several things I need to do over the next week or 2 but I might have some time to mess around with trying to generate that from the templates/default.nix file

Currently all docgen is done via the flake in this repo https://github.com/BirdeeHub/nixCats-doc

I could run that as an action within the nixCats repo eventually, or separately as I do currently.

Right now Im just doing it separately. When I update any docs in nixCats I go to the repo registered with azure as containing the static site and I run the flake from nixCats-doc and it generates the new site files. Then I push it up and a workflow publishes it.

[BirdeeHub]

It seems the generator i used for the utils doesn't work with the templates/default.nix file

https://github.com/BirdeeHub/nixCats-doc/blob/main/gen_docs%2Ftemplates.nix

^ this just generated an empty page. You can view what it generated lol but there's nothing there

https://nixcats.org/nixCats_templates.html

I can try some nix eval stuff maybe

[quarkQuark]

My thinking was inspired by what people often do in the Emacs world.

First, I would think it fairly easy to make a GitHub action taking .templates/default.nix and turning it into a help file if we still want one. The only hurdle I can think of is if the

vim:tw=78:ts=8:ft=help:norl:

line needs to stay at the end of the file. But that shouldn't be hard to deal with. Alternatively it could just be its own standalone help file, which would be much simpler to generate.

Then the next level is that it might be possible to make another GitHub action generating ./templates/default.nix straight from ./templates/README.md.

If you were happy with switching the README syntax to Org instead of Markdown, then I think I could do this quite easily. But it feels somewhat ironic to use Org for a Vim project, and the GitHub action would end up calling the Emacs executable!

There are probably ways of doing this with Markdown, but I have no experience with them and I don't know how mature they are. The nice thing about Org is that it's quite easy to have, say, a table with

| Name  | Path    | Description |
|-------+---------+-------------|
| fresh | ./fresh | ...         |

and then use some intermediary Python code to generate

fresh = {
  path = ./fresh;
  description = "...";
};

Someone should write a way to do this with Nix, but I haven't seen one yet. And my Nix-fu is currently very weak. This is another option going in the other direction.

Then in the future if any templates are changed, the only documentation that needs changing is in the README.

A warning: I am the sort of person who gets too excited about contriving systems to avoid any perceived inefficiency. You would be perfectly justified if you think this would all make the repo too complicated. It's also very possible that at some point the templates will be very stable and the documentation will never need to be changed anyway.

[quarkQuark]

The nice thing about Org is that it's quite easy to have, say, a table with

| Name  | Path    | Description |
|-------+---------+-------------|
| fresh | ./fresh | ...         |

Though actually one very annoying thing here is that you can't have line breaks in Org tables.

I think generating it from

** [[https://github.com/BirdeeHub/nixCats-nvim/blob/main/templates/fresh][=fresh=]]

Multi-line description.

would work better. GitHub would display that as

fresh

Multi-line description.

Another thing that would work is just having the Nix code in codeblocks in the README. It would look less nice but be fairly trivial to extract.

[BirdeeHub]

Is there any particular reason to do it in python? Any useful libraries for this?

Because im already halfway there in lua with cjson actually

I have name link description as a lua table in a script.

I was just gonna make them into a table somehow.

Know any python libraries that makes it super easy to generate markdown tables?

Give me like 30 mins ill just finish making this table as markdown, pandoc it to html and link it here.

Edit: maybe longer than 30 mins these newlines got hands.

Maybe ill try the other option rather than the markdown table

[BirdeeHub]

and yeah nixdoc doesnt work on this file unfortunately.

I use nixdoc to generate the utils file docs though!

[quarkQuark]

Is there any particular reason to do it in python? Any useful libraries for this?

Because im already halfway there in lua with cjson actually

Nah, any scripting language works. I'm not actually that great at Python, I just know enough to muddle through. I'm really a Haskell person.

Emacs does the hard bits. That is, it knows how to understand that table as an array. (And similar for the heading version). I suspect Python is actually overkill for then working with the array (if you're already using Emacs you can just do it in Emacs lisp, which is a language I hate but at least it's really well integrated). But it's useful as an option for more complicated manipulations.

Edit: maybe longer than 30 mins these newlines got hands.

I do not know this idiom. It has a good ring to it.

[BirdeeHub]

oh it means they are putting up a fight.

I had a plan. It was good. Unfortunately, it was bad.

I was going to use nix eval to get the values and parse the json

It was working great.

Unfortunately, you cant invoke nix inside a derivation...

Edit: oh wait... nvm I have another idea

[quarkQuark]

and yeah nixdoc doesnt work on this file unfortunately.

How come? Is it not possible to change the generated filename?

I use nixdoc to generate the utils file docs though!

You mean the ./utils/README.md, or somewhere in ./nixCatsHelp?

[BirdeeHub]

https://nixcats.org/TOC.html

the templates generated thing is not listed in the TOC yet cause I just made it and want to figure it out a little more first

[BirdeeHub]

ok well I have links.

Now I just need to choose an order for them I guess idk

But I wanna do that without listing them all out lol

[BirdeeHub]

awwww I rate limited myself...

Whelp, enough of that for tonight

[BirdeeHub]

How many times did I spam that? I have a token that should be fine haha

[BirdeeHub]

The sitegen repo is kinda next level custom stuff XD

I build the nixcats vimdocs into html using nixCats. It's some mad scientist stuff. You can change the sites colorscheme by changing the colorscheme haha

https://github.com/BirdeeHub/nixCats-doc

But the utils and module options docs are generated straight from the files, and soon the template one will be as well, and those just generate into markdown and then into html via pandoc

I haven't figured out how to generate those into vimdocs yet.

At some point I'm going to run the sitegen within the nixCats repo itself via GitHub action probably but that's a later project XD

[BirdeeHub]

I split the templates btw

[BirdeeHub]

For onlookers reading this, we now have https://nixcats.org/nixCats_templates.html !

[quarkQuark]

Looks good! Sorry I've been a bit busy to look at anything this week (and probably will be next week too).