Commit eebe71db authored by Jakub Kicinski's avatar Jakub Kicinski
Browse files

Merge branch 'doc-netlink-fixes-for-ynl-doc-generator' 

Donald Hunter says:

====================
doc: netlink: Fixes for ynl doc generator

Several fixes to ynl-gen-rst to resolve issues that can be seen
in:

https://docs.kernel.org/6.10-rc1/networking/netlink_spec/dpll.html#device-id-get
https://docs.kernel.org/6.10-rc1/networking/netlink_spec/dpll.html#lock-status

In patch 2, by not using 'sanitize' for op docs, any formatting in the
.yaml gets passed straight through to the generated .rst which means
that basic rst (also markdown compatible) list formatting can be used in
the .yaml
====================

Link: https://lore.kernel.org/r/20240528140652.9445-1-donald.hunter@gmail.com


Signed-off-by: default avatarJakub Kicinski <kuba@kernel.org>
parents 1e37449f 9104feed

Documentation/netlink/specs/dpll.yaml

+1 −0
Original line number Diff line number Diff line
@@ -479,6 +479,7 @@ operations: 
      name: pin-get

      doc: |

        Get list of pins and its attributes.



        - dump request without any attributes given - list all the pins in the

          system

        - dump request with target dpll - list all the pins registered with

tools/net/ynl/ynl-gen-rst.py

+9 −4
Original line number Diff line number Diff line
@@ -156,7 +156,10 @@ def parse_do(do_dict: Dict[str, Any], level: int = 0) -> str: 
    lines = []

    for key in do_dict.keys():

        lines.append(rst_paragraph(bold(key), level + 1))

        if key in ['request', 'reply']:

            lines.append(parse_do_attributes(do_dict[key], level + 1) + "\n")

        else:

            lines.append(headroom(level + 2) + do_dict[key] + "\n")



    return "\n".join(lines)
@@ -172,13 +175,13 @@ def parse_do_attributes(attrs: Dict[str, Any], level: int = 0) -> str: 


def parse_operations(operations: List[Dict[str, Any]], namespace: str) -> str:

    """Parse operations block"""

    preprocessed = ["name", "doc", "title", "do", "dump"]

    preprocessed = ["name", "doc", "title", "do", "dump", "flags"]

    linkable = ["fixed-header", "attribute-set"]

    lines = []



    for operation in operations:

        lines.append(rst_section(namespace, 'operation', operation["name"]))

        lines.append(rst_paragraph(sanitize(operation["doc"])) + "\n")

        lines.append(rst_paragraph(operation["doc"]) + "\n")



        for key in operation.keys():

            if key in preprocessed:
@@ -188,6 +191,8 @@ def parse_operations(operations: List[Dict[str, Any]], namespace: str) -> str: 
            if key in linkable:

                value = rst_ref(namespace, key, value)

            lines.append(rst_fields(key, value, 0))

        if 'flags' in operation:

            lines.append(rst_fields('flags', rst_list_inline(operation['flags'])))



        if "do" in operation:

            lines.append(rst_paragraph(":do:", 0))