colin/NetworkManager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: better handle description tags in generate-docs-nm-settings-docs-merge.py

Browse Source 
When we generate the manual page for nm-settings-nmcli, we run:

   "/usr/bin/python" \
        ./tools/generate-docs-nm-settings-docs-merge.py \
        --only-from-first \
        man/nm-settings-docs-nmcli.xml \
        src/nmcli/gen-metadata-nm-settings-nmcli.xml \
        src/libnm-client-impl/nm-property-infos-nmcli.xml \
        src/libnm-client-impl/nm-settings-docs-gir.xml

If "gen-metadata-nm-settings-nmcli.xml" contains either a <description>
or a <description-docbook>, then we must not continue searching the
other XML documents. The user provided an explicit override, and
fallback (search further) is wrong. Previously, we might take
<description> from the first file, and <description-docbook> from the
second file. As "man/nm-settings-nmcli.xsl" prefers
<description-docbook>, it takes the wrong text. Instead, as we search
the files during merge, we must prefer the first one.

Note that the change doesn't really matter anymore, because each XML
now must also contain both <description> and <description-docbook>.
There is an assertion for that.

Also, stop generating <deprecated-docbook>. First, it lacked the
important "since=" attribute and was necessary. Also, it's redundant and
does not contain anything interesting. So far, we don't need special
formatting for the deprecated message, and we likely never will.

Also, stop accepting or generating the "description=" attribute. This
should always be an XML element now.
This commit is contained in:
Thomas Haller
2023-05-17 12:19:34 +02:00
parent 89abede3df
commit 42aa225185
4 changed files with 70 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
tools/generate-docs-nm-settings-docs-gir.py
View File

@@ -328,12 +328,9 @@ def main(gir_path_str, output_path_str):
},
).text = deprecated_desc
deprecated_docbook = ET.SubElement(
property_element,
"deprecated-docbook",
)
create_desc_docbook(deprecated_docbook, deprecated_desc)
# The text should only be one line. Otherwise, our simple "<deprecated>" element
# cannot be rendered nicely.
assert re.split("\n", deprecated_desc) == [deprecated_desc]
docs_gir.write(
output_path_str,