Refactor to mimic singlehtml builder#1
Open
jdillard wants to merge 14 commits intoakaihola:singlemarkdownfrom
Open
Refactor to mimic singlehtml builder#1jdillard wants to merge 14 commits intoakaihola:singlemarkdownfrom
jdillard wants to merge 14 commits intoakaihola:singlemarkdownfrom
Conversation
This commit adds a functional SingleFileMarkdownBuilder that generates a single consolidated Markdown file from Sphinx documentation rather than separate files for each document. Key changes: - Complete implementation of SingleFileMarkdownBuilder with custom write_documents() method - Add custom SingleMarkdownTranslator to properly handle document anchors and styling - Add table of contents and document anchors to improve navigation in the single file - Simplify cross-references by using document anchors within the same file - Reformat test file to follow code style without functional changes The builder can be used with: sphinx-build -M singlemarkdown ./docs ./build The output will be a single file at ./build/singlemarkdown/<root_doc>.md
…tion errors - Refactor setup function in __init__.py with proper type hints and return metadata - Update singlemarkdown.py to follow Sphinx extension pattern by removing duplicate builder registration - Follow pattern from Sphinx's singlehtml.py implementation - Ensure proper extension loading through app.setup_extension
This commit adds the missing render_partial method to the SingleFileMarkdownBuilder class, which resolves the 'no-member' errors in the singlemarkdown.py file. The implementation: - Creates a proper render_partial method based on Sphinx's similar functionality - Uses StringOutput instead of StringIO for proper document rendering - Ensures correct type handling for method return values - Updates write_documents method to use StringOutput for consistency Fixes E1101: Instance of 'SingleFileMarkdownBuilder' has no 'render_partial' member (no-member)
- Add proper type annotations to class attributes and method parameters/return types - Fix potential type incompatibilities with appropriate casts - Add pyright-specific comments to suppress false positives - Improve variable naming and eliminate unused variables - Replace implicit variable assignments with explicit ones using underscore
…nnotations - Add extensive unit tests for SingleFileMarkdownBuilder methods - Create separate test file for SingleMarkdownTranslator - Improve Path handling in tests using pathlib - Add proper type annotations for MarkdownWriter variable - Test error handling and edge cases for better coverage
- Add parametrized tests to test singlemarkdown with various configuration options - Test handling of missing build directories - Test handling of file permission issues - Match the integration test pattern from test_builder.py - Enhance error handling and coverage
Pull Request Test Coverage Report for Build 18898729777Details
💛 - Coveralls |
akaihola
force-pushed
the
singlemarkdown
branch
from
ff7719d to
e78f773
Compare
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
3 participants
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.
Developer Note: I used Claude Code to generate this PR (making sure it had access to the sample docs and the singlehtml builder for references) to address liran-funaro#37 (comment) and haven't reviewed the code, but I did check it's work and it did fix the issue. I'm not sure if this helpful, and if not feel free to ignore, but thought I would make the PR in case it could serve as inspiration.
Below is its PR description.
Summary
Successfully adapted the
singlemarkdownbuilder to behave like Sphinx's built-insinglehtmlbuilder, which fixed the duplicate heading and incorrect nesting issues.Changes Made
assemble_doctree()to merge all documents into a single doctree viainline_all_toctrees()current_doc_nameandsec_numbersbefore writing (needed for URL adjustments)get_target_uri()to use#document-{docname}anchors like singlehtml doesstart_of_filenode handlersvisit_start_of_file()adds document anchors (like HTML translator)depart_start_of_file()tracks docname stack#docnameto#document-docnameResult
Before
After
All 19 tests pass, and the output now correctly handles heading hierarchy when merging multiple documents!