[Nix-dev] User-oriented nixpkgs documentation (was: ioquake3 on nixos)

[Mateusz Czaplinski]

The Go language toolkit has the nice approach, similar as in doxygen
or javadoc, based on theory that if documentation is close to code, it
will be easier to keep it correct. I believe it is working great. It
would be nice if a similar tool was created for Nix, making it easy to
automatically extract comments from Nix files/expressions into an easy
to read and navigate document/website. Then, I'd suppose the OP's
question would become moot, as the answer would be obvious - to put
explanations in comments in derivation code. The added benefit would
be that to read the docs for basic functions (like lib.extend), one
wouldn't have to grep & browse through the sources.

/Mateusz.

On Fri, Jun 17, 2016 at 3:34 PM, Daniel Hlynskyi <abcz2.uprola at gmail.com> wrote:
> Write a blog post. Though it is hard to maintain blog post content over
> time, ask yourself "how long am I able to maintain this knowledge? Who
> should be responsible for verifying this manual in with future changes?"
>
> People expect manuals to be consistent with software. Every time I find
> errors in docs, I am step away from using it. From this perspective
> blogposts and wiki are better place to contribute unmaintained knowledge -
> we don't expect them to be always correct.
>
> Make tags, so google can find your article with "quake nix".
>
> Just IMO, but critique accepted.
>
> 8 квіт. 2016 1:36 пп, користувач "Nikolay Amiantov" <ab at fmap.me> написав:
>
>> Hi,
>>
>> I want to add some documentation on how to use our ioquake3 derivation.
>> This brings me to question on _where_ should I actually add it. Right
>> now we have:
>>
>> 1. Nix manual: completely unrelated to my topic;
>> 2. NixOS manual: primarily describes services and not packages and is
>> NixOS-oriented, while my article can be of interest to Quake-playing Nix
>> users in general;
>> 3. nixpkgs manual: oriented at developers and packagers (as it itself
>> points out).
>>
>> I would have added my article to the wiki, but AFAIK it's generally
>> decided to get rid of it. So, where should I place articles like this? I
>> would describe the general class of such documentation as "user-oriented
>> nixpkgs manual".
>>
>> I have some other documentation articles in mind that I would like to
>> write later (e.g. on steam-run), which go to the same category (I don't
>> mean "games" ^_^).
>>
>> On 04/08/2016 12:28 PM, Nikolay Amiantov wrote:
>> > I play ioquake3 successfully. It needs the following to work:
>> >
>> > 1. Extract pak0.pk3 file from the original Quake 3 Arena.
>> > 2. Use Nix script like this:
>> >
>> > { nixpkgs ? import <nixpkgs> { } }:
>> >
>> > let
>> >   paks = nixpkgs.stdenv.mkDerivation {
>> >     name = "quake3-arena";
>> >     pak0 = ./baseq3/pak0.pk3; # Replace this with path to your file
>> >     buildCommand = ''
>> >       install -D -m644 $pak0 $out/baseq3/pak0.pk3;
>> >     '';
>> >   };
>> > in nixpkgs.quake3wrapper {
>> >   paks = [ paks nixpkgs.quake3pointrelease ];
>> > }
>> >
>> > 3. Run `nix-build` on it: `nix-build script.nix`
>> > 4. `result/bin/quake3` would run the game.
>> >
>> > This probably needs to be added to our manual and/or improved somehow.
>>
>> --
>> Nikolay.
>> _______________________________________________
>> nix-dev mailing list
>> nix-dev at lists.science.uu.nl
>> http://lists.science.uu.nl/mailman/listinfo/nix-dev
>
>
> _______________________________________________
> nix-dev mailing list
> nix-dev at lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev
>