Commit df09c21f authored by pennae's avatar pennae Committed by pennae
Browse files

nixos/documentation: deprecate docbook option docs 

following the plan in https://github.com/NixOS/nixpkgs/pull/189318#discussion_r961764451

also adds an activation script to print the warning during activation
instead of during build, otherwise folks using the new CLI that hides
build logs by default might never see the warning.
parent 45a5c01a

nixos/doc/manual/default.nix

+1 −1
Original line number Diff line number Diff line
@@ -209,7 +209,7 @@ let 
in rec {

  inherit generatedSources;



  inherit (optionsDoc) optionsJSON optionsNix optionsDocBook;

  inherit (optionsDoc) optionsJSON optionsNix optionsDocBook optionsUsedDocbook;



  # Generate the NixOS manual.

  manualHTML = runCommand "nixos-manual-html"

nixos/doc/manual/from_md/release-notes/rl-2305.section.xml

+16 −0
Original line number Diff line number Diff line
@@ -416,6 +416,22 @@ 
          sudo and sources the environment variables.

        </para>

      </listitem>

      <listitem>

        <para>

          DocBook option documentation, which has been deprecated since

          22.11, will now cause a warning when documentation is built.

          Out-of-tree modules should migrate to using CommonMark

          documentation as outlined in

          <xref linkend="sec-option-declarations" /> to silence this

          warning.

        </para>

        <para>

          DocBook option documentation support will be removed in the

          next release and CommonMark will become the default. DocBook

          option documentation that has not been migrated until then

          will no longer render properly or cause errors.

        </para>

      </listitem>

      <listitem>

        <para>

          The <literal>dnsmasq</literal> service now takes configuration

nixos/doc/manual/release-notes/rl-2305.section.md

+4 −0
Original line number Diff line number Diff line
@@ -101,6 +101,10 @@ In addition to numerous new and upgraded packages, this release has the followin 


- `services.mastodon` gained a tootctl wrapped named `mastodon-tootctl` similar to `nextcloud-occ` which can be executed from any user and switches to the configured mastodon user with sudo and sources the environment variables.



- DocBook option documentation, which has been deprecated since 22.11, will now cause a warning when documentation is built. Out-of-tree modules should migrate to using CommonMark documentation as outlined in [](#sec-option-declarations) to silence this warning.



  DocBook option documentation support will be removed in the next release and CommonMark will become the default. DocBook option documentation that has not been migrated until then will no longer render properly or cause errors.



- The `dnsmasq` service now takes configuration via the

  `services.dnsmasq.settings` attribute set. The option

  `services.dnsmasq.extraConfig` will be deprecated when NixOS 22.11 reaches

nixos/lib/make-options-doc/default.nix

+10 −1
Original line number Diff line number Diff line
@@ -139,9 +139,10 @@ in rec { 
      dst=$out/share/doc/nixos

      mkdir -p $dst



      TOUCH_IF_DB=$dst/.used-docbook \

      python ${./mergeJSON.py} \

        ${lib.optionalString warningsAreErrors "--warnings-are-errors"} \

        ${lib.optionalString (! allowDocBook) "--error-on-docbook"} \

        ${if allowDocBook then "--warn-on-docbook" else "--error-on-docbook"} \

        ${lib.optionalString markdownByDefault "--markdown-by-default"} \

        $baseJSON $options \

        > $dst/options.json
@@ -153,6 +154,14 @@ in rec { 
      echo "file json-br $dst/options.json.br" >> $out/nix-support/hydra-build-products

    '';



  optionsUsedDocbook = pkgs.runCommand "options-used-docbook" {} ''

    if [ -e ${optionsJSON}/share/doc/nixos/.used-docbook ]; then

      echo 1

    else

      echo 0

    fi >"$out"

  '';



  # Convert options.json into an XML file.

  # The actual generation of the xml file is done in nix purely for the convenience

  # of not having to generate the xml some other way

nixos/lib/make-options-doc/mergeJSON.py

+26 −14
Original line number Diff line number Diff line
@@ -228,6 +228,7 @@ def convertMD(options: Dict[str, Any]) -> str: 
    return options



warningsAreErrors = False

warnOnDocbook = False

errorOnDocbook = False

markdownByDefault = False

optOffset = 0
@@ -235,7 +236,10 @@ for arg in sys.argv[1:]: 
    if arg == "--warnings-are-errors":

        optOffset += 1

        warningsAreErrors = True

    if arg == "--error-on-docbook":

    if arg == "--warn-on-docbook":

        optOffset += 1

        warnOnDocbook = True

    elif arg == "--error-on-docbook":

        optOffset += 1

        errorOnDocbook = True

    if arg == "--markdown-by-default":
@@ -278,26 +282,27 @@ def is_docbook(o, key): 
# check that every option has a description

hasWarnings = False

hasErrors = False

hasDocBookErrors = False

hasDocBook = False

for (k, v) in options.items():

    if errorOnDocbook:

    if warnOnDocbook or errorOnDocbook:

        kind = "error" if errorOnDocbook else "warning"

        if isinstance(v.value.get('description', {}), str):

            hasErrors = True

            hasDocBookErrors = True

            hasErrors |= errorOnDocbook

            hasDocBook = True

            print(

                f"\x1b[1;31merror: option {v.name} description uses DocBook\x1b[0m",

                f"\x1b[1;31m{kind}: option {v.name} description uses DocBook\x1b[0m",

                file=sys.stderr)

        elif is_docbook(v.value, 'defaultText'):

            hasErrors = True

            hasDocBookErrors = True

            hasErrors |= errorOnDocbook

            hasDocBook = True

            print(

                f"\x1b[1;31merror: option {v.name} default uses DocBook\x1b[0m",

                f"\x1b[1;31m{kind}: option {v.name} default uses DocBook\x1b[0m",

                file=sys.stderr)

        elif is_docbook(v.value, 'example'):

            hasErrors = True

            hasDocBookErrors = True

            hasErrors |= errorOnDocbook

            hasDocBook = True

            print(

                f"\x1b[1;31merror: option {v.name} example uses DocBook\x1b[0m",

                f"\x1b[1;31m{kind}: option {v.name} example uses DocBook\x1b[0m",

                file=sys.stderr)



    if v.value.get('description', None) is None:
@@ -310,10 +315,14 @@ for (k, v) in options.items(): 
            f"\x1b[1;31m{severity}: option {v.name} has no type. Please specify a valid type, see " +

            "https://nixos.org/manual/nixos/stable/index.html#sec-option-types\x1b[0m", file=sys.stderr)



if hasDocBookErrors:

if hasDocBook:

    (why, what) = (

        ("disallowed for in-tree modules", "contribution") if errorOnDocbook

        else ("deprecated for option documentation", "module")

    )

    print("Explanation: The documentation contains descriptions, examples, or defaults written in DocBook. " +

        "NixOS is in the process of migrating from DocBook to Markdown, and " +

        "DocBook is disallowed for in-tree modules. To change your contribution to "+

        f"DocBook is {why}. To change your {what} to "+

        "use Markdown, apply mdDoc and literalMD and use the *MD variants of option creation " +

        "functions where they are available. For example:\n" +

        "\n" +
@@ -326,6 +335,9 @@ if hasDocBookErrors: 
        "  example.package = mkPackageOptionMD pkgs \"your-package\" {};\n" +

        "  imports = [ (mkAliasOptionModuleMD [ \"example\" \"args\" ] [ \"example\" \"settings\" ]) ];",

        file = sys.stderr)

    with open(os.getenv('TOUCH_IF_DB'), 'x'):

        # just make sure it exists

        pass



if hasErrors:

    sys.exit(1)