Repository navigation
Integrate automatic documentation creation. - #80
Merged
Merged
Conversation
* Initial plan
* Add automated CLI documentation generation using cog
- Add cogapp dependency in optional docs group
- Create docs/cli/ directory structure
- Generate comprehensive documentation for all command groups
- Add poe tasks for docs:generate and docs:check
- Include usage examples and workflow guidance
Co-authored-by: crossjam <208062+crossjam@users.noreply.github.com>
* Add comprehensive tests for CLI documentation generation
- Test docs/cli directory structure
- Verify cogapp installation
- Check documentation is up to date
- Validate cog directives in markdown files
- Ensure all command groups have documentation
Co-authored-by: crossjam <208062+crossjam@users.noreply.github.com>
* Address code review feedback
- Fix security issue: remove shell=True from subprocess call
- Correct CLI flag names in examples (--starred-only not --starred)
- Remove non-existent --diarize and --max flags from examples
- Fix chapters command examples (no starred flag)
- Update poe tasks to exclude README.md from cog processing
- Make test more lenient for rich-click formatting variations
Co-authored-by: crossjam <208062+crossjam@users.noreply.github.com>
* Fix linting errors: Remove trailing whitespace from blank lines
- Remove whitespace from blank line at line 48
- Remove whitespace from blank line at line 64
- All lint checks now pass
Co-authored-by: crossjam <208062+crossjam@users.noreply.github.com>
* Install dependencies with uv and verify QA task passes
- Install uv package manager
- Use uv sync to install all dependencies including cogapp
- Install docs and lint extras, plus dev dependencies
- Verify poe qa task completes cleanly (lint, type, test all pass)
- All 167 tests pass successfully
Co-authored-by: crossjam <208062+crossjam@users.noreply.github.com>
* Add cogapp to dev dependencies and update uv.lock
- Add cogapp>=3.0.0 to dev dependency-groups in pyproject.toml
- Update uv.lock to include cogapp in dev dependencies
- Fixes test failures when running poe qa in clean environment
- Tests test_cog_installed and test_docs_check_command now pass
Co-authored-by: crossjam <208062+crossjam@users.noreply.github.com>
* Fix documentation to use markdown-compatible ASCII instead of console formatting
- Add clean_help_output function to strip ANSI codes and replace box-drawing characters
- Update all cog blocks in download.md to use plain ASCII (+ - |) instead of unicode box chars (╭ ╰ ─ │)
- Update all cog blocks in transcription.md to use plain ASCII
- Regenerate documentation using cogapp
- All tests pass
Co-authored-by: crossjam <208062+crossjam@users.noreply.github.com>
* Add a docs check task in github actions
* Invoke the correct poe task to generate docs
* Diff the correct subdirectory
* Update the autogenerated documentation
* Generate automated docs with specific COLUMNS=100
* Set COLUMNS for generated documentation n poe task, use docs:check in github actions
* See if running cog directly makes a difference
* Generate diff when checking with cog
* Turn off host specific app directory in documentation
* Replace host-specific path with placeholder in podcast-archiver documentation
- Add regex to clean_help_output function to replace host-specific config paths
- Pattern matches [default: /any/path/to/config.yaml] across multiple lines
- Replaces with [default: {PLATFORM_APP_DIR}/config.yaml]
- Fixes issue where documentation showed user-specific paths like /Users/crossjam/Library/Application Support/podcast-archiver/config.yaml
- All tests pass
Co-authored-by: crossjam <208062+crossjam@users.noreply.github.com>
* Fix whitespace alignment after path placeholder replacement
- Add line normalization to clean_help_output function
- Normalize all table rows to 100 characters width
- Normalize border lines to 100 characters width
- Fix line 416 (now 427) to have proper alignment with closing |
- All lines now consistently 100 characters for proper formatting
- Tests pass
Co-authored-by: crossjam <208062+crossjam@users.noreply.github.com>
* Add line wrapping to preserve content when normalizing to 100 chars
- Replace aggressive normalization with smart line wrapping
- Wrap long table rows (>100 chars) to 100-char width
- Continuation lines use 37-space indentation
- Preserves all content from 120-char CLI output
- Fixes issue where "precedence." and other text was being truncated
- Tests pass
Co-authored-by: crossjam <208062+crossjam@users.noreply.github.com>
* Plan to fix cog output inconsistency across all command sections
Co-authored-by: crossjam <208062+crossjam@users.noreply.github.com>
* Fix cog documentation generation to properly wrap CLI output
- Update all 7 clean_help_output functions with improved wrapping logic
- Add path replacement for host-specific config.yaml paths in all blocks
- Fix issue where 120-char CLI output created empty continuation lines
- Content that fits within 100 chars (after trimming padding) is not wrapped
- Only create continuation lines when there's actual content to continue
- All documentation sections now generate consistent 100-char tables
- Tests pass
Co-authored-by: crossjam <208062+crossjam@users.noreply.github.com>
* Add comprehensive test for clean_help_output wrapping logic
- Test validates wrapping of long lines with spaces to 100 chars
- Covers 8 test cases:
1. Lines that fit within 100 chars (just padding adjustment)
2. Lines genuinely too long that need wrapping
3. Lines with only trailing spaces (no wrap needed)
4. Border line normalization
5. ANSI code stripping
6. Box-drawing character replacement
7. Host-specific path replacement
8. Continuation lines with leading spaces
- All tests pass, confirming wrapping logic works correctly
Co-authored-by: crossjam <208062+crossjam@users.noreply.github.com>
* Fix linting issues in wrapping test
- Fix line length issues by breaking long strings into concatenations
- Fix blank lines with whitespace
- Fix off-by-one error in test input padding (62 spaces, not 61)
- All 168 tests pass
- Full QA suite passes (lint, type, test)
Co-authored-by: crossjam <208062+crossjam@users.noreply.github.com>
* Tweak generated docs to eliminate host specific content
* Don’t hardwire where data is stored
* Refactor: Extract clean_help_output to doc_utils module
- Create src/retrocast/doc_utils.py with clean_help_output function
- Remove 15 duplicate function definitions from documentation files
- Update all cog blocks to import from doc_utils instead
- Add test to verify imports are used instead of inline definitions
- All tests pass, lint passes
- Reduces code duplication and improves maintainability
Co-authored-by: crossjam <208062+crossjam@users.noreply.github.com>
* Refine the replacement regexp for a config file path default string in docs
* Prefix platfrom_app_dir text with a /, don’t do a git diff on doc gen check
* Update download.md doc file
* See what the output of help is
* Need to bump the columns wide enough
* Just eliminate the offending line
* Remove any completely empty lines from post-processed help output
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: crossjam <208062+crossjam@users.noreply.github.com>
Co-authored-by: Brian Dennis <bmd+github@crossjam.net>
Danger! Danger! High Voltage!
crossjam
added
documentation
Owner
Author
|
LGTM! Fire in the ... Taco Bell! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
We wound up implementing the automatic documentation creation in another branch created by Copilot Agent. The results got merged into this branch. Now merging into main.