[master] e7c0497 Improve the RST output.
Poul-Henning Kamp
phk at FreeBSD.org
Wed Feb 28 14:57:08 UTC 2018
commit e7c0497404a5b4aadda71aead3b0e7fe946d6993
Author: Poul-Henning Kamp <phk at FreeBSD.org>
Date: Wed Feb 28 14:44:39 2018 +0000
Improve the RST output.
I came for something else, but one thing led to another...
Emit a proper summary at the top, but elide ENUMs to keep it
compact.
If the entire VCL prototype fits in the header, put it there.
else if it fits with ENUMs elided do that or finally resort
to just the name + "(...)".
If the header didn't hold the full prototype, emit a codeblock
with it, and split that in one line per argument if it is too
wide for the manual pages.
Remove the manual summary from the libvmod_blob docs.
otherwise summarize it (ie: elide ENUMs)
diff --git a/lib/libvcc/vmodtool.py b/lib/libvcc/vmodtool.py
index 86fcdad..fca5b03 100755
--- a/lib/libvcc/vmodtool.py
+++ b/lib/libvcc/vmodtool.py
@@ -45,7 +45,6 @@ import random
import copy
import json
-rstfmt = False
strict_abi = True
AMBOILERPLATE = '''
@@ -226,7 +225,12 @@ class ctype(object):
return "STRING"
if self.spec is None:
return self.vt
- return self.vt + " {" + ",".join(self.spec) + "}"
+ return self.vt + " {" + ", ".join(self.spec) + "}"
+
+ def synopsis(self):
+ if self.vt == "STRING_LIST":
+ return "STRING"
+ return self.vt
def json(self, jl):
jl.append([self.vt, self.nm, self.defval, self.spec])
@@ -308,15 +312,8 @@ def nmlegal(nm):
class prototype(object):
def __init__(self, st, retval=True, prefix=""):
self.st = st
+ self.obj = None
ll = st.line[1]
- while True:
- a1 = ll.count("(")
- a2 = ll.count(")")
- if a1 > 0 and a1 == a2:
- break
- n = st.doc.split("\n", 1)
- ll += n[0]
- st.doc = n[1]
if retval:
self.retval, s = vtype(ll)
@@ -325,7 +322,9 @@ class prototype(object):
s = ll
i = s.find("(")
assert i > 0
- self.name = prefix + s[:i].strip()
+ self.prefix = prefix
+ self.bname = s[:i].strip()
+ self.name = self.prefix + self.bname
self.vcc = st.vcc
if not nmlegal(self.cname()):
err("%s(): Illegal name\n" % self.name, warn=False)
@@ -358,14 +357,25 @@ class prototype(object):
return self.vcc.sympfx + r
return r
- def vcl_proto(self, short):
- s = ""
- if self.retval is not None and type(self.st) != s_object:
+ def vcl_proto(self, short, pfx=""):
+ if type(self.st) == s_method:
+ pfx += pfx
+ s = pfx
+ if type(self.st) == s_object:
+ s += "new x" + self.bname + " = "
+ elif self.retval is not None:
s += self.retval.vcl() + " "
- s += self.name + "("
+
+ if type(self.st) == s_method:
+ s += self.obj + self.bname + "("
+ else:
+ s += self.name + "("
ll = []
for i in self.args:
- t = i.vcl()
+ if short:
+ t = i.synopsis()
+ else:
+ t = i.vcl()
if t in privs:
continue
if not short:
@@ -374,9 +384,30 @@ class prototype(object):
if i.defval is not None:
t += "=" + i.defval
ll.append(t)
- s += ", ".join(ll) + ")"
+ t = ",@".join(ll)
+ if len(s + t) > 68 and not short:
+ s += "\n" + pfx + pfx
+ s += t.replace("@", "\n" + pfx + pfx)
+ s += "\n" + pfx + ")"
+ else:
+ s += t.replace("@", " ") + ")"
return s
+ def rsthead(self, fo):
+ s = self.vcl_proto(False)
+ if len(s) < 60:
+ write_rst_hdr(fo, s, '-')
+ else:
+ s = self.vcl_proto(True)
+ if len(s) > 60:
+ s = self.name + "(...)"
+ write_rst_hdr(fo, s, '-')
+ fo.write("\n::\n\n" + self.vcl_proto(False, pfx=" ") + "\n")
+
+ def synopsis(self, fo, man):
+ fo.write(self.vcl_proto(True, pfx=" ") + "\n")
+ fo.write(" \n")
+
def c_ret(self):
return self.retval.ct
@@ -400,7 +431,7 @@ class prototype(object):
self.retval.json(ll)
ll.append(cfunc)
for i in self.args:
- i.json(ll)
+ i.json(ll)
jl.append(ll)
#######################################################################
@@ -409,10 +440,11 @@ class prototype(object):
class stanza(object):
def __init__(self, l0, doc, vcc):
self.line = l0
- if len(doc) == 1:
- self.doc = doc[0]
- else:
- self.doc = ""
+ while len(doc) > 0 and doc[0] == '':
+ doc.pop(0)
+ while len(doc) > 0 and doc[-1] == '':
+ doc.pop(-1)
+ self.doc = doc
self.vcc = vcc
self.rstlbl = None
self.methods = None
@@ -427,26 +459,27 @@ class stanza(object):
fo.write(".. _" + self.rstlbl + ":\n\n")
self.rsthead(fo, man)
+ fo.write("\n")
self.rstmid(fo, man)
+ fo.write("\n")
self.rsttail(fo, man)
+ fo.write("\n")
def rsthead(self, fo, man):
if self.proto is None:
return
- if rstfmt:
- s = self.proto.vcl_proto(short=False)
- write_rst_hdr(fo, s, '-')
- else:
- write_rst_hdr(fo, self.proto.name, '-')
- s = self.proto.vcl_proto(short=False)
- fo.write("\n::\n\n\t%s\n" % s)
+ self.proto.rsthead(fo)
def rstmid(self, fo, man):
- fo.write(self.doc + "\n")
+ fo.write("\n".join(self.doc) + "\n")
def rsttail(self, fo, man):
return
+ def synopsis(self, fo, man):
+ if self.proto is not None:
+ self.proto.synopsis(fo, man)
+
def hfile(self, fo):
return
@@ -487,22 +520,21 @@ class s_module(stanza):
fo.write("\n")
write_rst_hdr(fo, "SYNOPSIS", "=")
fo.write("\n")
- fo.write('import %s [from "path"] ;\n' % self.vcc.modname)
+ fo.write("\n::\n\n")
+ fo.write(' import %s [from "path"] ;\n' % self.vcc.modname)
+ fo.write(" \n")
+ for c in self.vcc.contents:
+ c.synopsis(fo, man)
fo.write("\n")
def rsttail(self, fo, man):
- write_rst_hdr(fo, "CONTENTS", "=")
- fo.write("\n")
-
if man:
- for i in self.vcc.contents[1:]:
- if i.rstlbl is None:
- continue
- fo.write("* %s\n" % i.proto.vcl_proto(short=True))
- fo.write("\n")
return
+ write_rst_hdr(fo, "CONTENTS", "=")
+ fo.write("\n")
+
ll = []
for i in self.vcc.contents[1:]:
j = i.rstlbl
@@ -593,6 +625,7 @@ class s_object(stanza):
def parse(self):
self.proto = prototype(self, retval=False)
self.proto.retval = vtype('VOID')[0]
+ self.proto.obj = "x" + self.proto.name
self.init = copy.copy(self.proto)
self.init.name += '__init'
@@ -606,15 +639,9 @@ class s_object(stanza):
self.methods = []
def rsthead(self, fo, man):
- if rstfmt:
- s = self.proto.vcl_proto(short=False)
- write_rst_hdr(fo, "new OBJ = " + s, '=')
- else:
- write_rst_hdr(fo, self.proto.name, '-')
- s = "new OBJ = " + self.proto.vcl_proto(short=False)
- fo.write("\n::\n\n\t%s\n" % s)
+ self.proto.rsthead(fo)
- fo.write(self.doc + "\n")
+ fo.write("\n" + "\n".join(self.doc) + "\n\n")
for i in self.methods:
i.rstfile(fo, man)
@@ -622,6 +649,11 @@ class s_object(stanza):
def rstmid(self, fo, man):
return
+ def synopsis(self, fo, man):
+ self.proto.synopsis(fo, man)
+ for i in self.methods:
+ i.proto.synopsis(fo, man)
+
def chfile(self, fo, h):
sn = self.vcc.sympfx + self.vcc.modname + "_" + self.proto.name
fo.write("struct %s;\n" % sn)
@@ -688,6 +720,7 @@ class s_method(stanza):
assert type(p) == s_object
self.pfx = p.proto.name
self.proto = prototype(self, prefix=self.pfx)
+ self.proto.obj = "x" + self.pfx
self.rstlbl = "func_" + self.proto.name
p.methods.append(self)
@@ -742,16 +775,18 @@ class vcc(object):
a = "\n" + open(self.inputfile, "r").read()
s = a.split("\n$")
self.copyright = s.pop(0).strip()
- for i in range(len(s)):
- b = s[i].split("\n", 1)
- c = b[0].split(None, 1)
-
- if i == 0 and c[0] != "Module":
- err("$Module must be first stanze", False)
+ while len(s):
+ ss = s.pop(0)
+ i = ss.find("\n\n")
+ if i > -1:
+ i += 1
+ else:
+ i = len(ss)
+ c = ss[:i].split()
m = dispatch.get(c[0])
if m is None:
- err("Unknown stanze $%s" % c[0])
- m(c, b[1:], self)
+ err("Unknown stanze $%s" % ss[:i])
+ m([c[0], " ".join(c[1:])], ss[i:].split('\n'), self)
def rst_copyright(self, fo):
write_rst_hdr(fo, "COPYRIGHT", "=")
diff --git a/lib/libvmod_blob/vmod.vcc b/lib/libvmod_blob/vmod.vcc
index a462f3a..341f3fe 100644
--- a/lib/libvmod_blob/vmod.vcc
+++ b/lib/libvmod_blob/vmod.vcc
@@ -8,25 +8,6 @@
$Module blob 3 utilities for the VCL blob type
-::
-
- # binary-to-text encodings
- STRING blob.encode([ENUM encoding,] [ENUM case,] BLOB blob)
- BLOB blob.decode([ENUM decoding,] [INT length,] STRING_LIST encoded)
- STRING blob.transcode([ENUM decoding,] [ENUM encoding,] [ENUM case,]
- [INT length,] STRING_LIST encoded)
-
- # other utilities
- BOOL blob.same(BLOB, BLOB)
- BOOL blob.equal(BLOB, BLOB)
- INT blob.length(BLOB)
- BLOB blob.sub(BLOB, BYTES length [, BYTES offset])
-
- # blob object
- new OBJ = blob.blob([ENUM decoding,] STRING_LIST encoded)
- BLOB <obj>.get()
- STRING <obj>.encode([ENUM encoding,] [ENUM case])
-
$ABI strict
DESCRIPTION
More information about the varnish-commit
mailing list