Skip to content

Task2md

cli()

A CLI tool to generate markdown documentation files from Task files.

Source code in src/task2md/task2md.py 
10
11
12
13
@click.group()
@click.version_option("1.2.0", prog_name="task2md")
def cli() -> None:
    """A CLI tool to generate markdown documentation files from Task files."""

dir_command(input_dir, output_dir)

Command to generate a markdown documentation file from a directory.

Raises:

Type Description
ClickException

Error when reading input file or writing output file
Source code in src/task2md/task2md.py 
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
@cli.command("dir")
@click.option(
    "-i",
    "--input",
    "input_dir",
    type=click.Path(exists=True, file_okay=False, dir_okay=True, path_type=Path),
    required=True,
    help="Input directory",
)
@click.option(
    "-d",
    "--dir",
    "output_dir",
    type=click.Path(
        exists=False, file_okay=False, dir_okay=True, writable=True, path_type=Path
    ),
    required=False,
    help="Output markdown documentation files directory. Default current directory.",
)
def dir_command(
    input_dir: Path,
    output_dir: Path | None,
) -> None:
    """Command to generate a markdown documentation file from a directory.

    Raises:
        click.ClickException: Error when reading input file or writing output file
    """
    task_files: list[str] = [
        entry.name
        for entry in input_dir.iterdir()
        if entry.name.endswith((".yml", ".yaml"))
    ]

    if len(task_files) == 0:
        click.echo(f"No yaml file found in: {input_dir}")
    else:
        try:
            out_dir = Dir(output_dir, True)

        except OSError as error:
            raise click.ClickException(
                "Output directory can not be created!\n" + str(error)
            ) from error

        # A single unreadable Taskfile must not deprive the whole directory of
        # its documentation: report it, skip it, keep going, and fail at the end.
        failures: list[str] = []
        index_file = Index()
        for filename in task_files:
            task_file = File(path=str(input_dir / filename))
            try:
                task_file.generate(out_dir)
            except (OSError, ValueError) as error:
                failures.append(filename)
                click.echo(
                    f"Error on reading or writing file {filename} :\n {error!s}",
                    err=True,
                )
                continue

            index_file.task_files.append(task_file)
            click.echo(f"Task documentation generated: {task_file.get_filename()}.md")

        try:
            index_file.task_files.sort()
            index_file.generate(out_dir)
            click.echo("Index documentation generated: index.md")

        except OSError as error:
            raise click.ClickException(
                f"Error on writing file index.md :\n {error!s}"
            ) from error

        if failures:
            raise click.ClickException(
                f"{len(failures)} file(s) could not be processed: {', '.join(failures)}"
            )

file(input_file, output_dir)

Command to generate a markdown documentation file from a Task file.

Raises:

Type Description
ClickException

Error when reading input file or writing output file
Source code in src/task2md/task2md.py 
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
@cli.command()
@click.option(
    "-i",
    "--input",
    "input_file",
    type=click.Path(exists=True, file_okay=True, dir_okay=False, path_type=Path),
    required=True,
    help="Input Task yaml file.",
)
@click.option(
    "-d",
    "--dir",
    "output_dir",
    type=click.Path(
        exists=False, file_okay=False, dir_okay=True, writable=True, path_type=Path
    ),
    required=False,
    help="Output markdown documentation files directory. Default current directory.",
)
def file(
    input_file: Path,
    output_dir: Path | None,
) -> None:
    """Command to generate a markdown documentation file from a Task file.

    Raises:
        click.ClickException: Error when reading input file or writing output file
    """
    task_file = File(path=str(input_file))

    try:
        out_dir = Dir(output_dir, True)

    except OSError as error:
        raise click.ClickException(
            "Output directory can not be created!\n" + str(error)
        ) from error

    try:
        task_file.generate(out_dir)

        click.echo(f"Task documentation generated: {task_file.get_filename()}.md")

    except ValueError as ve:
        raise click.ClickException(
            f"Error on reading file {input_file} :\n {ve!s}"
        ) from ve