You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by ac...@apache.org on 2015/03/12 15:34:29 UTC
svn commit: r1666214 [3/3] - in /qpid/dispatch/branches/0.4: doc/ doc/book/
doc/man/ doc/notes/ python/qpid_dispatch_internal/management/
Copied: qpid/dispatch/branches/0.4/doc/man/help2rst.py (from r1665930, qpid/dispatch/branches/0.4/doc/man/help2md.py)
URL: http://svn.apache.org/viewvc/qpid/dispatch/branches/0.4/doc/man/help2rst.py?p2=qpid/dispatch/branches/0.4/doc/man/help2rst.py&p1=qpid/dispatch/branches/0.4/doc/man/help2md.py&r1=1665930&r2=1666214&rev=1666214&view=diff
==============================================================================
--- qpid/dispatch/branches/0.4/doc/man/help2md.py (original)
+++ qpid/dispatch/branches/0.4/doc/man/help2rst.py Thu Mar 12 14:34:28 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/branches/0.4/doc/man/qdmanage.rst.in
URL: http://svn.apache.org/viewvc/qpid/dispatch/branches/0.4/doc/man/qdmanage.rst.in?rev=1666214&view=auto
==============================================================================
--- qpid/dispatch/branches/0.4/doc/man/qdmanage.rst.in (added)
+++ qpid/dispatch/branches/0.4/doc/man/qdmanage.rst.in Thu Mar 12 14:34:28 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/branches/0.4/doc/man/qdrouterd.rst.in
URL: http://svn.apache.org/viewvc/qpid/dispatch/branches/0.4/doc/man/qdrouterd.rst.in?rev=1666214&view=auto
==============================================================================
--- qpid/dispatch/branches/0.4/doc/man/qdrouterd.rst.in (added)
+++ qpid/dispatch/branches/0.4/doc/man/qdrouterd.rst.in Thu Mar 12 14:34:28 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/branches/0.4/doc/man/qdrouterd_conf_man.py
URL: http://svn.apache.org/viewvc/qpid/dispatch/branches/0.4/doc/man/qdrouterd_conf_man.py?rev=1666214&r1=1666213&r2=1666214&view=diff
==============================================================================
--- qpid/dispatch/branches/0.4/doc/man/qdrouterd_conf_man.py (original)
+++ qpid/dispatch/branches/0.4/doc/man/qdrouterd_conf_man.py Thu Mar 12 14:34:28 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/branches/0.4/doc/man/qdstat.rst
URL: http://svn.apache.org/viewvc/qpid/dispatch/branches/0.4/doc/man/qdstat.rst?rev=1666214&view=auto
==============================================================================
--- qpid/dispatch/branches/0.4/doc/man/qdstat.rst (added)
+++ qpid/dispatch/branches/0.4/doc/man/qdstat.rst Thu Mar 12 14:34:28 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/branches/0.4/doc/notes/code-conventions.rst
URL: http://svn.apache.org/viewvc/qpid/dispatch/branches/0.4/doc/notes/code-conventions.rst?rev=1666214&view=auto
==============================================================================
--- qpid/dispatch/branches/0.4/doc/notes/code-conventions.rst (added)
+++ qpid/dispatch/branches/0.4/doc/notes/code-conventions.rst Thu Mar 12 14:34:28 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/branches/0.4/python/qpid_dispatch_internal/management/schema_doc.py
URL: http://svn.apache.org/viewvc/qpid/dispatch/branches/0.4/python/qpid_dispatch_internal/management/schema_doc.py?rev=1666214&r1=1666213&r2=1666214&view=diff
==============================================================================
--- qpid/dispatch/branches/0.4/python/qpid_dispatch_internal/management/schema_doc.py (original)
+++ qpid/dispatch/branches/0.4/python/qpid_dispatch_internal/management/schema_doc.py Thu Mar 12 14:34:28 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: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org