You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
## Overview
This PR adds support for configuring the `pretty` option at the
individual documentation block level, allowing users to override the
global setting on a case-by-case basis. It also includes updates to the
project version (0.1.4) and comprehensive documentation of changes in
the CHANGELOG.
## Changes
- Added version 0.1.4 to the CHANGELOG with detailed entries
- Enhanced the `TyperProcessor.run()` method to support per-block
configuration for the `pretty` option
- Improved boolean parsing for the pretty option to properly handle
string values like "true", "false", "1", "0", etc.
- Added comprehensive tests with parameterized test cases to verify all
combinations of global and block-level settings
- Updated documentation to reflect new capabilities
## Implementation Details
The implementation properly prioritizes block-level settings over global
settings:
- The global setting is used as the default
- If a block includes a `:pretty:` directive, it overrides the global
setting
- The block-level setting properly handles different boolean-like string
values
## Testing
- Added a new parameterized test case
`test_typer_processor_pretty_option` to verify all combinations of
global and block-level pretty settings
- All 26 tests are now passing with 97% coverage
- Manually verified the functionality by running the MkDocs server and
checking the documentation output
## Other Notes
The changes are backward compatible with existing documentation and do
not affect previous functionality. Users can continue using the global
setting or now opt to override it in specific documentation blocks as
needed.
A MkDocs plugin that automatically generates beautiful documentation for your Typer CLI applications.
14
12
15
-
You might be wondering why there are two plugins for Typer. The [`mkdocs-typer`](https://github.com/bruce-szalwinski/mkdocs-typer) plugin is great, but it hasn't been updated in over a year, and there have been a number of changes to Typer since then. One important change is that Typer now has it's own documentation generation system via the `typer <module> utils docs` command. This plugin simply leverages that system to generate the documentation for your Typer CLIs.
13
+
You might be wondering why there are two plugins for Typer. The [`mkdocs-typer`](https://github.com/bruce-szalwinski/mkdocs-typer) plugin is great, but it hasn't been updated in over a year, and there have been a number of changes to Typer since then. One important change is that Typer now has its own documentation generation system via the `typer <module> utils docs` command. This plugin simply leverages that system to generate the documentation for your Typer CLIs.
16
14
17
-
I created this plugin because the original plugin was no longer working for me, and I wanted to have a simple plugin that would work with the latest version of Typer. If the original `mkdocs-typer` plugin still works for you, there probably isn't a reason to switch. However, if you are looking for a plugin that will work with the latest version of Typer, this plugin is for you!
15
+
I created this plugin because the original plugin was no longer working for me, and I wanted to have a simple plugin that would work with the latest version of Typer. If the original `mkdocs-typer` plugin still works for you, there probably isn't a reason to switch. However, if you are looking for a plugin that will work with the latest version of Typer, this plugin is for you!
18
16
19
17
-[Read The Docs](https://syn54x.github.io/mkdocs-typer2/)
20
18
-[Check out a demo](https://syn54x.github.io/mkdocs-typer2/cli)
@@ -25,6 +23,19 @@ I created this plugin because the original plugin was no longer working for me,
25
23
- Automatically generates CLI documentation from your Typer commands
26
24
- Supports all Typer command features including arguments, options, and help text
27
25
- Easy to configure and use
26
+
-`pretty` feature for encapsulating arguments & options inside tables instead of lists
27
+
- Global plugin configuration or per-documentation block configuration
28
+
29
+
## How It Works
30
+
31
+
The plugin leverages Typer's built-in documentation generation via the `typer <module> utils docs` command to create Markdown documentation. It then processes this Markdown content and integrates it into your MkDocs site.
32
+
33
+
The plugin works by:
34
+
35
+
1. Registering a Markdown extension that processes special directive blocks
36
+
2. Running the Typer documentation command on your specified module
37
+
3. Optionally reformatting the output to use tables for arguments and options (the "pretty" mode)
38
+
4. Integrating the resulting HTML into your MkDocs site
28
39
29
40
## Installation
30
41
@@ -34,37 +45,89 @@ Install using pip:
34
45
pip install mkdocs-typer2
35
46
```
36
47
37
-
## Usage
48
+
### Requirements
49
+
50
+
- Python 3.10 or higher
51
+
- MkDocs 1.6.1 or higher
52
+
- Typer 0.12.5 or higher
53
+
- Pydantic 2.9.2 or higher
54
+
55
+
## Configuration
38
56
39
-
1. Add the plugin to your `mkdocs.yml` file:
57
+
### Basic Configuration
58
+
59
+
Add the plugin to your `mkdocs.yml` file:
40
60
41
61
```yaml
42
62
plugins:
43
63
- mkdocs-typer2
44
64
```
45
65
46
-
The plugin offers a `pretty` option that can be set in your `mkdocs.yml` file to enable pretty documentation. This will use markdown tables to format the CLI options and arguments instead of lists.
66
+
### Pretty Mode
67
+
68
+
The plugin offers a `pretty` option that can be set in your `mkdocs.yml` file to enable pretty documentation. This will use markdown tables to format the CLI options and arguments instead of lists:
47
69
48
70
```yaml
49
71
plugins:
50
72
- mkdocs-typer2:
51
73
pretty: true
52
74
```
53
75
54
-
2. In your Markdown files, use the `:::typer` directive to generate documentation for your Typer CLI
76
+
## Usage
77
+
78
+
### Basic Usage
79
+
80
+
In your Markdown files, use the `::: mkdocs-typer2` directive to generate documentation for your Typer CLI:
55
81
56
82
```markdown
57
83
::: mkdocs-typer2
58
84
:module: my_module
59
85
:name: mycli
60
86
```
61
87
62
-
- The `:module:` option is required and specifies the module containing your Typer CLI application. This is the *installed* module, not the directory. I.e: If you app is located in `src/my_module/cli.py`, your `:module:` should typically be `my_module.cli`.
63
-
- The `:name:` option is optional and specifies the name of the CLI. If left blank, your CLI will simply be named `CLI` in your documentation.
88
+
### Required Parameters
89
+
90
+
- `:module:`- The module containing your Typer CLI application. This is the *installed* module, not the directory path. For example, if your app is located in `src/my_module/cli.py`, your `:module:` should typically be `my_module.cli`.
91
+
92
+
### Optional Parameters
93
+
94
+
- `:name:`- The name of the CLI. If left blank, your CLI will simply be named `CLI` in your documentation.
95
+
- `:pretty:`- Set to `true` to enable pretty formatting for this specific documentation block, overriding the global setting.
96
+
97
+
## Advanced Usage
98
+
99
+
### Per-Block Pretty Configuration
100
+
101
+
You can override the global pretty setting for individual documentation blocks:
102
+
103
+
```markdown
104
+
::: mkdocs-typer2
105
+
:module: my_module.cli
106
+
:name: mycli
107
+
:pretty: true
108
+
```
109
+
110
+
### Multiple CLI Documentation
111
+
112
+
You can document multiple CLIs in the same MkDocs site by using multiple directive blocks:
113
+
114
+
```markdown
115
+
# Main CLI
116
+
117
+
::: mkdocs-typer2
118
+
:module: my_module.cli
119
+
:name: mycli
120
+
121
+
# Admin CLI
122
+
123
+
::: mkdocs-typer2
124
+
:module: my_module.admin
125
+
:name: admin-cli
126
+
```
64
127
65
128
## Example
66
129
67
-
This repository is a good example of how to use the plugin. We have a simple CLI located in `src/mkdocs_typer2/cli.py`.
130
+
This repository is a good example of how to use the plugin. We have a simple CLI located in `src/mkdocs_typer2/cli.py`.
68
131
69
132
The CLI's documentation is automatically generated using the block level directive in `docs/cli.md`:
70
133
@@ -73,3 +136,20 @@ The CLI's documentation is automatically generated using the block level directi
73
136
:module: mkdocs_typer2.cli
74
137
:name: mkdocs-typer2
75
138
```
139
+
140
+
And the pretty version in `docs/cli-pretty.md`:
141
+
142
+
```markdown
143
+
::: mkdocs-typer2
144
+
:module: mkdocs_typer2.cli
145
+
:name: mkdocs-typer2
146
+
:pretty: true
147
+
```
148
+
149
+
## Contributing
150
+
151
+
Contributions are welcome! Please feel free to submit a Pull Request.
152
+
153
+
## License
154
+
155
+
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
0 commit comments