qpid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From acon...@apache.org
Subject svn commit: r1666214 [3/3] - in /qpid/dispatch/branches/0.4: doc/ doc/book/ doc/man/ doc/notes/ python/qpid_dispatch_internal/management/
Date Thu, 12 Mar 2015 14:34:29 GMT
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


Mime
View raw message