Book a Demo!
CoCalc Logo Icon
StoreFeaturesDocsShareSupportNewsAboutPoliciesSign UpSign In
aws
GitHub Repository: aws/aws-cli
 Path: blob/develop/awscli/customizations/addexamples.py
1566 views
1
# Copyright 2013 Amazon.com, Inc. or its affiliates. All Rights Reserved.

2
#

3
# Licensed under the Apache License, Version 2.0 (the "License"). You

4
# may not use this file except in compliance with the License. A copy of

5
# the License is located at

6
#

7
#     http://aws.amazon.com/apache2.0/

8
#

9
# or in the "license" file accompanying this file. This file is

10
# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF

11
# ANY KIND, either express or implied. See the License for the specific

12
# language governing permissions and limitations under the License.

13
"""

14
Add authored examples to MAN and HTML documentation

15
---------------------------------------------------

16


17
This customization allows authored examples in ReST format to be

18
inserted into the generated help for an Operation.  To get this to

19
work you need to:

20


21
* Register the ``add_examples`` function below with the

22
  ``doc-examples.*.*`` event.

23
* Create a file containing ReST format fragment with the examples.

24
  The file needs to be created in the ``examples/<service_name>``

25
  directory and needs to be named ``<service_name>-<op_name>.rst``.

26
  For example, ``examples/ec2/ec2-create-key-pair.rst``.

27


28
"""

29
import os

30
import logging

31


32


33
LOG = logging.getLogger(__name__)

34


35


36
def add_examples(help_command, **kwargs):

37
    doc_path = os.path.join(

38
        os.path.dirname(

39
            os.path.dirname(

40
                os.path.abspath(__file__))), 'examples')

41
    doc_path = os.path.join(doc_path,

42
                            help_command.event_class.replace('.', os.path.sep))

43
    doc_path = doc_path + '.rst'

44
    LOG.debug("Looking for example file at: %s", doc_path)

45
    if os.path.isfile(doc_path):

46
        help_command.doc.style.h2('Examples')

47
        help_command.doc.style.start_note()

48
        msg = ("<p>To use the following examples, you must have the AWS "

49
               "CLI installed and configured. See the "

50
               "<a href='https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-quickstart.html'>"

51
               "Getting started guide</a> in the <i>AWS CLI User Guide</i> "

52
               "for more information.</p>"

53
               "<p>Unless otherwise stated, all examples have unix-like "

54
               "quotation rules. These examples will need to be adapted "

55
               "to your terminal's quoting rules. See "

56
               "<a href='https://docs.aws.amazon.com/cli/v1/userguide/cli-usage-parameters-quoting-strings.html'>"

57
               "Using quotation marks with strings</a> "

58
               "in the <i>AWS CLI User Guide</i>.</p>")

59
        help_command.doc.include_doc_string(msg)

60
        help_command.doc.style.end_note()

61
        fp = open(doc_path)

62
        for line in fp.readlines():

63
            help_command.doc.write(line)

64


65