Browse Source

Remove the 'openstack-auto-commands' tool

The 'openstack-auto-commands' command has been superseded by the
'cliff.sphinxext' Sphinx extensions [1]. Remove both this and the helper
script in 'bin/doc-tools-update-cli-reference'.

[1] https://docs.openstack.org/cliff/latest/user/sphinxext.html

Change-Id: Ia20ace51377290997566b89ad4f78a941358cb86
Stephen Finucane 1 year ago
parent
commit
cb165573bc

+ 0
- 89
bin/doc-tools-update-cli-reference View File

@@ -1,89 +0,0 @@
1
-#!/bin/bash
2
-
3
-# Licensed under the Apache License, Version 2.0 (the "License"); you may
4
-# not use this file except in compliance with the License. You may obtain
5
-# a copy of the License at
6
-#
7
-#      http://www.apache.org/licenses/LICENSE-2.0
8
-#
9
-# Unless required by applicable law or agreed to in writing, software
10
-# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11
-# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12
-# License for the specific language governing permissions and limitations
13
-# under the License.
14
-
15
-if [[ $# -ne 1 ]]; then
16
-    echo "usage: $0 PROJECT"
17
-    echo
18
-    echo "PROJECT = something like nova, neutron or glance"
19
-    exit 1
20
-fi
21
-
22
-project=$1
23
-
24
-# checks command exist or not
25
-function does_exist {
26
-    which $@ > /dev/null 2>&1
27
-    local status=$?
28
-    if [[ $status -ne 0 ]]; then
29
-        echo "error: $1 not installed"
30
-        exit 1
31
-    fi
32
-}
33
-
34
-does_exist virtualenv
35
-does_exist pip
36
-does_exist git
37
-
38
-if [[ ! -e $HOME/.gitconfig ]]; then
39
-    echo "note: ~/.gitconfig does not exist"
40
-fi
41
-
42
-if [[ ! -e .venv ]]; then
43
-    virtualenv -p python2.7 .venv
44
-fi
45
-
46
-source .venv/bin/activate
47
-
48
-pip install --upgrade openstack-doc-tools
49
-pip install --upgrade pbr
50
-
51
-# Cliff can optionally output HTML - if cliff-tablib is installed.
52
-pip install --upgrade cliff-tablib
53
-
54
-# OSProfiler is an OpenStack cross-project profiling library.
55
-pip install --upgrade osprofiler
56
-
57
-if [[ $project == 'aodh' ]]; then
58
-    pip install --upgrade ${project}client
59
-elif [[ $project == 'gnocchi' ]]; then
60
-    pip install --upgrade ${project}client
61
-else
62
-    pip install --upgrade python-${project}client
63
-fi
64
-
65
-rm -rf output
66
-mkdir output
67
-
68
-# Work around until python-cinderclient use 3.latest as a default
69
-OS_VOLUME_API_VERSION=3.latest \
70
-openstack-auto-commands --output-dir output $project
71
-
72
-if [[ ! -e "python-${project}client" ]]; then
73
-    git clone git://git.openstack.org/openstack/python-${project}client
74
-fi
75
-
76
-cd python-${project}client
77
-
78
-( git remote -v  | grep -q gerrit ) || git review -s
79
-
80
-git checkout master
81
-git pull
82
-branch=cli-reference
83
-git branch --list $branch && git branch -D $branch
84
-git checkout -b $branch
85
-mv ../output/${project}.rst "doc/source/cli/details.rst"
86
-rm -rf ../output
87
-version=$($project --version 2>&1)
88
-version=${version##*\)}
89
-git commit -a -m "[cli-ref] Update python-${project}client to ${version##* }"

+ 0
- 772
os_doc_tools/commands.py View File

@@ -1,772 +0,0 @@
1
-#!/usr/bin/env python
2
-
3
-# Licensed under the Apache License, Version 2.0 (the "License"); you may
4
-# not use this file except in compliance with the License. You may obtain
5
-# a copy of the License at
6
-#
7
-#      http://www.apache.org/licenses/LICENSE-2.0
8
-#
9
-# Unless required by applicable law or agreed to in writing, software
10
-# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11
-# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12
-# License for the specific language governing permissions and limitations
13
-# under the License.
14
-
15
-import argparse
16
-import os
17
-import subprocess
18
-import sys
19
-import yaml
20
-
21
-import os_doc_tools
22
-
23
-DEVNULL = open(os.devnull, 'wb')
24
-MAXLINELENGTH = 78
25
-
26
-
27
-def use_help_flag(os_command):
28
-    """Use --help flag (instead of help keyword)
29
-
30
-    Returns true if the command requires a --help flag instead
31
-    of a help keyword.
32
-    """
33
-
34
-    return os_command == "swift" or "-manage" in os_command
35
-
36
-
37
-def quote_rst(line):
38
-    """Convert special characters for RST output."""
39
-
40
-    line = line.replace('\\', '\\\\').replace('`', '\\`').replace('*', '\\*')
41
-
42
-    if 'DEPRECATED!' in line:
43
-        line = line.replace('DEPRECATED!', '**DEPRECATED!**')
44
-    elif 'DEPRECATED' in line:
45
-        line = line.replace('DEPRECATED', '**DEPRECATED**')
46
-
47
-    if 'env[' in line:
48
-        line = line.replace('env[', '``env[').replace(']', ']``')
49
-        # work around for "Default=env[...]" at cinder
50
-        line = line.replace('=``', '= ``')
51
-
52
-    return line
53
-
54
-
55
-def generate_heading(os_command, api_name, title,
56
-                     output_dir, os_filename, continue_on_error):
57
-    """Write RST file header.
58
-
59
-    :param os_command:        client command to document
60
-    :param api_name:          string description of the API of os_command
61
-    :param output_dir:        directory to write output file to
62
-    :param os_filename:       name to create current output file as
63
-    :param continue_on_error: continue even if there's an error
64
-    """
65
-
66
-    try:
67
-        version = subprocess.check_output([os_command, "--version"],
68
-                                          universal_newlines=True,
69
-                                          stderr=subprocess.STDOUT)
70
-    except OSError as e:
71
-        if e.errno == os.errno.ENOENT:
72
-            action = 'skipping' if continue_on_error else 'aborting'
73
-            print("Command %s not found, %s." % (os_command, action))
74
-            if continue_on_error:
75
-                return
76
-            else:
77
-                sys.exit(1)
78
-    # Extract version from "swift 0.3"
79
-    version = version.splitlines()[-1].strip().rpartition(' ')[2]
80
-
81
-    print("Documenting '%s help (version %s)'" % (os_command, version))
82
-
83
-    os_file = open(os.path.join(output_dir, os_filename), 'w')
84
-    os_file.write(".. ###################################################\n")
85
-    os_file.write(".. ##  WARNING  ######################################\n")
86
-    os_file.write(".. ##############  WARNING  ##########################\n")
87
-    os_file.write(".. ##########################  WARNING  ##############\n")
88
-    os_file.write(".. ######################################  WARNING  ##\n")
89
-    os_file.write(".. ###################################################\n")
90
-    os_file.write(".. ###################################################\n")
91
-    os_file.write(".. ##\n")
92
-    os_file.write(".. This file is tool-generated. Do not edit manually.\n")
93
-    os_file.write(".. http://docs.openstack.org/contributor-guide/\n")
94
-    os_file.write(".. doc-tools/cli-reference.html\n")
95
-    os_file.write("..                                                  ##\n")
96
-    os_file.write(".. ##  WARNING  ######################################\n")
97
-    os_file.write(".. ##############  WARNING  ##########################\n")
98
-    os_file.write(".. ##########################  WARNING  ##############\n")
99
-    os_file.write(".. ######################################  WARNING  ##\n")
100
-    os_file.write(".. ###################################################\n\n")
101
-    format_heading(title, 1, os_file)
102
-
103
-    if os_command == "heat":
104
-        os_file.write(".. warning::\n\n")
105
-        os_file.write("   The " + os_command + " CLI is deprecated\n")
106
-        os_file.write("   in favor of python-openstackclient.\n\n")
107
-
108
-    os_file.write("The " + os_command + " client is the command-line ")
109
-    os_file.write("interface (CLI) for the\n")
110
-    os_file.write(api_name + "\n")
111
-    os_file.write("and its extensions.\n\n")
112
-
113
-    os_file.write("This chapter documents :command:`" + os_command + "` ")
114
-    os_file.write("version ``" + version + "``.\n\n")
115
-
116
-    os_file.write("For help on a specific :command:`" + os_command + "` ")
117
-    os_file.write("command, enter:\n\n")
118
-
119
-    os_file.write(".. code-block:: console\n\n")
120
-    if use_help_flag(os_command):
121
-        os_file.write("   $ " + os_command + " COMMAND --help\n\n")
122
-    else:
123
-        os_file.write("   $ " + os_command + " help COMMAND\n\n")
124
-
125
-    os_file.write(".. _" + os_command + "_command_usage:\n\n")
126
-    format_heading(os_command + " usage", 2, os_file)
127
-    return os_file
128
-
129
-
130
-def is_option(string):
131
-    """Returns True if string specifies an argument."""
132
-
133
-    for x in string:
134
-        if not (x.isupper() or x == '_' or x == ','):
135
-            return False
136
-
137
-    if string.startswith('DEPRECATED'):
138
-        return False
139
-    return True
140
-
141
-
142
-def extract_options(line):
143
-    """Extract command or option from line."""
144
-
145
-    # We have a command or parameter to handle
146
-    # Differentiate:
147
-    #  1. --version
148
-    #  2. --timeout <seconds>
149
-    #  3. --service <service>, --service-id <service>
150
-    #  4. -v, --verbose
151
-    #  5. -p PORT, --port PORT
152
-    #  6. <backup>              ID of the backup to restore.
153
-    #  7. --alarm-action <Webhook URL>
154
-    #  8.   <NAME or ID>  Name or ID of stack to resume.
155
-    #  9. --json JSON  JSON representation of node group template.
156
-    # 10. --id <cluster_id> ID of the cluster to show.
157
-    # 11. --instance "<opt=value,opt=value,...>"
158
-
159
-    split_line = line.split(None, 2)
160
-
161
-    if split_line[0].startswith("-"):
162
-        last_was_option = True
163
-    else:
164
-        last_was_option = False
165
-
166
-    if (len(split_line) > 1 and
167
-        ('<' in split_line[0] or
168
-         '<' in split_line[1] or
169
-         '--' in split_line[1] or
170
-         split_line[1].startswith(("-", '<', '{', '[')) or
171
-         is_option(split_line[1]))):
172
-
173
-        words = line.split(None)
174
-
175
-        i = 0
176
-        while i < len(words) - 1:
177
-            if (('<' in words[i] and
178
-                '>' not in words[i]) or
179
-                ('[' in words[i] and
180
-                 ']' not in words[i])):
181
-                words[i] += ' ' + words[i + 1]
182
-                del words[i + 1]
183
-            else:
184
-                i += 1
185
-
186
-        skip_is_option = False
187
-        while len(words) > 1:
188
-            if words[1].startswith('DEPRECATED'):
189
-                break
190
-            if last_was_option:
191
-                if (words[1].startswith(("-", '<', '{', '[', '"')) or
192
-                   (is_option(words[1]) and skip_is_option is False)):
193
-                    skip_is_option = False
194
-                    if words[1].isupper() or words[1].startswith('<'):
195
-                        skip_is_option = True
196
-                    words[0] = words[0] + ' ' + words[1]
197
-                    del words[1]
198
-                else:
199
-                    break
200
-            else:
201
-                if words[1].startswith("-"):
202
-                    words[0] = words[0] + ' ' + words[1]
203
-                    del words[1]
204
-                else:
205
-                    break
206
-
207
-        w0 = words[0]
208
-        del words[0]
209
-        w1 = ''
210
-        if words:
211
-            w1 = words[0]
212
-            del words[0]
213
-            for w in words:
214
-                w1 += " " + w
215
-
216
-        if not w1:
217
-            split_line = [w0]
218
-        else:
219
-            split_line = [w0, w1]
220
-    else:
221
-        split_line = line.split(None, 1)
222
-
223
-    return split_line
224
-
225
-
226
-def format_heading(heading, level, os_file):
227
-    """Nicely print heading.
228
-
229
-    :param heading: heading strings
230
-    :param level: heading level
231
-    :param os_file: open filehandle for output of RST file
232
-    """
233
-
234
-    if level == 1:
235
-        os_file.write("=" * len(heading) + "\n")
236
-
237
-    os_file.write(heading + "\n")
238
-
239
-    if level == 1:
240
-        os_file.write("=" * len(heading) + "\n\n")
241
-    elif level == 2:
242
-        os_file.write("~" * len(heading) + "\n\n")
243
-    elif level == 3:
244
-        os_file.write("-" * len(heading) + "\n\n")
245
-    else:
246
-        os_file.write("\n")
247
-
248
-    return
249
-
250
-
251
-def format_help(title, lines, os_file):
252
-    """Nicely print section of lines.
253
-
254
-    :param title: help title, if exist
255
-    :param lines: strings to format
256
-    :param os_file: open filehandle for output of RST file
257
-    """
258
-
259
-    close_entry = False
260
-    if title:
261
-        os_file.write("**" + title + ":**" + "\n\n")
262
-
263
-    continued_line = ''
264
-    for line in lines:
265
-        if not line or line[0] != ' ':
266
-            break
267
-        # We have to handle these cases:
268
-        # 1. command  Explanation
269
-        # 2. command
270
-        #             Explanation on next line
271
-        # 3. command  Explanation continued
272
-        #             on next line
273
-        # If there are more than 8 spaces, let's treat it as
274
-        # explanation.
275
-        if line.startswith('       '):
276
-            # Explanation
277
-            xline = continued_line + quote_rst(line.lstrip(' '))
278
-            continued_line = ''
279
-            # Concatenate the command options with "-"
280
-            # For example:
281
-            #     see 'glance image-
282
-            #     show'
283
-            if xline.endswith('-'):
284
-                continued_line = xline
285
-                continue
286
-            # check niceness
287
-            if len(xline) > (MAXLINELENGTH - 2):
288
-                xline = xline.replace(' ', '\n  ')
289
-            os_file.write("  " + xline + "\n")
290
-            continue
291
-        # Now we have a command or parameter to handle
292
-        split_line = extract_options(line)
293
-
294
-        if not close_entry:
295
-            close_entry = True
296
-        else:
297
-            os_file.write("\n")
298
-
299
-        xline = split_line[0]
300
-
301
-        # check niceness work around for long option name, glance
302
-        xline = xline.replace('[<RESOURCE_TYPE_ASSOCIATIONS> ...]',
303
-                              '[...]')
304
-
305
-        os_file.write("``" + xline + "``\n")
306
-
307
-        if len(split_line) > 1:
308
-            # Explanation
309
-            xline = continued_line + quote_rst(split_line[1])
310
-            continued_line = ''
311
-            # Concatenate the command options with "-"
312
-            # For example:
313
-            #     see 'glance image-
314
-            #     show'
315
-            if xline.endswith('-'):
316
-                continued_line = xline
317
-                continue
318
-            # check niceness
319
-            if len(xline) > (MAXLINELENGTH - 2):
320
-                # check niceness
321
-                xline = xline.replace(' ', '\n  ')
322
-            os_file.write("  " + xline + "\n")
323
-
324
-    os_file.write("\n")
325
-
326
-    return
327
-
328
-
329
-def generate_command(os_command, os_file):
330
-    """Convert os_command --help to RST.
331
-
332
-    :param os_command: client command to document
333
-    :param os_file:    open filehandle for output of RST file
334
-    """
335
-
336
-    if use_help_flag(os_command):
337
-        help_lines = subprocess.check_output([os_command, "--help"],
338
-                                             universal_newlines=True,
339
-                                             stderr=DEVNULL).split('\n')
340
-    else:
341
-        help_lines = subprocess.check_output([os_command, "help"],
342
-                                             universal_newlines=True,
343
-                                             stderr=DEVNULL).split('\n')
344
-
345
-    ignore_next_lines = False
346
-    next_line_screen = True
347
-    line_index = -1
348
-    in_screen = False
349
-    subcommands = 'complete'
350
-    for line in help_lines:
351
-        line_index += 1
352
-        if line and line[0] != ' ':
353
-            # XXX: Might have whitespace before!!
354
-            if '<subcommands>' in line:
355
-                ignore_next_lines = False
356
-                continue
357
-            if 'Positional arguments' in line:
358
-                ignore_next_lines = True
359
-                next_line_screen = True
360
-                os_file.write("\n\n")
361
-                in_screen = False
362
-                if os_command != "glance":
363
-                    format_help('Subcommands',
364
-                                help_lines[line_index + 2:], os_file)
365
-                continue
366
-            if line.startswith(('Optional arguments:', 'Optional:',
367
-                                'Options:', 'optional arguments')):
368
-                if in_screen:
369
-                    os_file.write("\n\n")
370
-                    in_screen = False
371
-                os_file.write(".. _" + os_command + "_command_options:\n\n")
372
-                format_heading(os_command + " optional arguments", 2, os_file)
373
-                format_help('', help_lines[line_index + 1:], os_file)
374
-                next_line_screen = True
375
-                ignore_next_lines = True
376
-                continue
377
-            # magnum
378
-            if line.startswith('Common auth options'):
379
-                if in_screen:
380
-                    os_file.write("\n\n")
381
-                    in_screen = False
382
-                os_file.write("\n")
383
-                os_file.write(os_command)
384
-                os_file.write(".. _" + os_command + "_common_auth:\n\n")
385
-                format_heading(os_command + " common authentication arguments",
386
-                               2, os_file)
387
-                format_help('', help_lines[line_index + 1:], os_file)
388
-                next_line_screen = True
389
-                ignore_next_lines = True
390
-                continue
391
-            # neutron
392
-            if line.startswith('Commands for API v2.0:'):
393
-                if in_screen:
394
-                    os_file.write("\n\n")
395
-                    in_screen = False
396
-                os_file.write(".. _" + os_command + "_common_api_v2:\n\n")
397
-                format_heading(os_command + " API v2.0 commands", 2, os_file)
398
-                format_help('', help_lines[line_index + 1:], os_file)
399
-                next_line_screen = True
400
-                ignore_next_lines = True
401
-                continue
402
-            # swift
403
-            if line.startswith('Examples:'):
404
-                os_file.write(".. _" + os_command + "_examples:\n\n")
405
-                format_heading(os_command + " examples", 2, os_file)
406
-                next_line_screen = True
407
-                ignore_next_lines = False
408
-                continue
409
-            # all
410
-            if not line.startswith('usage'):
411
-                continue
412
-        if not ignore_next_lines:
413
-            if next_line_screen:
414
-                os_file.write(".. code-block:: console\n\n")
415
-                os_file.write("   " + line)
416
-                next_line_screen = False
417
-                in_screen = True
418
-            elif line:
419
-                os_file.write("\n   " + line.rstrip())
420
-        # subcommands (select bash-completion, complete for bash-completion)
421
-        if 'bash-completion' in line:
422
-            subcommands = 'bash-completion'
423
-
424
-    if in_screen:
425
-        os_file.write("\n\n")
426
-
427
-    return subcommands
428
-
429
-
430
-def generate_subcommand(os_command, os_subcommand, os_file, extra_params,
431
-                        suffix, title_suffix):
432
-    """Convert os_command help os_subcommand to RST.
433
-
434
-    :param os_command: client command to document
435
-    :param os_subcommand: client subcommand to document
436
-    :param os_file:    open filehandle for output of RST file
437
-    :param extra_params: Extra parameter to pass to os_command
438
-    :param suffix: Extra suffix to add to link ID
439
-    :param title_suffix: Extra suffix for title
440
-    """
441
-
442
-    print("Documenting subcommand '%s'..." % os_subcommand)
443
-
444
-    args = [os_command]
445
-    if extra_params:
446
-        args.extend(extra_params)
447
-    if use_help_flag(os_command):
448
-        args.append(os_subcommand)
449
-        args.append("--help")
450
-    else:
451
-        args.append("help")
452
-        args.append(os_subcommand)
453
-    help_lines = subprocess.check_output(args,
454
-                                         universal_newlines=True,
455
-                                         stderr=DEVNULL)
456
-
457
-    help_lines_lower = help_lines.lower()
458
-    if 'positional arguments' in help_lines_lower:
459
-        index = help_lines_lower.index('positional arguments')
460
-    elif 'optional arguments' in help_lines_lower:
461
-        index = help_lines_lower.index('optional arguments')
462
-    else:
463
-        index = len(help_lines_lower)
464
-
465
-    if 'deprecated' in (help_lines_lower[0:index]):
466
-        print("Subcommand '%s' is deprecated, skipping." % os_subcommand)
467
-        return
468
-
469
-    help_lines = help_lines.split('\n')
470
-
471
-    os_subcommandid = os_subcommand.replace(' ', '_')
472
-    os_file.write(".. _" + os_command + "_" + os_subcommandid + suffix)
473
-    os_file.write(":\n\n")
474
-    format_heading(os_command + " " + os_subcommand + title_suffix, 3, os_file)
475
-
476
-    if os_command == "swift":
477
-        next_line_screen = False
478
-        os_file.write(".. code-block:: console\n\n")
479
-        os_file.write("Usage: swift " + os_subcommand + "\n\n")
480
-        in_para = True
481
-    else:
482
-        next_line_screen = True
483
-        in_para = False
484
-    if extra_params:
485
-        extra_paramstr = ' '.join(extra_params)
486
-        help_lines[0] = help_lines[0].replace(os_command, "%s %s" %
487
-                                              (os_command, extra_paramstr))
488
-    line_index = -1
489
-    # Content is:
490
-    # usage...
491
-    #
492
-    # Description
493
-    #
494
-    # Arguments
495
-
496
-    skip_lines = False
497
-    for line in help_lines:
498
-        line_index += 1
499
-        if line.startswith('Usage:') and os_command == "swift":
500
-            line = line[len("Usage: "):]
501
-        if line.startswith(('Arguments:',
502
-                            'Positional arguments:', 'positional arguments',
503
-                            'Optional arguments', 'optional arguments',
504
-                            'Required arguments', 'required arguments')):
505
-            if in_para:
506
-                in_para = False
507
-                os_file.write("\n")
508
-            if line.startswith(('Positional arguments',
509
-                                'positional arguments')):
510
-                format_help('Positional arguments',
511
-                            help_lines[line_index + 1:], os_file)
512
-                skip_lines = True
513
-                continue
514
-            elif line.startswith(('Optional arguments:',
515
-                                  'optional arguments')):
516
-                format_help('Optional arguments',
517
-                            help_lines[line_index + 1:], os_file)
518
-                skip_lines = True
519
-                continue
520
-            elif line.startswith(('Required arguments:',
521
-                                  'required arguments')):
522
-                format_help('Required arguments',
523
-                            help_lines[line_index + 1:], os_file)
524
-                skip_lines = True
525
-                continue
526
-            else:
527
-                format_help('Arguments', help_lines[line_index + 1:], os_file)
528
-                break
529
-        if skip_lines:
530
-            continue
531
-        if not line:
532
-            if not in_para:
533
-                os_file.write("\n")
534
-            in_para = True
535
-            continue
536
-        if next_line_screen:
537
-            os_file.write(".. code-block:: console\n\n")
538
-            os_file.write("   " + line + "\n")
539
-            next_line_screen = False
540
-        elif line.startswith('       '):
541
-            # ceilometer alarm-gnocchi-aggregation-by-metrics-threshold-create
542
-            # has 7 white space indentation
543
-            if not line.isspace():
544
-                # skip blank line, such as "trove help cluster-grow" command.
545
-                os_file.write("   " + line + "\n")
546
-        else:
547
-            xline = quote_rst(line)
548
-            if (len(xline) > MAXLINELENGTH):
549
-                # check niceness
550
-                xline = xline.replace(' ', '\n')
551
-            os_file.write(xline + "\n")
552
-
553
-    if in_para:
554
-        os_file.write("\n")
555
-
556
-
557
-def discover_subcommands(os_command, subcommands, extra_params):
558
-    """Discover all help subcommands for the given command"
559
-
560
-    :param os_command: client command whose subcommands need to be discovered
561
-    :param subcommands: list or type ('complete' or 'bash-completion')
562
-                        of subcommands to document
563
-    :param extra_params: Extra parameter to pass to os_command.
564
-    :return: the list of subcommands discovered
565
-    :rtype: list(str)
566
-    """
567
-    if extra_params is None:
568
-        extra_params = ''
569
-    print(("Discovering subcommands of '%s' %s ..."
570
-          % (os_command, extra_params)))
571
-    blacklist = ['bash-completion', 'complete', 'help']
572
-    if type(subcommands) is str:
573
-        args = [os_command]
574
-        if extra_params:
575
-            args.extend(extra_params)
576
-        if subcommands == 'complete':
577
-            subcommands = []
578
-            args.append('complete')
579
-            lines = subprocess.check_output(
580
-                args, universal_newlines=True, stderr=DEVNULL).split('\n')
581
-            delim = ' '
582
-            # if the cmds= line contains '-' then use that as a delim
583
-            for line in lines:
584
-                if '-' in line and 'cmds=' in line:
585
-                    delim = '-'
586
-                    break
587
-            for line in [x.strip() for x in lines
588
-                         if x.strip().startswith('cmds_') and '-' in x]:
589
-                subcommand, _ = line.split('=')
590
-                subcommand = subcommand.replace(
591
-                    'cmds_', '').replace('_', delim)
592
-                subcommands.append(subcommand)
593
-        else:
594
-            args.append('bash-completion')
595
-            subcommands = subprocess.check_output(
596
-                args,
597
-                universal_newlines=True).strip().split('\n')[-1].split()
598
-
599
-    subcommands = sorted([o for o in subcommands if not (o.startswith('-') or
600
-                                                         o in blacklist)])
601
-
602
-    print("%d subcommands discovered." % len(subcommands))
603
-    return subcommands
604
-
605
-
606
-def generate_subcommands(os_command, os_file, subcommands, extra_params,
607
-                         suffix, title_suffix):
608
-    """Convert os_command help subcommands for all subcommands to RST.
609
-
610
-    :param os_command: client command to document
611
-    :param os_file:    open filehandle for output of RST file
612
-    :param subcommands: list or type ('complete' or 'bash-completion')
613
-                        of subcommands to document
614
-    :param extra_params: Extra parameter to pass to os_command.
615
-    :param suffix: Extra suffix to add to link ID
616
-    :param title_suffix: Extra suffix for title
617
-    """
618
-    for subcommand in subcommands:
619
-        generate_subcommand(os_command, subcommand, os_file, extra_params,
620
-                            suffix, title_suffix)
621
-    print("%d subcommands documented." % len(subcommands))
622
-
623
-
624
-def discover_and_generate_subcommands(os_command, os_file, subcommands,
625
-                                      extra_params, suffix, title_suffix):
626
-    """Convert os_command help subcommands for all subcommands to RST.
627
-
628
-    :param os_command: client command to document
629
-    :param os_file:    open filehandle for output of RST file
630
-    :param subcommands: list or type ('complete' or 'bash-completion')
631
-                        of subcommands to document
632
-    :param extra_params: Extra parameter to pass to os_command.
633
-    :param suffix: Extra suffix to add to link ID
634
-    :param title_suffix: Extra suffix for title
635
-    """
636
-    subcommands = discover_subcommands(os_command, subcommands, extra_params)
637
-    generate_subcommands(os_command, os_file, subcommands, extra_params,
638
-                         suffix, title_suffix)
639
-
640
-
641
-def _get_clients_filename():
642
-    return os.path.join(os.path.dirname(__file__),
643
-                        'resources/clients.yaml')
644
-
645
-
646
-def get_clients():
647
-    """Load client definitions from the resource file."""
648
-    fname = _get_clients_filename()
649
-    clients = yaml.load(open(fname, 'r'))
650
-    return clients
651
-
652
-
653
-def document_single_project(os_command, output_dir, continue_on_error):
654
-    """Create documentation for os_command."""
655
-
656
-    clients = get_clients()
657
-
658
-    if os_command not in clients:
659
-        print("'%s' command not yet handled" % os_command)
660
-        print("(Command must be defined in '%s')" % _get_clients_filename())
661
-        if continue_on_error:
662
-            return False
663
-        else:
664
-            sys.exit(-1)
665
-
666
-    print("Documenting '%s'" % os_command)
667
-
668
-    data = clients[os_command]
669
-    if 'name' in data:
670
-        api_name = "%s API" % data['name']
671
-        title = "%s command-line client" % data.get('title', data['name'])
672
-    else:
673
-        api_name = ''
674
-        title = data.get('title', '')
675
-
676
-    out_filename = os_command + ".rst"
677
-    out_file = generate_heading(os_command, api_name, title,
678
-                                output_dir, out_filename,
679
-                                continue_on_error)
680
-    if not out_file:
681
-        if continue_on_error:
682
-            return False
683
-        else:
684
-            sys.exit(-1)
685
-
686
-    subcommands = generate_command(os_command, out_file)
687
-    if subcommands == 'complete' and data.get('subcommands'):
688
-        subcommands = data.get('subcommands')
689
-
690
-    discover_and_generate_subcommands(os_command, out_file, subcommands,
691
-                                      None, "", "")
692
-
693
-    print("Finished.\n")
694
-    out_file.close()
695
-    return True
696
-
697
-
698
-def main():
699
-    clients = get_clients()
700
-    api_clients = sorted([x for x in clients if not x.endswith('-manage')])
701
-    manage_clients = sorted([x for x in clients if x.endswith('-manage')])
702
-    all_clients = api_clients + manage_clients
703
-
704
-    parser = argparse.ArgumentParser(description="Generate RST files "
705
-                                     "to document python-PROJECTclients.")
706
-    parser.add_argument('clients', metavar='client', nargs='*',
707
-                        help="OpenStack command to document. Specify "
708
-                        "multiple times to generate documentation for "
709
-                        "multiple clients. One of: " +
710
-                        ", ".join(all_clients) + ".")
711
-    parser.add_argument("--all", help="Document all clients. "
712
-                        "Namely " + ", ".join(all_clients) + ".",
713
-                        action="store_true")
714
-    parser.add_argument("--all-api", help="Document all API clients. "
715
-                        "Namely " + ", ".join(clients.keys()) + ".",
716
-                        action="store_true")
717
-    parser.add_argument("--all-manage", help="Document all manage clients. "
718
-                        "Namely " + ", ".join(manage_clients) + ".",
719
-                        action="store_true")
720
-    parser.add_argument("--output-dir", default=".",
721
-                        help="Directory to write generated files to")
722
-    parser.add_argument("--continue-on-error", default=False,
723
-                        help="Continue with remaining clients even if an "
724
-                        "error occurs generating a client file.",
725
-                        action="store_true")
726
-    parser.add_argument("--version", default=False,
727
-                        help="Show program's version number and exit.",
728
-                        action="store_true")
729
-    prog_args = parser.parse_args()
730
-
731
-    client_list = []
732
-    if prog_args.all or prog_args.all_api or prog_args.all_manage:
733
-        if prog_args.all or prog_args.all_api:
734
-            client_list = api_clients
735
-        if prog_args.all or prog_args.all_manage:
736
-            client_list.extend(manage_clients)
737
-    elif prog_args.clients:
738
-        client_list = prog_args.clients
739
-
740
-    if not prog_args or 'help' in [client.lower() for client in client_list]:
741
-        parser.print_help()
742
-        sys.exit(0)
743
-    elif prog_args.version:
744
-        print(os_doc_tools.__version__)
745
-        sys.exit(0)
746
-
747
-    if not client_list:
748
-        parser.print_help()
749
-        sys.exit(1)
750
-
751
-    print("OpenStack Auto Documenting of Commands (using "
752
-          "openstack-doc-tools version %s)\n"
753
-          % os_doc_tools.__version__)
754
-
755
-    success_list = []
756
-    error_list = []
757
-    for client in client_list:
758
-        if document_single_project(
759
-                client, prog_args.output_dir, prog_args.continue_on_error):
760
-            success_list.append(client)
761
-        else:
762
-            error_list.append(client)
763
-
764
-    if success_list:
765
-        print("Generated documentation for: %s" % ", ".join(success_list))
766
-    if error_list:
767
-        print("Generation failed for: %s" % ", ".join(error_list))
768
-        sys.exit(1)
769
-
770
-
771
-if __name__ == "__main__":
772
-    sys.exit(main())

+ 0
- 134
os_doc_tools/resources/clients.yaml View File

@@ -1,134 +0,0 @@
1
----
2
-aodh:
3
-    name: Telemetry Alarming service (aodh)
4
-    subcommands:
5
-      - alarm create
6
-      - alarm delete
7
-      - alarm list
8
-      - alarm show
9
-      - alarm state get
10
-      - alarm state set
11
-      - alarm update
12
-      - alarm-history search
13
-      - alarm-history show
14
-      - capabilities list
15
-barbican:
16
-    name: Key Manager service (barbican)
17
-    subcommands: complete
18
-ceilometer:
19
-    name: Telemetry Data Collection service (ceilometer)
20
-cinder:
21
-    name: Block Storage service (cinder)
22
-cloudkitty:
23
-    name: Rating service (cloudkitty)
24
-congress:
25
-    name: Governance service (congress)
26
-designate:
27
-    name: DNS service (designate)
28
-    subcommands: complete
29
-freezer:
30
-    name: Backup, Restore, and Disaster Recovery service (freezer)
31
-glance:
32
-    name: Image service (glance)
33
-gnocchi:
34
-    name: A time series storage and resources index service (gnocchi)
35
-    subcommands:
36
-      - archive-policy create
37
-      - archive-policy delete
38
-      - archive-policy list
39
-      - archive-policy show
40
-      - archive-policy update
41
-      - archive-policy-rule create
42
-      - archive-policy-rule delete
43
-      - archive-policy-rule list
44
-      - archive-policy-rule show
45
-      - benchmark measures add
46
-      - benchmark measures show
47
-      - benchmark metric create
48
-      - benchmark metric show
49
-      - capabilities list
50
-      - complete
51
-      - help
52
-      - measures add
53
-      - measures aggregation
54
-      - measures batch-metrics
55
-      - measures batch-resources-metrics
56
-      - measures show
57
-      - metric create
58
-      - metric delete
59
-      - metric list
60
-      - metric show
61
-      - resource batch delete
62
-      - resource create
63
-      - resource delete
64
-      - resource history
65
-      - resource list
66
-      - resource show
67
-      - resource update
68
-      - resource-type create
69
-      - resource-type delete
70
-      - resource-type list
71
-      - resource-type show
72
-      - resource-type update
73
-      - status
74
-heat:
75
-    name: Orchestration service (heat)
76
-ironic:
77
-    name: Bare Metal service (ironic)
78
-kite:
79
-    name: A service for managing and distributing message encryption keys (kite)
80
-magnum:
81
-    name: Container Infrastructure Management service (magnum)
82
-manila:
83
-    name: Shared File Systems service (manila)
84
-mistral:
85
-    name: Workflow service (mistral)
86
-    subcommands: complete
87
-monasca:
88
-    name: Monitoring (monasca)
89
-murano:
90
-    name: Application Catalog service (murano)
91
-neutron:
92
-    name: Networking service (neutron)
93
-nova:
94
-    name: Compute service (nova)
95
-senlin:
96
-    name: Clustering service (senlin)
97
-solum:
98
-    name: Software Development Lifecycle Automation service (solum)
99
-swift:
100
-    name: Object Storage service (swift)
101
-    subcommands:
102
-      - auth
103
-      - capabilities
104
-      - delete
105
-      - download
106
-      - list
107
-      - post
108
-      - stat
109
-      - tempurl
110
-      - upload
111
-tacker:
112
-    name: NFV Orchestration service (tacker)
113
-tripleo:
114
-    name: Deployment service (tripleo)
115
-trove:
116
-    name: Database service (trove)
117
-trove-manage:
118
-    name: Database service management utility
119
-    subcommands:
120
-      - datastore_update
121
-      - datastore_version_flavor_add
122
-      - datastore_version_flavor_delete
123
-      - datastore_version_update
124
-      - db_downgrade
125
-      - db_load_datastore_config_parameters
126
-      - db_recreate
127
-      - db_sync
128
-      - db_upgrade
129
-vitrage:
130
-    name: RCA (Root Cause Analysis) service (vitrage)
131
-watcher:
132
-    name: Infrastructure Optimization service (watcher)
133
-zaqar:
134
-    name: Message service (zaqar)

+ 6
- 0
releasenotes/notes/the-great-doc-tools-cleanup-1a79e2c200232489.yaml View File

@@ -6,3 +6,9 @@ upgrade:
6 6
     ``oslo_config.sphinxext`` `Sphinx extension`__.
7 7
 
8 8
     __ https://docs.openstack.org/oslo.config/latest/reference/sphinxext.html
9
+  - |
10
+    The ``openstack-auto-commands`` command and its helper script in
11
+    ``bin/doc-tools-update-cli-reference`` have been removed. These have been
12
+    superseded by the ``cliff.sphinxext`` `Sphinx extensions`__.
13
+
14
+    __ https://docs.openstack.org/cliff/latest/user/sphinxext.html

+ 0
- 2
setup.cfg View File

@@ -27,7 +27,6 @@ data_files =
27 27
     share/openstack-doc-tools/cleanup = cleanup/*
28 28
 scripts =
29 29
     bin/doc-tools-check-languages
30
-    bin/doc-tools-update-cli-reference
31 30
     bin/doc-tools-build-rst
32 31
 
33 32
 [global]
@@ -36,7 +35,6 @@ setup-hooks =
36 35
 
37 36
 [entry_points]
38 37
 console_scripts =
39
-     openstack-auto-commands = os_doc_tools.commands:main
40 38
      openstack-jsoncheck = os_doc_tools.jsoncheck:main
41 39
      openstack-indexpage = os_doc_tools.index:main
42 40
 

Loading…
Cancel
Save