docs-output-filter 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- docs_output_filter-0.1.0/.gitignore +42 -0
- docs_output_filter-0.1.0/LICENSE +21 -0
- docs_output_filter-0.1.0/PKG-INFO +213 -0
- docs_output_filter-0.1.0/README.md +188 -0
- docs_output_filter-0.1.0/pyproject.toml +104 -0
- docs_output_filter-0.1.0/src/docs_output_filter/__init__.py +108 -0
- docs_output_filter-0.1.0/src/docs_output_filter/__main__.py +7 -0
- docs_output_filter-0.1.0/src/docs_output_filter/backends/__init__.py +97 -0
- docs_output_filter-0.1.0/src/docs_output_filter/backends/mkdocs.py +370 -0
- docs_output_filter-0.1.0/src/docs_output_filter/backends/sphinx.py +432 -0
- docs_output_filter-0.1.0/src/docs_output_filter/cli.py +193 -0
- docs_output_filter-0.1.0/src/docs_output_filter/display.py +383 -0
- docs_output_filter-0.1.0/src/docs_output_filter/mcp_server.py +835 -0
- docs_output_filter-0.1.0/src/docs_output_filter/modes.py +590 -0
- docs_output_filter-0.1.0/src/docs_output_filter/processor.py +278 -0
- docs_output_filter-0.1.0/src/docs_output_filter/remote.py +81 -0
- docs_output_filter-0.1.0/src/docs_output_filter/state.py +334 -0
- docs_output_filter-0.1.0/src/docs_output_filter/types.py +113 -0
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# Byte-compiled / optimized / DLL files
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*$py.class
|
|
5
|
+
|
|
6
|
+
# Distribution / packaging
|
|
7
|
+
dist/
|
|
8
|
+
build/
|
|
9
|
+
*.egg-info/
|
|
10
|
+
|
|
11
|
+
# Virtual environments
|
|
12
|
+
.venv/
|
|
13
|
+
venv/
|
|
14
|
+
ENV/
|
|
15
|
+
|
|
16
|
+
# IDE
|
|
17
|
+
.idea/
|
|
18
|
+
.vscode/
|
|
19
|
+
*.swp
|
|
20
|
+
*.swo
|
|
21
|
+
|
|
22
|
+
# Testing
|
|
23
|
+
.pytest_cache/
|
|
24
|
+
.coverage
|
|
25
|
+
htmlcov/
|
|
26
|
+
|
|
27
|
+
# mkdocs test sites
|
|
28
|
+
tests/fixtures/*/.site/
|
|
29
|
+
tests/fixtures/*/site/
|
|
30
|
+
|
|
31
|
+
# mkdocs build output
|
|
32
|
+
site/
|
|
33
|
+
|
|
34
|
+
# mkdocs-output-filter state files
|
|
35
|
+
.mkdocs-output-filter/
|
|
36
|
+
|
|
37
|
+
# OS
|
|
38
|
+
.DS_Store
|
|
39
|
+
Thumbs.db
|
|
40
|
+
|
|
41
|
+
# uv
|
|
42
|
+
uv.lock
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,213 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: docs-output-filter
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Filter documentation build output (MkDocs, Sphinx) to show only warnings and errors with nice formatting
|
|
5
|
+
Project-URL: Homepage, https://github.com/ianhi/docs-output-filter
|
|
6
|
+
Project-URL: Repository, https://github.com/ianhi/docs-output-filter
|
|
7
|
+
Author-email: Ian <ian@example.com>
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Keywords: cli,documentation,filter,mkdocs,sphinx
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Environment :: Console
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Topic :: Documentation
|
|
19
|
+
Classifier: Topic :: Utilities
|
|
20
|
+
Requires-Python: >=3.11
|
|
21
|
+
Requires-Dist: click!=8.3.0,!=8.3.1
|
|
22
|
+
Requires-Dist: mcp>=1.26.0
|
|
23
|
+
Requires-Dist: rich>=13.0.0
|
|
24
|
+
Description-Content-Type: text/markdown
|
|
25
|
+
|
|
26
|
+
# docs-output-filter
|
|
27
|
+
|
|
28
|
+
**Filter documentation build output to show only what matters: warnings and errors.**
|
|
29
|
+
|
|
30
|
+
Works with **MkDocs** and **Sphinx** (including sphinx-autobuild, Jupyter Book, myst-nb). Includes an MCP server for AI code assistant integration (Claude Code, etc.).
|
|
31
|
+
|
|
32
|
+
## Before & After
|
|
33
|
+
|
|
34
|
+
<table>
|
|
35
|
+
<tr>
|
|
36
|
+
<th>❌ Raw build output (43 lines)</th>
|
|
37
|
+
<th>✅ Filtered output (15 lines)</th>
|
|
38
|
+
</tr>
|
|
39
|
+
<tr>
|
|
40
|
+
<td>
|
|
41
|
+
|
|
42
|
+
```
|
|
43
|
+
INFO - Building documentation...
|
|
44
|
+
INFO - Cleaning site directory
|
|
45
|
+
INFO - Log level set to INFO
|
|
46
|
+
INFO - Building documentation to directory: /project/site
|
|
47
|
+
INFO - MERMAID2 - Initialization arguments: {}
|
|
48
|
+
INFO - Generating index pages...
|
|
49
|
+
INFO - Reading page 'index.md'
|
|
50
|
+
INFO - Reading page 'guide/getting-started.md'
|
|
51
|
+
INFO - Reading page 'guide/configuration.md'
|
|
52
|
+
INFO - Reading page 'api/reference.md'
|
|
53
|
+
INFO - Copying static files from theme: material
|
|
54
|
+
INFO - Copying 'assets/stylesheets/extra.css'
|
|
55
|
+
INFO - Copying 'assets/javascripts/extra.js'
|
|
56
|
+
[git-revision-date-localized-plugin] has no git logs
|
|
57
|
+
INFO - Executing code blocks with markdown_exec...
|
|
58
|
+
WARNING - markdown_exec: Execution of python
|
|
59
|
+
code block exited with errors
|
|
60
|
+
|
|
61
|
+
Code block is:
|
|
62
|
+
|
|
63
|
+
import numpy as np
|
|
64
|
+
data = np.random.rand(10, 10)
|
|
65
|
+
raise ValueError("INTENTIONAL TEST ERROR")
|
|
66
|
+
|
|
67
|
+
Output is:
|
|
68
|
+
|
|
69
|
+
Traceback (most recent call last):
|
|
70
|
+
File "<code block: session test; n1>", line 3
|
|
71
|
+
raise ValueError("INTENTIONAL TEST ERROR")
|
|
72
|
+
ValueError: INTENTIONAL TEST ERROR
|
|
73
|
+
|
|
74
|
+
WARNING - [git-revision] Unable to read git logs
|
|
75
|
+
INFO - Rendering 'index.md'
|
|
76
|
+
INFO - Rendering 'guide/getting-started.md'
|
|
77
|
+
INFO - Rendering 'guide/configuration.md'
|
|
78
|
+
INFO - Rendering 'api/reference.md'
|
|
79
|
+
INFO - Building search index...
|
|
80
|
+
INFO - Writing 'sitemap.xml'
|
|
81
|
+
INFO - Writing 'search/search_index.json'
|
|
82
|
+
INFO - Documentation built in 12.34 seconds
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
</td>
|
|
86
|
+
<td>
|
|
87
|
+
|
|
88
|
+
```
|
|
89
|
+
⚠ WARNING [markdown_exec] ValueError: INTENTIONAL TEST ERROR
|
|
90
|
+
📍 session 'test' → line 3
|
|
91
|
+
|
|
92
|
+
╭──────────────── Code Block ─────────────────╮
|
|
93
|
+
│ 1 import numpy as np │
|
|
94
|
+
│ 2 data = np.random.rand(10, 10) │
|
|
95
|
+
│ 3 raise ValueError("INTENTIONAL TEST E...")│
|
|
96
|
+
╰─────────────────────────────────────────────╯
|
|
97
|
+
╭─────────── Error Output ────────────╮
|
|
98
|
+
│ ValueError: INTENTIONAL TEST ERROR │
|
|
99
|
+
╰───────── use -v for full traceback ─╯
|
|
100
|
+
|
|
101
|
+
⚠ WARNING [git-revision] Unable to read git logs
|
|
102
|
+
|
|
103
|
+
Summary: 2 warning(s)
|
|
104
|
+
|
|
105
|
+
🌐 Server: http://127.0.0.1:8000/
|
|
106
|
+
📁 Output: /project/site
|
|
107
|
+
Built in 12.34s
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
</td>
|
|
111
|
+
</tr>
|
|
112
|
+
</table>
|
|
113
|
+
|
|
114
|
+
## Installation
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
# With uv (recommended)
|
|
118
|
+
uv tool install docs-output-filter
|
|
119
|
+
|
|
120
|
+
# With pip
|
|
121
|
+
pip install docs-output-filter
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
## Usage
|
|
125
|
+
|
|
126
|
+
```bash
|
|
127
|
+
# Wrapper mode (recommended) — just prefix your build command
|
|
128
|
+
docs-output-filter -- mkdocs build
|
|
129
|
+
docs-output-filter -- mkdocs serve --livereload
|
|
130
|
+
docs-output-filter -- sphinx-autobuild docs _build/html
|
|
131
|
+
|
|
132
|
+
# Pipe mode — traditional Unix pipe
|
|
133
|
+
mkdocs build 2>&1 | docs-output-filter
|
|
134
|
+
sphinx-build docs _build 2>&1 | docs-output-filter
|
|
135
|
+
|
|
136
|
+
# Process a remote build log (e.g., ReadTheDocs)
|
|
137
|
+
docs-output-filter --url https://app.readthedocs.org/projects/myproject/builds/12345/
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
> **Tip:** Wrapper mode (`--`) is the easiest way to use docs-output-filter. It runs the command for you, automatically captures both stdout and stderr, and fixes buffering issues with sphinx-autobuild. No `2>&1` needed.
|
|
141
|
+
|
|
142
|
+
> **Note:** If using pipe mode, `2>&1` is important — Sphinx writes warnings to stderr. Without it, warnings bypass the filter.
|
|
143
|
+
|
|
144
|
+
> **Note:** Use `--livereload` with `mkdocs serve` due to a [Click 8.3.x bug](https://github.com/mkdocs/mkdocs/issues/4032).
|
|
145
|
+
|
|
146
|
+
## Features
|
|
147
|
+
|
|
148
|
+
| Feature | Description |
|
|
149
|
+
|---------|-------------|
|
|
150
|
+
| **Multi-tool support** | MkDocs and Sphinx with auto-detection |
|
|
151
|
+
| **Filtered output** | Shows WARNING and ERROR messages, hides routine INFO |
|
|
152
|
+
| **Code blocks** | Syntax-highlighted code for markdown_exec and myst-nb errors |
|
|
153
|
+
| **Location info** | File, line number, session name, warning codes |
|
|
154
|
+
| **Streaming mode** | Real-time output for `mkdocs serve` / `sphinx-autobuild` with rebuild detection |
|
|
155
|
+
| **Interactive mode** | Toggle between raw/filtered with keyboard (`-i`) |
|
|
156
|
+
| **Remote logs** | Fetch and parse build logs from ReadTheDocs and other CI |
|
|
157
|
+
| **MCP server** | API for AI code assistants like Claude Code |
|
|
158
|
+
|
|
159
|
+
## Options
|
|
160
|
+
|
|
161
|
+
| Flag | Description |
|
|
162
|
+
|------|-------------|
|
|
163
|
+
| `-- COMMAND` | Run command as subprocess (recommended, no `2>&1` needed) |
|
|
164
|
+
| `-v, --verbose` | Show full tracebacks and code blocks |
|
|
165
|
+
| `-e, --errors-only` | Hide warnings, show only errors |
|
|
166
|
+
| `--no-color` | Disable colored output |
|
|
167
|
+
| `--raw` | Pass through unfiltered build output |
|
|
168
|
+
| `-i, --interactive` | Toggle raw/filtered with keyboard |
|
|
169
|
+
| `--url URL` | Fetch and process a remote build log |
|
|
170
|
+
| `--tool mkdocs\|sphinx\|auto` | Force build tool detection (default: auto) |
|
|
171
|
+
| `--share-state` | Write state for MCP server integration |
|
|
172
|
+
|
|
173
|
+
## MCP Server (for AI Assistants)
|
|
174
|
+
|
|
175
|
+
Enable AI code assistants to access build issues:
|
|
176
|
+
|
|
177
|
+
```bash
|
|
178
|
+
# Terminal 1: Run build tool with state sharing
|
|
179
|
+
mkdocs serve --livereload 2>&1 | docs-output-filter --share-state
|
|
180
|
+
|
|
181
|
+
# Terminal 2: AI assistant connects via MCP
|
|
182
|
+
docs-output-filter --mcp --watch
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
Add to Claude Code's MCP config (`.claude/settings.local.json`):
|
|
186
|
+
```json
|
|
187
|
+
{
|
|
188
|
+
"mcpServers": {
|
|
189
|
+
"docs-output-filter": {
|
|
190
|
+
"command": "docs-output-filter",
|
|
191
|
+
"args": ["--mcp", "--watch"]
|
|
192
|
+
}
|
|
193
|
+
}
|
|
194
|
+
}
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
## Documentation
|
|
198
|
+
|
|
199
|
+
Full documentation: https://ianhi.github.io/docs-output-filter/
|
|
200
|
+
|
|
201
|
+
## Development
|
|
202
|
+
|
|
203
|
+
```bash
|
|
204
|
+
git clone https://github.com/ianhi/docs-output-filter
|
|
205
|
+
cd docs-output-filter
|
|
206
|
+
uv sync
|
|
207
|
+
uv run pre-commit install
|
|
208
|
+
uv run pytest
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
## License
|
|
212
|
+
|
|
213
|
+
MIT
|
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
# docs-output-filter
|
|
2
|
+
|
|
3
|
+
**Filter documentation build output to show only what matters: warnings and errors.**
|
|
4
|
+
|
|
5
|
+
Works with **MkDocs** and **Sphinx** (including sphinx-autobuild, Jupyter Book, myst-nb). Includes an MCP server for AI code assistant integration (Claude Code, etc.).
|
|
6
|
+
|
|
7
|
+
## Before & After
|
|
8
|
+
|
|
9
|
+
<table>
|
|
10
|
+
<tr>
|
|
11
|
+
<th>❌ Raw build output (43 lines)</th>
|
|
12
|
+
<th>✅ Filtered output (15 lines)</th>
|
|
13
|
+
</tr>
|
|
14
|
+
<tr>
|
|
15
|
+
<td>
|
|
16
|
+
|
|
17
|
+
```
|
|
18
|
+
INFO - Building documentation...
|
|
19
|
+
INFO - Cleaning site directory
|
|
20
|
+
INFO - Log level set to INFO
|
|
21
|
+
INFO - Building documentation to directory: /project/site
|
|
22
|
+
INFO - MERMAID2 - Initialization arguments: {}
|
|
23
|
+
INFO - Generating index pages...
|
|
24
|
+
INFO - Reading page 'index.md'
|
|
25
|
+
INFO - Reading page 'guide/getting-started.md'
|
|
26
|
+
INFO - Reading page 'guide/configuration.md'
|
|
27
|
+
INFO - Reading page 'api/reference.md'
|
|
28
|
+
INFO - Copying static files from theme: material
|
|
29
|
+
INFO - Copying 'assets/stylesheets/extra.css'
|
|
30
|
+
INFO - Copying 'assets/javascripts/extra.js'
|
|
31
|
+
[git-revision-date-localized-plugin] has no git logs
|
|
32
|
+
INFO - Executing code blocks with markdown_exec...
|
|
33
|
+
WARNING - markdown_exec: Execution of python
|
|
34
|
+
code block exited with errors
|
|
35
|
+
|
|
36
|
+
Code block is:
|
|
37
|
+
|
|
38
|
+
import numpy as np
|
|
39
|
+
data = np.random.rand(10, 10)
|
|
40
|
+
raise ValueError("INTENTIONAL TEST ERROR")
|
|
41
|
+
|
|
42
|
+
Output is:
|
|
43
|
+
|
|
44
|
+
Traceback (most recent call last):
|
|
45
|
+
File "<code block: session test; n1>", line 3
|
|
46
|
+
raise ValueError("INTENTIONAL TEST ERROR")
|
|
47
|
+
ValueError: INTENTIONAL TEST ERROR
|
|
48
|
+
|
|
49
|
+
WARNING - [git-revision] Unable to read git logs
|
|
50
|
+
INFO - Rendering 'index.md'
|
|
51
|
+
INFO - Rendering 'guide/getting-started.md'
|
|
52
|
+
INFO - Rendering 'guide/configuration.md'
|
|
53
|
+
INFO - Rendering 'api/reference.md'
|
|
54
|
+
INFO - Building search index...
|
|
55
|
+
INFO - Writing 'sitemap.xml'
|
|
56
|
+
INFO - Writing 'search/search_index.json'
|
|
57
|
+
INFO - Documentation built in 12.34 seconds
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
</td>
|
|
61
|
+
<td>
|
|
62
|
+
|
|
63
|
+
```
|
|
64
|
+
⚠ WARNING [markdown_exec] ValueError: INTENTIONAL TEST ERROR
|
|
65
|
+
📍 session 'test' → line 3
|
|
66
|
+
|
|
67
|
+
╭──────────────── Code Block ─────────────────╮
|
|
68
|
+
│ 1 import numpy as np │
|
|
69
|
+
│ 2 data = np.random.rand(10, 10) │
|
|
70
|
+
│ 3 raise ValueError("INTENTIONAL TEST E...")│
|
|
71
|
+
╰─────────────────────────────────────────────╯
|
|
72
|
+
╭─────────── Error Output ────────────╮
|
|
73
|
+
│ ValueError: INTENTIONAL TEST ERROR │
|
|
74
|
+
╰───────── use -v for full traceback ─╯
|
|
75
|
+
|
|
76
|
+
⚠ WARNING [git-revision] Unable to read git logs
|
|
77
|
+
|
|
78
|
+
Summary: 2 warning(s)
|
|
79
|
+
|
|
80
|
+
🌐 Server: http://127.0.0.1:8000/
|
|
81
|
+
📁 Output: /project/site
|
|
82
|
+
Built in 12.34s
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
</td>
|
|
86
|
+
</tr>
|
|
87
|
+
</table>
|
|
88
|
+
|
|
89
|
+
## Installation
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
# With uv (recommended)
|
|
93
|
+
uv tool install docs-output-filter
|
|
94
|
+
|
|
95
|
+
# With pip
|
|
96
|
+
pip install docs-output-filter
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
## Usage
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
# Wrapper mode (recommended) — just prefix your build command
|
|
103
|
+
docs-output-filter -- mkdocs build
|
|
104
|
+
docs-output-filter -- mkdocs serve --livereload
|
|
105
|
+
docs-output-filter -- sphinx-autobuild docs _build/html
|
|
106
|
+
|
|
107
|
+
# Pipe mode — traditional Unix pipe
|
|
108
|
+
mkdocs build 2>&1 | docs-output-filter
|
|
109
|
+
sphinx-build docs _build 2>&1 | docs-output-filter
|
|
110
|
+
|
|
111
|
+
# Process a remote build log (e.g., ReadTheDocs)
|
|
112
|
+
docs-output-filter --url https://app.readthedocs.org/projects/myproject/builds/12345/
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
> **Tip:** Wrapper mode (`--`) is the easiest way to use docs-output-filter. It runs the command for you, automatically captures both stdout and stderr, and fixes buffering issues with sphinx-autobuild. No `2>&1` needed.
|
|
116
|
+
|
|
117
|
+
> **Note:** If using pipe mode, `2>&1` is important — Sphinx writes warnings to stderr. Without it, warnings bypass the filter.
|
|
118
|
+
|
|
119
|
+
> **Note:** Use `--livereload` with `mkdocs serve` due to a [Click 8.3.x bug](https://github.com/mkdocs/mkdocs/issues/4032).
|
|
120
|
+
|
|
121
|
+
## Features
|
|
122
|
+
|
|
123
|
+
| Feature | Description |
|
|
124
|
+
|---------|-------------|
|
|
125
|
+
| **Multi-tool support** | MkDocs and Sphinx with auto-detection |
|
|
126
|
+
| **Filtered output** | Shows WARNING and ERROR messages, hides routine INFO |
|
|
127
|
+
| **Code blocks** | Syntax-highlighted code for markdown_exec and myst-nb errors |
|
|
128
|
+
| **Location info** | File, line number, session name, warning codes |
|
|
129
|
+
| **Streaming mode** | Real-time output for `mkdocs serve` / `sphinx-autobuild` with rebuild detection |
|
|
130
|
+
| **Interactive mode** | Toggle between raw/filtered with keyboard (`-i`) |
|
|
131
|
+
| **Remote logs** | Fetch and parse build logs from ReadTheDocs and other CI |
|
|
132
|
+
| **MCP server** | API for AI code assistants like Claude Code |
|
|
133
|
+
|
|
134
|
+
## Options
|
|
135
|
+
|
|
136
|
+
| Flag | Description |
|
|
137
|
+
|------|-------------|
|
|
138
|
+
| `-- COMMAND` | Run command as subprocess (recommended, no `2>&1` needed) |
|
|
139
|
+
| `-v, --verbose` | Show full tracebacks and code blocks |
|
|
140
|
+
| `-e, --errors-only` | Hide warnings, show only errors |
|
|
141
|
+
| `--no-color` | Disable colored output |
|
|
142
|
+
| `--raw` | Pass through unfiltered build output |
|
|
143
|
+
| `-i, --interactive` | Toggle raw/filtered with keyboard |
|
|
144
|
+
| `--url URL` | Fetch and process a remote build log |
|
|
145
|
+
| `--tool mkdocs\|sphinx\|auto` | Force build tool detection (default: auto) |
|
|
146
|
+
| `--share-state` | Write state for MCP server integration |
|
|
147
|
+
|
|
148
|
+
## MCP Server (for AI Assistants)
|
|
149
|
+
|
|
150
|
+
Enable AI code assistants to access build issues:
|
|
151
|
+
|
|
152
|
+
```bash
|
|
153
|
+
# Terminal 1: Run build tool with state sharing
|
|
154
|
+
mkdocs serve --livereload 2>&1 | docs-output-filter --share-state
|
|
155
|
+
|
|
156
|
+
# Terminal 2: AI assistant connects via MCP
|
|
157
|
+
docs-output-filter --mcp --watch
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
Add to Claude Code's MCP config (`.claude/settings.local.json`):
|
|
161
|
+
```json
|
|
162
|
+
{
|
|
163
|
+
"mcpServers": {
|
|
164
|
+
"docs-output-filter": {
|
|
165
|
+
"command": "docs-output-filter",
|
|
166
|
+
"args": ["--mcp", "--watch"]
|
|
167
|
+
}
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
## Documentation
|
|
173
|
+
|
|
174
|
+
Full documentation: https://ianhi.github.io/docs-output-filter/
|
|
175
|
+
|
|
176
|
+
## Development
|
|
177
|
+
|
|
178
|
+
```bash
|
|
179
|
+
git clone https://github.com/ianhi/docs-output-filter
|
|
180
|
+
cd docs-output-filter
|
|
181
|
+
uv sync
|
|
182
|
+
uv run pre-commit install
|
|
183
|
+
uv run pytest
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
## License
|
|
187
|
+
|
|
188
|
+
MIT
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "docs-output-filter"
|
|
3
|
+
version = "0.1.0"
|
|
4
|
+
description = "Filter documentation build output (MkDocs, Sphinx) to show only warnings and errors with nice formatting"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
requires-python = ">=3.11"
|
|
7
|
+
license = "MIT"
|
|
8
|
+
authors = [
|
|
9
|
+
{ name = "Ian", email = "ian@example.com" }
|
|
10
|
+
]
|
|
11
|
+
keywords = ["mkdocs", "sphinx", "documentation", "cli", "filter"]
|
|
12
|
+
classifiers = [
|
|
13
|
+
"Development Status :: 4 - Beta",
|
|
14
|
+
"Environment :: Console",
|
|
15
|
+
"Intended Audience :: Developers",
|
|
16
|
+
"License :: OSI Approved :: MIT License",
|
|
17
|
+
"Programming Language :: Python :: 3",
|
|
18
|
+
"Programming Language :: Python :: 3.11",
|
|
19
|
+
"Programming Language :: Python :: 3.12",
|
|
20
|
+
"Topic :: Documentation",
|
|
21
|
+
"Topic :: Utilities",
|
|
22
|
+
]
|
|
23
|
+
dependencies = [
|
|
24
|
+
"click!=8.3.0,!=8.3.1",
|
|
25
|
+
"mcp>=1.26.0",
|
|
26
|
+
"rich>=13.0.0",
|
|
27
|
+
]
|
|
28
|
+
|
|
29
|
+
[project.scripts]
|
|
30
|
+
docs-output-filter = "docs_output_filter:main"
|
|
31
|
+
docs-output-filter-mcp = "docs_output_filter.mcp_server:main"
|
|
32
|
+
|
|
33
|
+
[project.urls]
|
|
34
|
+
Homepage = "https://github.com/ianhi/docs-output-filter"
|
|
35
|
+
Repository = "https://github.com/ianhi/docs-output-filter"
|
|
36
|
+
|
|
37
|
+
[build-system]
|
|
38
|
+
requires = ["hatchling"]
|
|
39
|
+
build-backend = "hatchling.build"
|
|
40
|
+
|
|
41
|
+
[tool.hatch.build.targets.wheel]
|
|
42
|
+
packages = ["src/docs_output_filter"]
|
|
43
|
+
|
|
44
|
+
[tool.hatch.build.targets.sdist]
|
|
45
|
+
include = [
|
|
46
|
+
"/src",
|
|
47
|
+
"/README.md",
|
|
48
|
+
"/LICENSE",
|
|
49
|
+
]
|
|
50
|
+
|
|
51
|
+
[tool.ruff]
|
|
52
|
+
line-length = 100
|
|
53
|
+
target-version = "py311"
|
|
54
|
+
|
|
55
|
+
[tool.ruff.lint]
|
|
56
|
+
select = [
|
|
57
|
+
"E", # pycodestyle errors
|
|
58
|
+
"W", # pycodestyle warnings
|
|
59
|
+
"F", # pyflakes
|
|
60
|
+
"I", # isort
|
|
61
|
+
"B", # flake8-bugbear
|
|
62
|
+
"UP", # pyupgrade
|
|
63
|
+
]
|
|
64
|
+
ignore = [
|
|
65
|
+
"E501", # line too long (handled by formatter)
|
|
66
|
+
]
|
|
67
|
+
|
|
68
|
+
[tool.ruff.lint.isort]
|
|
69
|
+
known-first-party = ["docs_output_filter"]
|
|
70
|
+
|
|
71
|
+
[dependency-groups]
|
|
72
|
+
dev = [
|
|
73
|
+
"markdown-exec>=1.12.1",
|
|
74
|
+
"mkdocs>=1.6.1",
|
|
75
|
+
"mkdocs-material>=9.7.1",
|
|
76
|
+
"mypy>=1.19.1",
|
|
77
|
+
"pre-commit>=4.5.1",
|
|
78
|
+
"pytest>=9.0.2",
|
|
79
|
+
"pytest-cov>=7.0.0",
|
|
80
|
+
"ruff>=0.15.0",
|
|
81
|
+
"sphinx>=7.0",
|
|
82
|
+
"sphinx-autobuild>=2024.0",
|
|
83
|
+
]
|
|
84
|
+
|
|
85
|
+
[tool.pytest.ini_options]
|
|
86
|
+
testpaths = ["tests"]
|
|
87
|
+
addopts = "-v"
|
|
88
|
+
|
|
89
|
+
[tool.coverage.run]
|
|
90
|
+
source = ["docs_output_filter"]
|
|
91
|
+
branch = true
|
|
92
|
+
|
|
93
|
+
[tool.coverage.report]
|
|
94
|
+
exclude_lines = [
|
|
95
|
+
"pragma: no cover",
|
|
96
|
+
"if __name__ == .__main__.:",
|
|
97
|
+
"raise NotImplementedError",
|
|
98
|
+
]
|
|
99
|
+
|
|
100
|
+
[tool.mypy]
|
|
101
|
+
python_version = "3.11"
|
|
102
|
+
warn_return_any = true
|
|
103
|
+
warn_unused_configs = true
|
|
104
|
+
ignore_missing_imports = true
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
"""Filter documentation build output to show only warnings and errors with nice formatting.
|
|
2
|
+
|
|
3
|
+
Supports both MkDocs and Sphinx builds. This is the package facade — all public
|
|
4
|
+
symbols are re-exported here for backward compatibility, but the implementation
|
|
5
|
+
lives in focused submodules:
|
|
6
|
+
|
|
7
|
+
- cli.py: Argument parsing and main() entry point
|
|
8
|
+
- display.py: Rich-based formatting (print_issue, print_summary, etc.)
|
|
9
|
+
- processor.py: StreamingProcessor for incremental parsing
|
|
10
|
+
- modes.py: Run modes (streaming, batch, interactive, URL, wrap)
|
|
11
|
+
- remote.py: Remote build log fetching (ReadTheDocs, etc.)
|
|
12
|
+
- types.py: Shared data types (Issue, BuildInfo, Level, etc.)
|
|
13
|
+
- state.py: State file I/O for MCP server integration
|
|
14
|
+
- backends/: Backend protocol and implementations (MkDocs, Sphinx)
|
|
15
|
+
- mcp_server.py: MCP server for code agent integration
|
|
16
|
+
|
|
17
|
+
Usage:
|
|
18
|
+
docs-output-filter -- mkdocs serve --livereload
|
|
19
|
+
mkdocs build 2>&1 | docs-output-filter
|
|
20
|
+
sphinx-build docs build 2>&1 | docs-output-filter -v
|
|
21
|
+
|
|
22
|
+
Update this docstring if you add new submodules or change the public API surface.
|
|
23
|
+
"""
|
|
24
|
+
|
|
25
|
+
from __future__ import annotations
|
|
26
|
+
|
|
27
|
+
from docs_output_filter.backends import Backend, BuildTool, detect_backend, get_backend
|
|
28
|
+
from docs_output_filter.backends.mkdocs import (
|
|
29
|
+
detect_chunk_boundary,
|
|
30
|
+
extract_build_info,
|
|
31
|
+
is_in_multiline_block,
|
|
32
|
+
parse_info_messages,
|
|
33
|
+
parse_markdown_exec_issue,
|
|
34
|
+
parse_mkdocs_output,
|
|
35
|
+
)
|
|
36
|
+
from docs_output_filter.cli import __version__, main
|
|
37
|
+
from docs_output_filter.display import (
|
|
38
|
+
DisplayMode,
|
|
39
|
+
print_info_groups,
|
|
40
|
+
print_issue,
|
|
41
|
+
print_summary,
|
|
42
|
+
)
|
|
43
|
+
from docs_output_filter.modes import run_wrap_mode
|
|
44
|
+
from docs_output_filter.processor import StreamingProcessor
|
|
45
|
+
from docs_output_filter.remote import fetch_remote_log
|
|
46
|
+
from docs_output_filter.state import (
|
|
47
|
+
StateFileData,
|
|
48
|
+
find_project_root,
|
|
49
|
+
get_state_file_path,
|
|
50
|
+
read_state_file,
|
|
51
|
+
write_state_file,
|
|
52
|
+
)
|
|
53
|
+
from docs_output_filter.types import (
|
|
54
|
+
BuildInfo,
|
|
55
|
+
ChunkBoundary,
|
|
56
|
+
InfoCategory,
|
|
57
|
+
InfoMessage,
|
|
58
|
+
Issue,
|
|
59
|
+
Level,
|
|
60
|
+
StreamingState,
|
|
61
|
+
dedent_code,
|
|
62
|
+
group_info_messages,
|
|
63
|
+
)
|
|
64
|
+
|
|
65
|
+
__all__ = [
|
|
66
|
+
# Data classes
|
|
67
|
+
"Level",
|
|
68
|
+
"Issue",
|
|
69
|
+
"BuildInfo",
|
|
70
|
+
"StreamingState",
|
|
71
|
+
"StateFileData",
|
|
72
|
+
"ChunkBoundary",
|
|
73
|
+
"DisplayMode",
|
|
74
|
+
"InfoCategory",
|
|
75
|
+
"InfoMessage",
|
|
76
|
+
# Backend system
|
|
77
|
+
"Backend",
|
|
78
|
+
"BuildTool",
|
|
79
|
+
"detect_backend",
|
|
80
|
+
"get_backend",
|
|
81
|
+
# Parsing functions (mkdocs - for backward compat)
|
|
82
|
+
"detect_chunk_boundary",
|
|
83
|
+
"is_in_multiline_block",
|
|
84
|
+
"extract_build_info",
|
|
85
|
+
"parse_mkdocs_output",
|
|
86
|
+
"parse_markdown_exec_issue",
|
|
87
|
+
"parse_info_messages",
|
|
88
|
+
"group_info_messages",
|
|
89
|
+
"dedent_code",
|
|
90
|
+
# State file functions
|
|
91
|
+
"find_project_root",
|
|
92
|
+
"get_state_file_path",
|
|
93
|
+
"read_state_file",
|
|
94
|
+
"write_state_file",
|
|
95
|
+
# Remote
|
|
96
|
+
"fetch_remote_log",
|
|
97
|
+
# Streaming
|
|
98
|
+
"StreamingProcessor",
|
|
99
|
+
# Display
|
|
100
|
+
"print_issue",
|
|
101
|
+
"print_info_groups",
|
|
102
|
+
"print_summary",
|
|
103
|
+
# Modes
|
|
104
|
+
"run_wrap_mode",
|
|
105
|
+
# CLI
|
|
106
|
+
"__version__",
|
|
107
|
+
"main",
|
|
108
|
+
]
|