Copied: qpid/dispatch/trunk/doc/man/help2rst.py (from r1665924, qpid/dispatch/trunk/doc/man/help2md.py) URL: http://svn.apache.org/viewvc/qpid/dispatch/trunk/doc/man/help2rst.py?p2=qpid/dispatch/trunk/doc/man/help2rst.py&p1=qpid/dispatch/trunk/doc/man/help2md.py&r1=1665924&r2=1665993&rev=1665993&view=diff ============================================================================== --- qpid/dispatch/trunk/doc/man/help2md.py (original) +++ qpid/dispatch/trunk/doc/man/help2rst.py Wed Mar 11 20:25:45 2015 @@ -18,19 +18,14 @@ # """ -Generate markdown man pages by combining a markdown document with the -the --help output of the program. - -Extract the options section of help output and convert to markdown format for -inclusion in a man page. Replace the # Options section of the source document -or append it at the end if there is no # Options section. +Convett --help output of a program into rst text format. """ import re, sys from qpid_dispatch_internal.compat.subproc import check_output, STDOUT, CalledProcessError from os import path -def help2md(help_out): +def help2rst(help_out): VALUE = r"(?:[\w-]+|<[^>]+>)" DEFAULT = r"(?: +\([^)]+\))?" OPTION = r"-[\w-]+(?:[ =]%s)?%s" % (VALUE, DEFAULT) # -opt[(=| )value][(default)] @@ -43,24 +38,20 @@ def help2md(help_out): if (options): help_out = help_out[options.end():] result = "" - result += "# Options\n\n" + def heading(text, underline): + return "%s\n%s\n\n" % (text, underline*len(text)) + for item in re.finditer(r"%s|%s" % (OPT_HELP, SUBHEAD), help_out, re.IGNORECASE | re.MULTILINE): if item.group(3): - result += "## %s\n\n" % item.group(3).strip() # Sub-heading + result += heading(item.group(3).strip(), "~") else: result += "%s\n: %s\n\n" % (item.group(1), re.sub("\s+", " ", item.group(2)).strip()) return result -usage = "Usage: %s manpage_in.md manpage_out.md program [help-args...]" - def main(argv): - if len(argv) < 4: raise ValueError("Wrong number of arguments: "+usage) - source, target, program = argv[1], argv[2], argv[3:] - source_md = open(source).read() - options_md = help2md(check_output(program, stderr=STDOUT)) - combine_md = re.sub(r"\n# Options.*?(?=(\n# |$))(?ims)", options_md, source_md) - upcase_md = re.sub(r"^#+ .*$(?m)", lambda m: m.group(0).upper(), combine_md) - open(target, "w").write(upcase_md) + if len(argv) < 2: raise ValueError("Wrong number of arguments: "+usage) + program = argv[1:] + print help2rst(check_output(program, stderr=STDOUT)) if __name__ == "__main__": try: @@ -69,4 +60,3 @@ if __name__ == "__main__": if hasattr(e, "output") and e.output: print "\n%s\n\n%s\n" % (e, e.output) raise -
Added: qpid/dispatch/trunk/doc/man/qdmanage.rst.in URL: http://svn.apache.org/viewvc/qpid/dispatch/trunk/doc/man/qdmanage.rst.in?rev=1665993&view=auto ============================================================================== --- qpid/dispatch/trunk/doc/man/qdmanage.rst.in (added) +++ qpid/dispatch/trunk/doc/man/qdmanage.rst.in Wed Mar 11 20:25:45 2015 @@ -0,0 +1,143 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License + +:orphan: + +qdmanage manual page +==================== + +Synopsis +-------- + +qdmanage *operation* [*options...*] [*arguments...*] + +Description +----------- + +An AMQP management client for use with qdrouterd. Sends AMQP management +operations requests and prints the response in JSON format. This is a +generic AMQP management tool and can be used with any standard AMQP +managed endpoint, not just with qdrouter. + +Operations +---------- + +`query` [*ATTR*...] + Print the attributes named in the ATTR list or all attributes if + none are listed. Print attributes for all entities by default, use + --type, --name and --identity options to restrict what is printed. + +`create` [*ATTR=VALUE*...] + Create a new entity with the specified attributes. With the --stdin + option, read attributes from stdin. This can be a JSON map of + attributes to create a single entity, or a JSON list of maps to + create multiple entitiees. + +`read` + Print the attributes of an entity specified by the --name or + --identity options. With the --stdin option, create entities based + on data from stdin. This can be a JSON map of attributes to create a + single entity, or a JSON list of maps to create multiple entitiees. + +`update` [*ATTR=VALUE*...] + Update the attributes of an existing entity. With the --stdin + option, read attributes from stdin. This can be a JSON map of + attributes to update a single entity, or a JSON list of maps to + update multiple entitiees. If an ATTR name is listed with no =VALUE, + that attribute will be deleted from the entity. + +`delete` + Delete an entity specified by the --name or --identity options. + +`get-types` [*TYPE*] + List entity types with their base types. With no arguments list all + types. + +`get-operations` [*TYPE*] + List entity types with their operations. With no arguments list all + types. + +`get-attributes` [*TYPE*] + List entity types with their attributes. With no arguments list all + types. + +`get-annotations` [*TYPE*] + List entity types with their annotations. With no arguments list all + types. + +`get-mgmt-nodes` + List all other known management nodes connected to this one. + +`get-json-schema` [*INDENT*] + Get the router schema in JSON format. Optional integer indent for + formatted output. + +`get-log` [*INDENT*] + Get recent log entries from the router. + +Options +------- + +.. include:: qdmanage_help.rst + +Files +----- + +${CMAKE_INSTALL_PREFIX}/${QD_DOC_INSTALL_DIR}/qdrouter.json + Management schema for qdrouterd. + +${CMAKE_INSTALL_PREFIX}/${QD_DOC_INSTALL_DIR}/qdrouter.json.readme.txt + Explanation of the management schema. + +Examples +-------- + +Show the logging configuration + +:: + + qdmanage query --type=log + +Enable debug and higher log messages by default: + +:: + + qdmanage udpdate name=log/DEFAULT enable=debug+ + +Enable trace log messages only for the MESSAGE moudle and direct MESSAGE +logs to the file "test.log" + +:: + + qdmanage udpdate name=log/MESSAGE enable=trace output=test.log + +Set MESSAGE logging back to the default: + +:: + + qdmanage udpdate name=log/MESSAGE enable=default + +Disable MESSAGE logging: + +:: + + qdmanage udpdate name=log/MESSAGE enable=none + +See also +-------- + +*qdrouterd(8)*, *qdstat(8)*, *qdrouterd.conf(5)* + +http://qpid.apache.org/components/dispatch-router Added: qpid/dispatch/trunk/doc/man/qdrouterd.rst.in URL: http://svn.apache.org/viewvc/qpid/dispatch/trunk/doc/man/qdrouterd.rst.in?rev=1665993&view=auto ============================================================================== --- qpid/dispatch/trunk/doc/man/qdrouterd.rst.in (added) +++ qpid/dispatch/trunk/doc/man/qdrouterd.rst.in Wed Mar 11 20:25:45 2015 @@ -0,0 +1,49 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License + +:orphan: + +qdrouterd manual page +===================== + +SYNOPSIS +-------- + +qdrouterd [*options*] + +DESCRIPTION +----------- + +The Qpid Dispatch router (qdrouterd) is a network daemon that directs +AMQP 1.0 messages between endpoints, such as messaging clients and +servers. + +OPTIONS +------- + +.. include:: qdrouterd_help.rst + +FILES +----- + +${SYSCONF_INSTALL_DIR}/qdrouterd.conf + Configuration flie. + +SEE ALSO +-------- + +*qdrouterd.conf(5)*, *qdstat(8)*, *qdmanage(8)* + +http://qpid.apache.org/components/dispatch-router Modified: qpid/dispatch/trunk/doc/man/qdrouterd_conf_man.py URL: http://svn.apache.org/viewvc/qpid/dispatch/trunk/doc/man/qdrouterd_conf_man.py?rev=1665993&r1=1665992&r2=1665993&view=diff ============================================================================== --- qpid/dispatch/trunk/doc/man/qdrouterd_conf_man.py (original) +++ qpid/dispatch/trunk/doc/man/qdrouterd_conf_man.py Wed Mar 11 20:25:45 2015 @@ -27,8 +27,8 @@ from qpid_dispatch_internal.management.s class ManPageWriter(SchemaWriter): - def __init__(self, filename): - super(ManPageWriter, self).__init__(open(filename, 'w'), QdSchema()) + def __init__(self): + super(ManPageWriter, self).__init__(sys.stdout, QdSchema()) def attribute_type(self, attr, holder): # Don't show read-only attributes @@ -37,14 +37,23 @@ class ManPageWriter(SchemaWriter): def man_page(self): self.writeln(r""" -# Name +:orphan: -qdrouterd.conf - Configuration file for the Qpid Dispatch router +qdrouterd.conf manual page +========================== -# Description +Synopsis +-------- + +qdroutered.conf is the configuration file for the dispatch router. + +Description +----------- The configuration file is made up of sections with this syntax: +:: + SECTION-NAME { ATTRIBUTE-NAME: ATTRIBUTE-VALUE ATTRIBUTE-NAME: ATTRIBUTE-VALUE @@ -64,6 +73,8 @@ that can be included in multiple "listen how the 'ssl-profile' attribute of 'listener' sections references the 'name' attribute of 'ssl-profile' sections. +:: + ssl-profile { name: ssl-profile-one cert-db: ca-certificate-1.pem @@ -100,5 +111,14 @@ attribute of 'ssl-profile' sections. for a in entity_type.annotations: self.attribute_types(a) self.attribute_types(entity_type) + self.writeln(""" +See also +-------- + +*qdrouterd(8)*, *qdmanage(8)* + +http://qpid.apache.org/components/dispatch-router + """) + if __name__ == '__main__': - ManPageWriter(sys.argv[1]).man_page() + ManPageWriter().man_page() Added: qpid/dispatch/trunk/doc/man/qdstat.rst URL: http://svn.apache.org/viewvc/qpid/dispatch/trunk/doc/man/qdstat.rst?rev=1665993&view=auto ============================================================================== --- qpid/dispatch/trunk/doc/man/qdstat.rst (added) +++ qpid/dispatch/trunk/doc/man/qdstat.rst Wed Mar 11 20:25:45 2015 @@ -0,0 +1,41 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License + +qdstat manual page +================== + +Synopsis +-------- + +qdstat [options] + +Description +----------- + +*qdstat* shows status information about networks of Dispatch routers. It +can display connections, network nodes and links, and router stats such +as memory use. + +Options +------- + +.. include:: qdstat_help.rst + +See also +-------- + +*qdrouterd(8)*, *qdmanage(8)*, *qdrouterd.conf(5)* + +http://qpid.apache.org/components/dispatch-router Added: qpid/dispatch/trunk/doc/notes/code-conventions.rst URL: http://svn.apache.org/viewvc/qpid/dispatch/trunk/doc/notes/code-conventions.rst?rev=1665993&view=auto ============================================================================== --- qpid/dispatch/trunk/doc/notes/code-conventions.rst (added) +++ qpid/dispatch/trunk/doc/notes/code-conventions.rst Wed Mar 11 20:25:45 2015 @@ -0,0 +1,30 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +Code conventions +================ + +Python code +----------- + +Python code should be +`PEP-8 <http://www.python.org/dev/peps/pep-0008/>`__ compliant. In +particular: + +- Use four-space indents +- Do not use studlyCaps for function, method, and variable names; + instead use underscore\_separated\_names Modified: qpid/dispatch/trunk/python/qpid_dispatch_internal/management/schema_doc.py URL: http://svn.apache.org/viewvc/qpid/dispatch/trunk/python/qpid_dispatch_internal/management/schema_doc.py?rev=1665993&r1=1665992&r2=1665993&view=diff ============================================================================== --- qpid/dispatch/trunk/python/qpid_dispatch_internal/management/schema_doc.py (original) +++ qpid/dispatch/trunk/python/qpid_dispatch_internal/management/schema_doc.py Wed Mar 11 20:25:45 2015 @@ -27,9 +27,11 @@ from .schema import quotestr class SchemaWriter(object): """Write the schema as a markdown document""" + HEADINGS=r'=-+^*`:"~_#<>' + def __init__(self, output, schema, quiet=True): self.output, self.schema, self.quiet = output, schema, quiet - self._heading = 1 + self._heading = 0 # Options affecting how output is written def warn(self, message): @@ -43,7 +45,7 @@ class SchemaWriter(object): def heading(self, text=None, sub=0): self._heading += sub - if text: self.para("\n%s %s" % (self._heading*"#", text)) + if text: self.para("\n%s\n%s" % (text, self.HEADINGS[self._heading]*len(text))) class Section(namedtuple("Section", ["writer", "heading"])): def __enter__(self): self.writer.heading(self.heading, sub=+1) @@ -68,7 +70,7 @@ class SchemaWriter(object): self.writeln('*%s*%s' % ( attr.name, self.attribute_qualifiers(attr, show_create, show_update))) if attr.description: - self.writeln(": %s" % attr.description) + self.writeln(" %s" % attr.description) else: self.warn("Warning: No description for %s in %s" % (attr, attr.defined_in.short_name)) self.writeln() --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
