Unverified Commit 0cb46743 authored by Alejandro Sánchez Medina's avatar Alejandro Sánchez Medina Committed by GitHub
Browse files

doc: autogenerate python interpreter table (#313408) 



* doc: autogenerate python interpreter table

This serves as a practical example on generating documentation by
inspection of the evaluated Nixpkgs tree.

Co-authored-by: default avatarValentin Gagarin <valentin.gagarin@tweag.io>
parent 3305b2b2

doc/default.nix

+9 −1
Original line number Diff line number Diff line
@@ -105,7 +105,15 @@ in pkgs.stdenv.mkDerivation { 
    ln -s ${optionsDoc.optionsJSON}/share/doc/nixos/options.json ./config-options.json

  '';



  buildPhase = ''

  buildPhase = let

    pythonInterpreterTable = pkgs.callPackage ./doc-support/python-interpreter-table.nix {};

    pythonSection = with lib.strings; replaceStrings

      [ "@python-interpreter-table@" ]

      [ pythonInterpreterTable ]

      (readFile ./languages-frameworks/python.section.md);

  in ''

    cp ${builtins.toFile "python.section.md" pythonSection} ./languages-frameworks/python.section.md



    cat \

      ./functions/library.md.in \

      ${lib-docs}/index.md \

doc/doc-support/python-interpreter-table.nix

0 → 100644
+63 −0
Original line number Diff line number Diff line 
# For debugging, run in this directory:

#     nix eval --impure --raw --expr 'import ./python-interpreter-table.nix {}'

{ pkgs ? (import ../.. { config = { }; overlays = []; }) }:

let

  lib = pkgs.lib;

  inherit (lib.attrsets) attrNames filterAttrs;

  inherit (lib.lists) elem filter map naturalSort reverseList;

  inherit (lib.strings) concatStringsSep;



  isPythonInterpreter = name:

    /* NB: Package names that don't follow the regular expression:

      - `python-cosmopolitan` is not part of `pkgs.pythonInterpreters`.

      - `_prebuilt` interpreters are used for bootstrapping internally.

      - `python3Minimal` contains python packages, left behind conservatively.

      - `rustpython` lacks `pythonVersion` and `implementation`.

    */

    (lib.strings.match "(pypy|python)([[:digit:]]*)" name) != null;



  interpreterName = pname:

    let

      cuteName = {

        cpython = "CPython";

        pypy = "PyPy";

      };

      interpreter = pkgs.${pname};

    in

    "${cuteName.${interpreter.implementation}} ${interpreter.pythonVersion}";



  interpreters = reverseList (naturalSort (

    filter isPythonInterpreter (attrNames pkgs.pythonInterpreters)

  ));



  aliases = pname:

    attrNames (

      filterAttrs (name: value:

        isPythonInterpreter name

        && name != pname

        && interpreterName name == interpreterName pname

      ) pkgs

    );



  result = map (pname: {

    inherit pname;

    aliases = aliases pname;

    interpreter = interpreterName pname;

  }) interpreters;



  toMarkdown = data:

    let

      line = package: ''

        | ${package.pname} | ${join ", " package.aliases or [ ]} | ${package.interpreter} |

      '';

    in

    join "" (map line data);



  join = lib.strings.concatStringsSep;



in

''

  | Package | Aliases | Interpeter |

  |---------|---------|------------|

  ${toMarkdown result}

''

doc/languages-frameworks/python.section.md

+1 −10
Original line number Diff line number Diff line
@@ -4,16 +4,7 @@ 


### Interpreters {#interpreters}



| Package    | Aliases         | Interpreter |

|------------|-----------------|-------------|

| python27   | python2, python | CPython 2.7 |

| python39   |                 | CPython 3.9 |

| python310  |                 | CPython 3.10 |

| python311  | python3         | CPython 3.11 |

| python312  |                 | CPython 3.12 |

| python313  |                 | CPython 3.13 |

| pypy27     | pypy2, pypy     | PyPy2.7 |

| pypy39     | pypy3           | PyPy 3.9 |

@python-interpreter-table@



The Nix expressions for the interpreters can be found in

`pkgs/development/interpreters/python`.