Merge pull request #739 from vingar/patch-D1847844-F1E9-4861-97B5-CB0…

…09FC15A04-documentation__More_work

documentation: Minor fixes and epilog fix for sphinx-argparse #572

bin/rucio

@@ -2486,11 +2486,16 @@ def get_parser():
 
     # Ping command
     ping_parser = subparsers.add_parser('ping', formatter_class=argparse.RawDescriptionHelpFormatter, help='Ping Rucio server.',
-                                        epilog='''Example usage:
-    $ rucio ping
-    1.14.8
-The returned value is the version of Rucio installed on the server
-                                               ''')
+                                        epilog='Usage example\n'
+                                               '"""""""""""""\n'
+                                               '\n'
+                                               'To ping the server::\n'
+                                               '\n'
+                                               '    $ rucio ping\n'
+                                               '    1.14.8\n'
+                                               '\n'
+                                               'The returned value is the version of Rucio installed on the server.'
+                                               '\n')
     ping_parser.set_defaults(which='ping')
 
     # The whoami command
@@ -2506,8 +2511,11 @@ The returned value is the account currently used
     # The list-file-replicas command
     list_file_replicas_parser = subparsers.add_parser('list-file-replicas', help='List the replicas of a DID and it\'s PFNs.', description='This method allows to list all the replicas of a given Data IDentifier (DID). \
 The only mandatory parameter is the DID which can be a container/dataset/files. By default all the files replicas in state available are returned.', formatter_class=argparse.RawDescriptionHelpFormatter,
-                                                      epilog='''Example usage:
-To list the file replicas for a given dataset :
+                                                      epilog='''Example usage
+^^^^^^^^^^^^^
+
+To list the file replicas for a given dataset ::
+
     $ rucio list-file-replicas user.jdoe:user.jdoe.test.data.1234.1
     +-----------+---------------------------------+------------+-----------+-----------------------------------------------------------------------------------+
     | SCOPE      | NAME                              | FILESIZE   | ADLER32   | RSE: REPLICA                                                                   |
@@ -2516,14 +2524,15 @@ To list the file replicas for a given dataset :
     | user.jdoe | user.jdoe.test.data.1234.file.1 | 94.835 MB  | 5d000974  | SITE2_DISK: file://another/path/to/file/user.jdoe/user.jdoe.test.data.1234.file.1 |
     | user.jdoe | user.jdoe.test.data.1234.file.2 | 82.173 MB  | 01e56f23  | SITE2_DISK: file://another/path/to/file/user.jdoe/user.jdoe.test.data.1234.file.2 |
     +------------+-----------------------------------+------------+-----------+--------------------------------------------------------------------------------+
-To list the missing replica of a dataset of a given RSE :
+
+To list the missing replica of a dataset of a given RSE ::
+
     $ rucio list-file-replicas --rse SITE1_DISK user.jdoe:user.jdoe.test.data.1234.1
     +---------------+------------------------+
     | SCOPE     | NAME                       |
     |---------------+------------------------|
     | user.jdoe | user.jdoe.test.data.1234.2 |
-    +-----------+----------------------------+
-                                                 ''')
+    +-----------+----------------------------+''')
     list_file_replicas_parser.set_defaults(which='list_file_replicas')
     list_file_replicas_parser.add_argument('--protocols', dest='protocols', action='store', help='List of comma separated protocols. (i.e. https, root, srm).', required=False)
     list_file_replicas_parser.add_argument('--all-states', dest='all_states', action='store_true', default=False, help='To select all replicas (including unavailable ones).', required=False)

doc/source/conf.py

@@ -50,7 +50,7 @@
 
 # General information about the project.
 project = u'Rucio'
-copyright = u'2012-2018 CERN for the benefit of the ATLAS collaboration.'
+copyright = u'2012-2018 CERN for the benefit of the ATLAS collaboration'
 author = u'rucio-dev@cern.ch'
 
 # The version info for the project you're documenting, acts as replacement for

doc/source/index.rst

@@ -74,8 +74,8 @@ Operator Documentation
     installing_daemons
     monitoring
 
-Miscellaneous
-=============
+Authors
+=======
 
 .. toctree::
     :maxdepth: 1

lib/rucio/common/doc/argparse/ext.py

@@ -155,7 +155,7 @@ def print_subcommands(data, nested_content, markDownHelp=False):
     """
     Each subcommand is a dictionary with the following keys:
 
-    ['usage', 'action_groups', 'bare_usage', 'name', 'help']
+    ['usage', 'action_groups', 'bare_usage', 'name', 'help', 'epilog']
 
     In essence, this is all tossed in a new section with the title 'name'.
     Apparently there can also be a 'description' entry.
@@ -198,7 +198,12 @@ def print_subcommands(data, nested_content, markDownHelp=False):
             for x in print_subcommands(child, nested_content + subContent, markDownHelp):
                 sec += x
 
+            if 'epilog' in child and child['epilog']:
+                for element in renderList([child['epilog']], markDownHelp):
+                    sec += element
+
             subCommands += sec
+
         items.append(subCommands)
 
     return items
@@ -269,6 +274,7 @@ def _construct_manpage_specific_structure(self, parser_info):
             nested_parse_with_titles(
                 self.state, self.content, description_section)
             items.append(description_section)
+
         if parser_info.get('epilog') and 'noepilog' not in self.options:
             # TODO: do whatever sphinx does to understand ReST inside
             # docstrings magically imported from other places. The nested