commit f159a340ffc40399ad8fdf290aeae3705a02e19c · pyrox.dev/nixpkgs

+13 -9
doc/README.md
···

       159
       159
        
       In that case, please open an issue about the particular documentation convention and tag it with a "needs: documentation" label.

     

       160
       160
        
       

     

       161
       161
        
       - Put each sentence in its own line.

     

       162
       162
       -
         This makes reviewing documentation much easier, since GitHub's review system is based on lines.

     

       162
       162
       +
         This makes reviews and suggestions much easier, since GitHub's review system is based on lines.

     

       163
       163
       +
         It also helps identifying long sentences at a glance.

     

       163
       164
        
       

     

       164
       164
       -
       - Use the admonitions syntax for any callouts and examples (see [section above](#admonitions)).

     

       165
       165
       +
       - Use the [admonition syntax](#admonitions) for callouts and examples.

     

       165
       166
        
       

     

       166
       166
       -
       - If you provide an example involving Nix code, make your example into a fully-working package (something that can be passed to `pkgs.callPackage`).

     

       167
       167
       -
         This will help others quickly test that the example works, and will also make it easier if we start automatically testing all example code to make sure it works.

     

       168
       168
       -
         For example, instead of providing something like:

     

       167
       167
       +
       - Provide at least one example per function, and make examples self-contained.

     

       168
       168
       +
         This is easier to understand for beginners.

     

       169
       169
       +
         It also helps with testing that it actually works – especially once we introduce automation.

     

       169
       170
        
       

     

       170
       170
       -
         ```

     

       171
       171
       +
         Example code should be such that it can be passed to `pkgs.callPackage`.

     

       172
       172
       +
         Instead of something like:

     

       173
       173
       +
       

     

       174
       174
       +
         ```nix

     

       171
       175
        
         pkgs.dockerTools.buildLayeredImage {

     

       172
       176
        
           name = "hello";

     

       173
       177
        
           contents = [ pkgs.hello ];

     

       174
       178
        
         }

     

       175
       179
        
         ```

     

       176
       180
        
       

     

       177
       177
       -
         Provide something like:

     

       181
       181
       +
         Write something like:

     

       178
       182
        
       

     

       179
       179
       -
         ```

     

       183
       183
       +
         ```nix

     

       180
       184
        
         { dockerTools, hello }:

     

       181
       185
        
         dockerTools.buildLayeredImage {

     

       182
       186
        
           name = "hello";

     
···

       200
       204
        
       

     

       201
       205
        
         : Tag of the generated image.

     

       202
       206
        
       

     

       203
       203
       -
             _Default value:_ the output path's hash.

     

       207
       207
       +
           _Default value:_ the output path's hash.

     

       204
       208
        
       

     

       205
       209
        
         ```

     

       206
       210