Unverified Commit 638ff75e authored by Valentin Gagarin's avatar Valentin Gagarin Committed by GitHub
Browse files

lib.literalExpression: tag generated code blocks with `nix`, add usage example... 

lib.literalExpression: tag generated code blocks with `nix`, add usage example and describe function arg; lib.literalCode: init (#467878)
parents 53b399a1 56cee4ff

lib/options.nix

+63 −1
Original line number Diff line number Diff line
@@ -672,11 +672,30 @@ rec { 
    is necessary for complex values, e.g. functions, or values that depend on

    other values or packages.



    # Examples

    :::{.example}

    ## `literalExpression` usage example



    ```nix

    llvmPackages = mkOption {

      type = types.str;

      description = ''

        Version of llvm packages to use for

        this module

      '';

      example = literalExpression ''

        llvmPackages = pkgs.llvmPackages_20;

      '';

    };

    ```



    :::



    # Inputs



    `text`



    : 1\. Function argument

    : The text to render as a Nix expression

  */

  literalExpression =

    text:
@@ -688,6 +707,49 @@ rec { 
        inherit text;

      };



  /**

    For use in the `defaultText` and `example` option attributes. Causes the

    given string to be rendered verbatim in the documentation as a code

    block with the language bassed on the provided input tag.



    If you wish to render Nix code, please see `literalExpression`.



    # Examples

    :::{.example}

    ## `literalCode` usage example



    ```nix

    myPythonScript = mkOption {

      type = types.str;

      description = ''

        Example python script used by a module

      '';

      example = literalCode "python" ''

        print("Hello world!")

      '';

    };

    ```



    :::



    # Inputs



    `languageTag`



    : The language tag to use when producing the code block (i.e. `js`, `rs`, etc).



    `text`



    : The text to render as a Nix expression

  */

  literalCode =

    languageTag: text:

    lib.literalMD ''

      ```${languageTag}

      ${text}

      ```

    '';



  /**

    For use in the `defaultText` and `example` option attributes. Causes the

    given MD text to be inserted verbatim in the documentation, for when

pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/options.py

+1 −1
Original line number Diff line number Diff line
@@ -97,7 +97,7 @@ class BaseConverter(Converter[md.TR], Generic[md.TR]): 
        if lit := option_is(option, key, 'literalMD'):

            return [ self._render(f"*{key.capitalize()}:*\n{lit['text']}") ]

        elif lit := option_is(option, key, 'literalExpression'):

            code = md_make_code(lit['text'])

            code = md_make_code(lit['text'], info="nix")

            return [ self._render(f"*{key.capitalize()}:*\n{code}") ]

        elif key in option:

            raise Exception(f"{key} has unrecognized type", option[key])