Skip to content

Feature/markdown conversion#189

Open
znz wants to merge 16 commits intorurema:masterfrom
znz:feature/markdown-conversion
Open

Feature/markdown conversion#189
znz wants to merge 16 commits intorurema:masterfrom
znz:feature/markdown-conversion

Conversation

@znz
Copy link
Copy Markdown
Member

@znz znz commented Apr 7, 2026

No description provided.

znz and others added 4 commits April 7, 2026 14:28
@znz @claude
Add MarkdownToRRD converter (MD → RRD)
0d7ad5a 
Implement BitClust::MarkdownToRRD for converting Markdown-format
documentation to RRD format for the existing bitclust pipeline.

Features:
- Heading conversion (# → =, ## → ==, ### → ---)
- Method signatures with def/const/gvar/module_function keywords
- ClassName.method preservation (no self. conversion)
- YAML front matter → category/require/sublibrary
- @param/@return/@raise metadata with whitespace preservation
- @see → **SEE** conversion with separator preservation
- Inline cross-references [type:target] → [[type:target]]
- Module function refs: ? → .# (Kernel?.open → Kernel.#open)
- Bracket escaping: \[\] → [] (with space convention for [])
- Backslash escaping: \\\\ → \\
- Code blocks: ```ruby → #@SampleCode, ``` → //emlist
- Fenced code (N backticks) → indented code (N-3 spaces)
- Lists: - → *, N. → (N), **N.** → N.
- Definition lists: - **`term`**: desc → : term / desc
- #@ directive passthrough with nesting in continuation lines
- __WORD__ code span stripping

74 tests, 90 assertions.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@znz @claude
Add RRDToMarkdown converter (RRD → MD)
ea3988e 
Implement BitClust::RRDToMarkdown for converting existing RRD
documentation to Markdown format.

Features:
- Heading conversion (= → #, == → ##, === → ###)
- Method signatures with def/const/gvar/module_function keywords
- Module Functions section tracking for module_function detection
- YAML front matter generation (category/require/sublibrary)
- include/extend/alias passthrough (not front matter)
- @param/@raise/@return with whitespace preservation
- @see → - **SEE** list format
- Inline cross-references [[type:target]] → [type:target]
- Module function refs: .# → ? (Kernel.#open → Kernel?.open)
- Bracket escaping: [] → \[\], \\ → \\\\
- Code blocks: #@SampleCode → ```ruby, //emlist → ```lang
- Indented code → fenced code (3+indent backticks, base indent removed)
- Lists with continuation lines (content_indent tracking)
- Definition lists: : term / desc → - **`term`**: desc
- #@ directive nesting in continuation lines
- __WORD__ auto code spans (excluding bracket links)
- Bold number text: N. → **N.**

62 tests, 64 assertions.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@znz @claude
Add rrd2md batch conversion script
bac512c 
Script to convert all RRD documentation files to Markdown format.

Usage:
  ruby bin/rrd2md <input_dir> <output_dir>  # batch convert
  ruby bin/rrd2md --file <file>             # single file to stdout
  ruby bin/rrd2md --dry-run <in> <out>      # list target files

Converts all 826 files in doctree/refm/api/src/ with zero errors.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@znz @claude
Add MARKUP_SPEC.md and sample files
a5c185d 
Markdown notation specification (14 sections) and sample files
generated from actual RRD→MD converter output.

MARKUP_SPEC.md covers:
- YAML front matter (category/require/sublibrary)
- Heading structure and signature keywords
- Method signatures (def/const/gvar/module_function)
- @param/@return/@raise/@see metadata format
- Cross-references with module function ? notation
- Preprocessor directives (#@SInCE etc.)
- Code blocks (#@SampleCode, //emlist, indented code)
- Lists, definition lists, tables
- Parser logic (keyword-based, no context dependency)

Samples: Comparable.md, Array.md, String.md, cgi_core.md

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@znz znz requested a review from Copilot April 7, 2026 05:59
Copilot AI reviewed Apr 7, 2026
View reviewed changes
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR introduces a bidirectional conversion layer between BitClust’s RRD format and a new “るりま Markdown” format, along with documentation, samples, a batch conversion script, and extensive tests.

Changes:

  • Add BitClust::RRDToMarkdown and BitClust::MarkdownToRRD converters covering headings, signatures, directives, cross-references, lists, code blocks, and YAML front matter.
  • Add comprehensive unit + integration-style tests for both conversion directions (including roundtrip checks).
  • Add a Markdown markup specification document, sample converted Markdown files, and a bin/rrd2md batch conversion tool.

Reviewed changes

Copilot reviewed 7 out of 10 changed files in this pull request and generated 5 comments.

Show a summary per file
File Description
lib/bitclust/rrd_to_markdown.rb Implements RRD → Markdown conversion (front matter, headings, signatures, refs, lists, code handling).
lib/bitclust/markdown_to_rrd.rb Implements Markdown → RRD conversion (front matter parsing, signatures, refs, lists, code handling).
test/test_rrd_to_markdown.rb Unit tests + a Comparable roundtrip parsing test for RRD → Markdown.
test/test_markdown_to_rrd.rb Unit tests + Comparable sample integration test for Markdown → RRD.
bin/rrd2md Adds a CLI batch converter for directory / single-file conversion.
doc/markdown-samples/MARKUP_SPEC.md Adds the proposed Markdown markup specification.
doc/markdown-samples/Comparable.md Sample converted Markdown for Comparable.
doc/markdown-samples/cgi_core.md Sample converted Markdown for cgi/core.
doc/markdown-samples/Array.md Sample converted Markdown for Array.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

znz added a commit to znz/doctree that referenced this pull request Apr 7, 2026
@znz
Fix typos
c70cdf2 
found in comments of rurema/bitclust#189
znz and others added 2 commits April 7, 2026 15:35
@znz @claude
Fix duplicate test method names in converter tests
fd1b634 
Rename duplicate test methods so both definitions actually run:
- test_class_method_keeps_classname → test_class_method_keeps_classname_without_nil
- test_include_passthrough → test_include_metadata_passthrough (in both test files)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@znz @claude
Regenerate sample files from updated doctree sources
620aa28 
Fix typos originating from doctree RRD sources:
- "Rrecondition Failed" → "Precondition Failed" (cgi_core.md)
- "作成したしたときに" → "作成したときに" (Array.md)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@znz znz requested a review from Copilot April 7, 2026 06:36
Copilot AI reviewed Apr 7, 2026
View reviewed changes
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 7 out of 10 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@znz @claude
Fix code block and metadata robustness issues
b583669 
Address PR review feedback:
- Emit //emlist[][lang]{ when lang is present but title is absent
- Match fence closing length to opening length (supports 4+ backticks)
- Use explicit match objects instead of global $1/$2/$3 in convert_metadata
- Escape double quotes in emlist caption for title="..." attribute

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@znz znz requested a review from Copilot April 7, 2026 07:22
Copilot AI reviewed Apr 7, 2026
View reviewed changes
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 7 out of 10 changed files in this pull request and generated 6 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@znz @claude
Remove unused constants, instance variables, and methods
cca6ecc 
- INDENT_CODE_OFFSET, DIRECTIVE_ELSE_RE, CONTINUATION_DIRECTIVE_RE
- @class_name in both converters
- convert_entry_signature in MarkdownToRRD

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@znz znz requested a review from Copilot April 7, 2026 07:53
Copilot AI reviewed Apr 7, 2026
View reviewed changes
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 7 out of 10 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

znz and others added 2 commits April 7, 2026 17:54
@znz @claude
Fix escaped bracket links, list spacing, and SEE spec
a6c1651 
- Use escape-aware bracket parser for display-text links
  ([Hash#\[\]][m:Hash#\[\]] now correctly converts)
- Preserve multiple spaces in list items (- → *)
- Use assert_match instead of brittle line index in test
- Clarify SEE spec: comma-separated refs in one item are supported

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@znz @claude
Remove display-text link support from converter and tests
0eda65e 
Display-text links ([text][type:target]) are not generated by the
RRD→MD converter, so MD→RRD does not need to handle them.
Update MARKUP_SPEC SEE examples and test inputs to use bare refs only.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@znz znz requested a review from Copilot April 7, 2026 08:55
Copilot AI reviewed Apr 7, 2026
View reviewed changes
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 7 out of 10 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@znz @claude
Update display-text link section in MARKUP_SPEC
8cc6bd1 
Mark display-text links ([text][type:target]) as a future feature
to be implemented after Markdown migration. The current converter
only generates and consumes bare refs ([type:target]).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@znz znz requested a review from Copilot April 7, 2026 09:17
Copilot AI reviewed Apr 7, 2026
View reviewed changes
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 7 out of 10 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@znz @claude
Fix title attribute unescaping to handle \\" and \" only
2649116 
The previous unescape only handled \", missing \\. Use /\\(["\\])/
to correctly unescape both without affecting other backslash sequences
like literal \n in samplecode labels.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@znz znz requested a review from Copilot April 7, 2026 09:36
Copilot AI reviewed Apr 7, 2026
View reviewed changes
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 7 out of 10 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@znz @claude
Fix samplecode label escaping, YAML guard, and unused constant
b3c7318 
- Escape backslashes in #@SampleCode labels for title="..." attribute,
  matching the emlist caption escaping
- Guard YAML.safe_load return value to ensure Hash type
- Remove unused SAMPLECODE_END_RE constant

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@znz znz requested a review from Copilot April 7, 2026 10:35
Copilot AI reviewed Apr 7, 2026
View reviewed changes
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 7 out of 10 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@znz @claude
Apply convert_inline_refs to param/raise/return descriptions and clar…
1b6529b 
…ify front matter directive limitation in spec

- Convert [[c:...]] etc. in @param/@raise/@return description text
  to Markdown [c:...] format
- Document that front matter migration is skipped when #@ directives
  are mixed with category/require/sublibrary lines

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@znz znz requested a review from Copilot April 8, 2026 01:42
Copilot AI reviewed Apr 8, 2026
View reviewed changes
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 7 out of 10 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

znz and others added 2 commits April 8, 2026 11:35
@znz @claude
Improve code span protection, empty title handling, and indent code
4663313 
- Restrict add_code_spans bracket protection to cross-ref links only
  and skip __WORD__ conversion inside inline code spans
- Treat empty title="" as no title in samplecode conversion
- Use explicit slice (line[n..]) instead of lstrip in indented code
  to preserve inner indentation precisely

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@znz @claude
Fix add_code_spans to use RRD bracket syntax [[type:...]]
76f9ff9 
RD has no backtick inline code spans, so backtick protection is
unnecessary. Use [[...]] (RRD cross-ref syntax) instead of [...]
for the bracket protection pattern.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@znz znz requested a review from Copilot April 8, 2026 02:41
Copilot AI reviewed Apr 8, 2026
View reviewed changes
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 7 out of 10 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@znz