1# coding=utf-8
2# SPDX-License-Identifier: GPL-2.0
3#
4u"""
5    kernel-feat
6    ~~~~~~~~~~~
7
8    Implementation of the ``kernel-feat`` reST-directive.
9
10    :copyright:  Copyright (C) 2016  Markus Heiser
11    :copyright:  Copyright (C) 2016-2019  Mauro Carvalho Chehab
12    :maintained-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
13    :license:    GPL Version 2, June 1991 see Linux/COPYING for details.
14
15    The ``kernel-feat`` (:py:class:`KernelFeat`) directive calls the
16    scripts/get_feat.pl script to parse the Kernel ABI files.
17
18    Overview of directive's argument and options.
19
20    .. code-block:: rst
21
22        .. kernel-feat:: <ABI directory location>
23            :debug:
24
25    The argument ``<ABI directory location>`` is required. It contains the
26    location of the ABI files to be parsed.
27
28    ``debug``
29      Inserts a code-block with the *raw* reST. Sometimes it is helpful to see
30      what reST is generated.
31
32"""
33
34import codecs
35import os
36import subprocess
37import sys
38
39from os import path
40
41from docutils import nodes, statemachine
42from docutils.statemachine import ViewList
43from docutils.parsers.rst import directives, Directive
44from docutils.utils.error_reporting import ErrorString
45from sphinx.util.docutils import switch_source_input
46
47__version__  = '1.0'
48
49def setup(app):
50
51    app.add_directive("kernel-feat", KernelFeat)
52    return dict(
53        version = __version__
54        , parallel_read_safe = True
55        , parallel_write_safe = True
56    )
57
58class KernelFeat(Directive):
59
60    u"""KernelFeat (``kernel-feat``) directive"""
61
62    required_arguments = 1
63    optional_arguments = 2
64    has_content = False
65    final_argument_whitespace = True
66
67    option_spec = {
68        "debug"     : directives.flag
69    }
70
71    def warn(self, message, **replace):
72        replace["fname"]   = self.state.document.current_source
73        replace["line_no"] = replace.get("line_no", self.lineno)
74        message = ("%(fname)s:%(line_no)s: [kernel-feat WARN] : " + message) % replace
75        self.state.document.settings.env.app.warn(message, prefix="")
76
77    def run(self):
78
79        doc = self.state.document
80        if not doc.settings.file_insertion_enabled:
81            raise self.warning("docutils: file insertion disabled")
82
83        env = doc.settings.env
84        cwd = path.dirname(doc.current_source)
85        cmd = "get_feat.pl rest --dir "
86        cmd += self.arguments[0]
87
88        if len(self.arguments) > 1:
89            cmd += " --arch " + self.arguments[1]
90
91        srctree = path.abspath(os.environ["srctree"])
92
93        fname = cmd
94
95        # extend PATH with $(srctree)/scripts
96        path_env = os.pathsep.join([
97            srctree + os.sep + "scripts",
98            os.environ["PATH"]
99        ])
100        shell_env = os.environ.copy()
101        shell_env["PATH"]    = path_env
102        shell_env["srctree"] = srctree
103
104        lines = self.runCmd(cmd, shell=True, cwd=cwd, env=shell_env)
105        nodeList = self.nestedParse(lines, fname)
106        return nodeList
107
108    def runCmd(self, cmd, **kwargs):
109        u"""Run command ``cmd`` and return its stdout as unicode."""
110
111        try:
112            proc = subprocess.Popen(
113                cmd
114                , stdout = subprocess.PIPE
115                , stderr = subprocess.PIPE
116                , **kwargs
117            )
118            out, err = proc.communicate()
119
120            out, err = codecs.decode(out, 'utf-8'), codecs.decode(err, 'utf-8')
121
122            if proc.returncode != 0:
123                raise self.severe(
124                    u"command '%s' failed with return code %d"
125                    % (cmd, proc.returncode)
126                )
127        except OSError as exc:
128            raise self.severe(u"problems with '%s' directive: %s."
129                              % (self.name, ErrorString(exc)))
130        return out
131
132    def nestedParse(self, lines, fname):
133        content = ViewList()
134        node    = nodes.section()
135
136        if "debug" in self.options:
137            code_block = "\n\n.. code-block:: rst\n    :linenos:\n"
138            for l in lines.split("\n"):
139                code_block += "\n    " + l
140            lines = code_block + "\n\n"
141
142        for c, l in enumerate(lines.split("\n")):
143            content.append(l, fname, c)
144
145        buf  = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
146
147        with switch_source_input(self.state, content):
148            self.state.nested_parse(content, 0, node, match_titles=1)
149
150        return node.children
151