|
1
|
|
|
import logging |
|
2
|
|
|
import os |
|
3
|
|
|
from typing import Callable |
|
4
|
|
|
|
|
5
|
|
|
from menderbot.code import LANGUAGE_STRATEGIES, node_start_line, node_str |
|
6
|
|
|
from menderbot.source_file import Insertion, SourceFile |
|
7
|
|
|
|
|
8
|
|
|
logger = logging.getLogger("doc") |
|
9
|
|
|
|
|
10
|
|
|
|
|
11
|
|
|
def init_logging() -> None: |
|
12
|
|
|
""" |
|
13
|
|
|
Initializes the logging module. |
|
14
|
|
|
""" |
|
15
|
|
|
logger.setLevel(logging.DEBUG) |
|
16
|
|
|
# create console handler with a higher log level |
|
17
|
|
|
stream_handler = logging.StreamHandler() |
|
18
|
|
|
stream_handler.setLevel(logging.INFO) |
|
19
|
|
|
logger.addHandler(stream_handler) |
|
20
|
|
|
|
|
21
|
|
|
|
|
22
|
|
|
init_logging() |
|
23
|
|
|
|
|
24
|
|
|
|
|
25
|
|
|
def document_file(source_file: SourceFile, doc_gen: Callable) -> list[Insertion]: |
|
26
|
|
|
""" |
|
27
|
|
|
Generates documentation for functions in the sourcefile that don't have it |
|
28
|
|
|
using the supplied `doc_gen` callable. |
|
29
|
|
|
|
|
30
|
|
|
Return a list of insertions which the caller can use to update the file. |
|
31
|
|
|
|
|
32
|
|
|
If the file extension has no language strategy, the function logs a message and returns an empty list. |
|
33
|
|
|
""" |
|
34
|
|
|
path = source_file.path |
|
35
|
|
|
logger.info('Processing "%s"...', path) |
|
36
|
|
|
_, file_extension = os.path.splitext(path) |
|
37
|
|
|
language_strategy = LANGUAGE_STRATEGIES.get(file_extension) |
|
38
|
|
|
if not language_strategy: |
|
39
|
|
|
logger.info('Unrecognized extension "%s", skipping.', file_extension) |
|
40
|
|
|
return [] |
|
41
|
|
|
|
|
42
|
|
|
source = source_file.load_source_as_utf8() |
|
43
|
|
|
tree = language_strategy.parse_source_to_tree(source) |
|
44
|
|
|
insertions = [] |
|
45
|
|
|
for node in language_strategy.get_function_nodes(tree): |
|
46
|
|
|
if not language_strategy.function_has_comment(node): |
|
47
|
|
|
name = language_strategy.get_function_node_name(node) |
|
48
|
|
|
logger.info('Found undocumented function "%s"', name) |
|
49
|
|
|
code = node_str(node) |
|
50
|
|
|
comment = doc_gen(code, file_extension) |
|
51
|
|
|
function_start_line = node_start_line(node) |
|
52
|
|
|
doc_start_line = ( |
|
53
|
|
|
function_start_line + language_strategy.function_doc_line_offset |
|
54
|
|
|
) |
|
55
|
|
|
if comment: |
|
56
|
|
|
logger.info("Documenting with: %s", comment) |
|
57
|
|
|
logger.info("For code: %s", code) |
|
58
|
|
|
insertions.append( |
|
59
|
|
|
Insertion(text=comment, line_number=doc_start_line, label=name) |
|
60
|
|
|
) |
|
61
|
|
|
return insertions |
|
62
|
|
|
|
craftvscruft /
menderbot
