@@ -114,6 +114,7 @@ $(OVSIDL_BUILT): ovsdb/ovsdb-idlc.in python/ovs/dirs.py
# ovsdb-doc
EXTRA_DIST += ovsdb/ovsdb-doc
+FLAKE8_PYFILES += ovsdb/ovsdb-doc
OVSDB_DOC = $(run_python) $(srcdir)/ovsdb/ovsdb-doc
ovsdb/ovsdb-doc: python/ovs/dirs.py
@@ -14,9 +14,7 @@
# See the License for the specific language governing permissions and
# limitations under the License.
-from datetime import date
import getopt
-import os
import sys
import xml.dom.minidom
@@ -24,10 +22,13 @@ import ovs.json
from ovs.db import error
import ovs.db.schema
-from ovs_build_helpers.nroff import *
+from ovs_build_helpers.nroff import block_xml_to_nroff
+from ovs_build_helpers.nroff import escape_nroff_literal
+from ovs_build_helpers.nroff import text_to_nroff
argv0 = sys.argv[0]
+
def typeAndConstraintsToNroff(column):
type = column.type.toEnglish(escape_nroff_literal)
constraints = column.type.constraintsToEnglish(escape_nroff_literal,
@@ -38,6 +39,7 @@ def typeAndConstraintsToNroff(column):
type += " (must be unique within table)"
return type
+
def columnGroupToNroff(table, groupXml, documented_columns):
introNodes = []
columnNodes = []
@@ -49,7 +51,10 @@ def columnGroupToNroff(table, groupXml, documented_columns):
if (columnNodes
and not (node.nodeType == node.TEXT_NODE
and node.data.isspace())):
- raise error.Error("text follows <column> or <group> inside <group>: %s" % node)
+ raise error.Error(
+ "text follows <column> or <group> inside <group>: %s"
+ % node
+ )
introNodes += [node]
summary = []
@@ -65,15 +70,9 @@ def columnGroupToNroff(table, groupXml, documented_columns):
if node.hasAttribute('type'):
type_string = node.attributes['type'].nodeValue
type_json = ovs.json.from_string(str(type_string))
- # py2 -> py3 means str -> bytes and unicode -> str
- try:
- if type(type_json) in (str, unicode):
- raise error.Error("%s %s:%s has invalid 'type': %s"
- % (table.name, name, key, type_json))
- except:
- if type(type_json) in (bytes, str):
- raise error.Error("%s %s:%s has invalid 'type': %s"
- % (table.name, name, key, type_json))
+ if type(type_json) in (bytes, str):
+ raise error.Error("%s %s:%s has invalid 'type': %s"
+ % (table.name, name, key, type_json))
type_ = ovs.db.types.BaseType.from_json(type_json)
else:
type_ = column.type.value
@@ -91,10 +90,11 @@ def columnGroupToNroff(table, groupXml, documented_columns):
else:
if type_.type != column.type.value.type:
type_english = type_.toEnglish()
+ typeNroff += ", containing "
if type_english[0] in 'aeiou':
- typeNroff += ", containing an %s" % type_english
+ typeNroff += "an %s" % type_english
else:
- typeNroff += ", containing a %s" % type_english
+ typeNroff += "a %s" % type_english
constraints = (
type_.constraintsToEnglish(escape_nroff_literal,
text_to_nroff))
@@ -121,6 +121,7 @@ def columnGroupToNroff(table, groupXml, documented_columns):
raise error.Error("unknown element %s in <table>" % node.tagName)
return summary, intro, body
+
def tableSummaryToNroff(summary, level=0):
s = ""
for type, name, arg in summary:
@@ -132,6 +133,7 @@ def tableSummaryToNroff(summary, level=0):
s += ".RE\n"
return s
+
def tableToNroff(schema, tableXml):
tableName = tableXml.attributes['name'].nodeValue
table = schema.tables[tableName]
@@ -156,20 +158,17 @@ def tableToNroff(schema, tableXml):
return s
+
def docsToNroff(schemaFile, xmlFile, erFile, version=None):
schema = ovs.db.schema.DbSchema.from_json(ovs.json.from_file(schemaFile))
doc = xml.dom.minidom.parse(xmlFile).documentElement
- schemaDate = os.stat(schemaFile).st_mtime
- xmlDate = os.stat(xmlFile).st_mtime
- d = date.fromtimestamp(max(schemaDate, xmlDate))
-
if doc.hasAttribute('name'):
manpage = doc.attributes['name'].nodeValue
else:
manpage = schema.name
- if version == None:
+ if version is None:
version = "UNKNOWN"
# Putting '\" p as the first line tells "man" that the manpage
@@ -194,7 +193,6 @@ def docsToNroff(schemaFile, xmlFile, erFile, version=None):
.PP
''' % (manpage, schema.version, version, text_to_nroff(manpage), schema.name)
- tables = ""
introNodes = []
tableNodes = []
summary = []
@@ -237,8 +235,8 @@ Purpose
""" % (name, text_to_nroff(title))
if erFile:
- s += """
-.\\" check if in troff mode (TTY)
+ s += r"""
+.\" check if in troff mode (TTY)
.if t \{
.bp
.SH "TABLE RELATIONSHIPS"
@@ -248,8 +246,8 @@ database. Each node represents a table. Tables that are part of the
``root set'' are shown with double borders. Each edge leads from the
table that contains it and points to the table that its value
represents. Edges are labeled with their column names, followed by a
-constraint on the number of allowed values: \\fB?\\fR for zero or one,
-\\fB*\\fR for zero or more, \\fB+\\fR for one or more. Thick lines
+constraint on the number of allowed values: \fB?\fR for zero or one,
+\fB*\fR for zero or more, \fB+\fR for one or more. Thick lines
represent strong references; thin lines represent weak references.
.RS -1in
"""
@@ -263,6 +261,7 @@ represent strong references; thin lines represent weak references.
s += tableToNroff(schema, node) + "\n"
return s
+
def usage():
print("""\
%(argv0)s: ovsdb schema documentation generator
@@ -278,6 +277,7 @@ The following options are also available:
""" % {'argv0': argv0})
sys.exit(0)
+
if __name__ == "__main__":
try:
try:
ovsdb-doc script generates the following syntax warning while running with Python 3.12: /ovsdb/ovsdb-doc:240: SyntaxWarning: invalid escape sequence '\{' s += """ This doesn't cause a build failure because so far it's only a warning, but it will become a syntax error in the future. Fix that by converting to a raw string and removing unnecessary escape sequences. Adding ovsdb-doc to flake8-check to avoid re-introducing issues in the future. This means also fixing all the other issues with the script like unused imports and variables, long lines, missing empty lines, wildcarded imports. Also cleaning up one place that handles compatibility with Python 2 types, since we do not support Python 2 for a long time now. Signed-off-by: Ilya Maximets <i.maximets@ovn.org> --- ovsdb/automake.mk | 1 + ovsdb/ovsdb-doc | 50 +++++++++++++++++++++++------------------------ 2 files changed, 26 insertions(+), 25 deletions(-)