doc: begin work on new documentation #113
Conversation
nrdxp
force-pushed
the
doc
branch
6 times, most recently
from
4fee78f to
100dc40
Compare
|
Congrats! This is getting very nice! I'm considering adding paperback support soonish to nixpkgs (for purely nostalgic reasons) 😉 It might be slightly advantageous to put layout markdown files directly alongside the respectifv nix files within the folder layout. This way, the md doc is directly available next to the relevant files (for example also for browsing git). It is possible to put book.toml on the top level and then do: [book]
src = "."... and then just reference the files normaly from root. → the quickstart, parts of the readme content, etc obviously could continue to live in the Another advantage is that it would get very straight forward for users to expand with their own documentation, for example for a specific profiles, etc. (Taking the sharing aspect to the next level). Just my 2 cents. 👍 |
|
I've read through the entire thing and it looks really great! I think it is very clear and easy to understand.
I would personally prefer this. It would be simpler and easy to contribute to. But I could see it being harder for you to maintain. |
|
Sounds like a good idea. Still have a lot of work to do here, so I'll give it a shot and see how it goes. |
nrdxp
force-pushed
the
doc
branch
2 times, most recently
from
da77533 to
6751c09
Compare
|
force pushed, with layout section done, and everything squashed into a single commit. |
Users may wish to change the default value of override and nixos inputs. If they do so, we want the registry listing to reflect the proper ref names afterwards. Also create a shell alias to easily search every flake in nix.registry.
|
I'm gonna go ahead and push this to core even though all the goals from #111 have not been reached. What we have so far will be immensely helpful for new users, and I'd like to get it in front of them right away. We will finish the issue with an additional PR in the future. |
The scope of this PR has been reduced, and doesn't complete #111, but only partially implements it.
Essentially, each subdirectory will contain it's own README.md file explaining the purpose and usage of said directory. In additional,all of the md files will be compiled together in an mdbook which willbe rendered and hosted on github pages.
The rendered mdbook can be viewed on my website. https://nrdxp.dev/nixflk