Merge remote-tracking branch 'origin/master' into staging-next

Conflicts:
- pkgs/development/python-modules/pycdio/default.nix

2 files changed, 33 insertions, 20 deletions

diff --git a/doc/README.md b/doc/README.md
index 6f452f1ba744..d7a853d0ec35 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -251,25 +251,42 @@ You, as the writer of documentation, are still in charge of its content.
   For example:
 
   ```markdown
-  # pkgs.coolFunction
+  # pkgs.coolFunction {#pkgs.coolFunction}
 
-  Description of what `coolFunction` does.
+  `pkgs.coolFunction` *`name`* *`config`*
 
-  ## Inputs
+  Description of what `callPackage` does.
 
-  `coolFunction` expects a single argument which should be an attribute set, with the following possible attributes:
 
-  `name` (String)
+  ## Inputs {#pkgs-coolFunction-inputs}
+
+  If something's special about `coolFunction`'s general argument handling, you can say so here.
+  Otherwise, just describe the single argument or start the arguments' definition list without introduction.
+
+  *`name`* (String)
 
   : The name of the resulting image.
 
-  `tag` (String; _optional_)
+  *`config`* (Attribute set)
+
+  : Introduce the parameter. Maybe you have a test to make sure `{ }` is a sensible default; then you can say: these attributes are optional; `{ }` is a valid argument.
 
-  : Tag of the generated image.
+    `outputHash` (String; _optional_)
 
-    _Default:_ the output path's hash.
+    : A brief explanation including when and when not to pass this attribute.
+
+    : _Default:_ the output path's hash.
   ```
 
+  Checklist:
+  - Start with a synopsis, to show the order of positional arguments.
+  - Metavariables are in emphasized code spans: ``` *`arg1`* ```. Metavariables are placeholders where users may write arbitrary expressions. This includes positional arguments.
+  - Attribute names are regular code spans: ``` `attr1` ```. These identifiers can _not_ be picked freely by users, so they are _not_ metavariables.
+  - _optional_ attributes have a _`Default:`_ if it's easily described as a value.
+  - _optional_ attributes have a _`Default behavior:`_ if it's not easily described using a value.
+  - Nix types aren't in code spans, because they are not code
+  - Nix types are capitalized, to distinguish them from the camelCase [Module System](#module-system) types, which _are_ code and behave like functions.
+
 #### Examples
 
 To define a referenceable figure use the following fencing:
diff --git a/doc/languages-frameworks/python.section.md b/doc/languages-frameworks/python.section.md
index beca9545f284..8992d36fb25b 100644
--- a/doc/languages-frameworks/python.section.md
+++ b/doc/languages-frameworks/python.section.md
@@ -316,13 +316,7 @@ python3Packages.buildPythonApplication rec {
 }
 ```
 
-This is then added to `all-packages.nix` just as any other application would be.
-
-```nix
-{
-  luigi = callPackage ../applications/networking/cluster/luigi { };
-}
-```
+This is then added to `pkgs/by-name` just as any other application would be.
 
 Since the package is an application, a consumer doesn't need to care about
 Python versions or modules, which is why they don't go in `python3Packages`.
@@ -331,25 +325,27 @@ Python versions or modules, which is why they don't go in `python3Packages`.
 
 A distinction is made between applications and libraries, however, sometimes a
 package is used as both. In this case the package is added as a library to
-`python-packages.nix` and as an application to `all-packages.nix`. To reduce
+`python-packages.nix` and as an application to `pkgs/by-name`. To reduce
 duplication the `toPythonApplication` can be used to convert a library to an
 application.
 
 The Nix expression shall use [`buildPythonPackage`](#buildpythonpackage-function) and be called from
-`python-packages.nix`. A reference shall be created from `all-packages.nix` to
+`python-packages.nix`. A reference shall be created from `pkgs/by-name` to
 the attribute in `python-packages.nix`, and the `toPythonApplication` shall be
 applied to the reference:
 
 ```nix
 {
-  youtube-dl = with python3Packages; toPythonApplication youtube-dl;
-}
+  python3Packages,
+}:
+
+python3Packages.toPythonApplication python3Packages.youtube-dl
 ```
 
 #### `toPythonModule` function {#topythonmodule-function}
 
 In some cases, such as bindings, a package is created using
-[`stdenv.mkDerivation`](#sec-using-stdenv) and added as attribute in `all-packages.nix`. The Python
+[`stdenv.mkDerivation`](#sec-using-stdenv) and added as attribute in `pkgs/by-name` or in `all-packages.nix`. The Python
 bindings should be made available from `python-packages.nix`. The
 `toPythonModule` function takes a derivation and makes certain Python-specific
 modifications.