Can we auto-format the documentation / docbook XML?

Development
1

Hey so I’ve been looking in to auto-formatting the docs and … well, what do you think? Here is an excerpt:

-</para>
-
-<para>For configuring a gateway, optionally with explicitly specified interface:
-
+ </para>
+ <para>
+  For configuring a gateway, optionally with explicitly specified interface:
 <programlisting>
 networking.defaultGateway6 = {
   address = "fe00::1";
   interface = "enp0s3";
 }
 </programlisting>
-</para>
-
-<para>See <xref linkend='sec-ipv4' /> for similar examples and additional information.
-</para>
-
+ </para>
+ <para>
+  See <xref linkend='sec-ipv4' /> for similar examples and additional
+  information.
+ </para>
 </section>

It correctly handles programlisting, seems to do a nice job on wrapping appropriately, and has good defaults around what elements are inline.

Obviously I’d want to “backport” the change (by running the formatter on 18.03, not actually the commits.)

Thoughts?

1 Like
2

Here are some other examples:

-
-    </para></listitem>
-
-    <listitem><para>For creating swap partitions:
-    <command>mkswap</command>.  Again it&#x2019;s recommended to assign a
-    label to the swap partition: <option>-L
-    <replaceable>label</replaceable></option>. For example:
-
+        </para>
+       </listitem>
+       <listitem>
+        <para>
+         For creating swap partitions: <command>mkswap</command>. Again
+         it&#x2019;s recommended to assign a label to the swap partition:
+         <option>-L <replaceable>label</replaceable></option>. For example:

-
-  </para></listitem>
-
-  <listitem>
-    <variablelist>
-      <varlistentry><term>UEFI systems</term>
-      <listitem><para>Mount the boot file system on <filename>/mnt/boot</filename>, e.g.
-
+     </para>
+    </listitem>
+    <listitem>
+     <variablelist>
+      <varlistentry>
+       <term>UEFI systems</term>
+       <listitem>
+        <para>
+         Mount the boot file system on <filename>/mnt/boot</filename>, e.g.
3

See also: WIP: automagically format the docs by grahamc · Pull Request #39700 · NixOS/nixpkgs · GitHub

4

:+1: What tool are you using to format the docs?

It would be cool to have docfmt (whatever that is) in the nix-shell environment when working on the docs.

1 Like
5

Here is the how: nixpkgs doc: add format Make target by grahamc · Pull Request #39786 · NixOS/nixpkgs · GitHub

6

Apparently yes we can, and (for those who saw the firsts title ;)) basically no bikeshedding: WIP: automagically format the docs by grahamc · Pull Request #39700 · NixOS/nixpkgs · GitHub

3 Likes