Add links to documentation in README.md

dearblue · dearblue · commit 6291b55bba19 · 2024-11-10T22:39:14.000+09:00
The documentation table is generated by the `rake doc:update-index` command.
The following conditions must be met for links to be added to the documentation table.

  - The file must be placed under the `doc/` directory
  - The file must have the extension `.md`
  - The file must be written at the top of the file with `&lt;! -- summary: ANY-TEXT --&gt;`
diff --git a/README.md b/README.md
@@ -85,6 +85,27 @@ extensions in C and/or Ruby. For a guide on how to use mrbgems, consult the
 [mrbgems.md](doc/guides/mrbgems.md) file, and for example code, refer to the
 [examples/mrbgems/](examples/mrbgems) folder.
 
+## Index of Document
+
+<!--
+    This section is generated by `rake doc:update-index`.
+    All manual changes will get lost.
+-->
+
+<!-- BEGIN OF MRUBY DOCUMENT INDEX -->
+- [About the Limitations of mruby](doc/limitations.md)
+- [About the Compile](doc/guides/compile.md)
+- [About the Debugger with the `mrdb` Command](doc/guides/debugger.md)
+- [About GC Arena](doc/guides/gc-arena-howto.md)
+- [About Linking with `libmruby`](doc/guides/link.md)
+- [About Memory Allocator Customization](doc/guides/memory.md)
+- [About Build-time Configurations](doc/guides/mrbconf.md)
+- [About the Build-time Library Manager](doc/guides/mrbgems.md)
+- [About the Symbols](doc/guides/symbol.md)
+- [Internal Implementation / About Value Boxing](doc/internal/boxing.md)
+- [Internal Implementation / About mruby Virtual Machine Instructions](doc/internal/opcode.md)
+<!-- END OF MRUBY DOCUMENT INDEX -->
+
 ## License
 
 mruby is released under the [MIT License](LICENSE).
diff --git a/doc/guides/compile.md b/doc/guides/compile.md
@@ -1,3 +1,5 @@
+<!-- summary: About the Compile -->
+
 # Compile
 
 mruby uses Rake to compile and cross-compile all libraries and
diff --git a/doc/guides/debugger.md b/doc/guides/debugger.md
@@ -1,3 +1,5 @@
+<!-- summary: About the Debugger with the `mrdb` Command -->
+
 # How to Use the mruby Debugger
 
 copyright (c) 2014 Specified Non-Profit Corporation mruby Forum
diff --git a/doc/guides/gc-arena-howto.md b/doc/guides/gc-arena-howto.md
@@ -1,3 +1,5 @@
+<!-- summary: About GC Arena -->
+
 # How to use `mrb_gc_arena_save()`/`mrb_gc_arena_restore()`/`mrb_gc_protect()`
 
 _This is an English translation of [Matz's blog post][matz blog post]
diff --git a/doc/guides/link.md b/doc/guides/link.md
@@ -1,3 +1,5 @@
+<!-- summary: About Linking with `libmruby` -->
+
 # Linking `libmruby` to your application
 
 You have two ways to link `libmruby` to your application.
diff --git a/doc/guides/memory.md b/doc/guides/memory.md
@@ -1,3 +1,5 @@
+<!-- summary: About Memory Allocator Customization -->
+
 # Memory Allocation
 
 There are three methods to customize memory allocation in mruby.
diff --git a/doc/guides/mrbconf.md b/doc/guides/mrbconf.md
@@ -1,3 +1,5 @@
+<!-- summary: About Build-time Configurations -->
+
 # mruby configuration macros
 
 ## The configuration file
diff --git a/doc/guides/mrbgems.md b/doc/guides/mrbgems.md
@@ -1,3 +1,5 @@
+<!-- summary: About the Build-time Library Manager -->
+
 # mrbgems
 
 mrbgems is a library manager to integrate C and Ruby extensions in an easy and
diff --git a/doc/guides/symbol.md b/doc/guides/symbol.md
@@ -1,3 +1,5 @@
+<!-- summary: About the Symbols -->
+
 # Symbols
 
 Symbols in `mruby` C source code is represented by `mrb_sym` which is alias of
diff --git a/doc/internal/boxing.md b/doc/internal/boxing.md
@@ -1,3 +1,5 @@
+<!-- summary: About Value Boxing -->
+
 # Boxing
 
 The mruby objects and data are represented by C data type `mrb_value`. There are three options how to pack the data values in the `mrb_value`.
diff --git a/doc/internal/opcode.md b/doc/internal/opcode.md
@@ -1,3 +1,5 @@
+<!-- summary: About mruby Virtual Machine Instructions -->
+
 # The new bytecode
 
 We will reimplement the VM to use 8bit instruction code. By
diff --git a/doc/limitations.md b/doc/limitations.md
@@ -1,3 +1,5 @@
+<!-- summary: About the Limitations of mruby -->
+
 # Limitations and Differences
 
 The philosophy of mruby is to be a lightweight implementation of
diff --git a/tasks/doc.rake b/tasks/doc.rake
@@ -80,6 +80,32 @@ namespace :doc do
 
     MRuby::Documentation.update_opcode_md
   end
+
+  task 'update-index' do
+    rev_order = %w(doc/internal/ doc/guides/ doc/)
+    cmd = %W(git --git-dir #{MRUBY_ROOT}/.git --work-tree #{MRUBY_ROOT} ls-files -- doc/*.md)
+    doc = IO.popen(cmd, "r") { |io| io.read.split("\n") }
+    doc.sort_by! { |e| [-rev_order.index { |o| e.start_with?(o) }, e] }
+    readme_path = File.join(MRUBY_ROOT, "README.md")
+    readme = File.read(readme_path)
+    matched = false
+    mark_begin = "<!-- BEGIN OF MRUBY DOCUMENT INDEX -->\n"
+    mark_end = "<!-- END OF MRUBY DOCUMENT INDEX -->\n"
+    readme1 = readme.sub(/^#{mark_begin}\K.*(?=^#{mark_end})/m) {
+      matched = true
+      doc.each_with_object("") { |d, a|
+        summary = File.open(File.join(MRUBY_ROOT, d)) { |f|
+          f.each_line.first.slice(/^<!--\s*summary:\s*(.*?)\s*-->/, 1)
+        }
+        if summary
+          summary = "Internal Implementation / #{summary}" if d.start_with?("doc/internal/")
+          a << "- [#{summary}](#{d})\n"
+        end
+      }
+    }
+    raise "missing marker for document index in README.md" unless matched
+    File.write(readme_path, readme1, mode: "wb") unless readme == readme1
+  end
 end
 
 # deprecated

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+<!-- summary: About the Compile -->`
	`2`	`+`
`1`	`3`	`# Compile`
`2`	`4`
`3`	`5`	`mruby uses Rake to compile and cross-compile all libraries and`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	+<!-- summary: About the Debugger with the `mrdb` Command -->
	`2`	`+`
`1`	`3`	`# How to Use the mruby Debugger`
`2`	`4`
`3`	`5`	`copyright (c) 2014 Specified Non-Profit Corporation mruby Forum`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+<!-- summary: About GC Arena -->`
	`2`	`+`
`1`	`3`	# How to use `mrb_gc_arena_save()`/`mrb_gc_arena_restore()`/`mrb_gc_protect()`
`2`	`4`
`3`	`5`	`_This is an English translation of [Matz's blog post][matz blog post]`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	+<!-- summary: About Linking with `libmruby` -->
	`2`	`+`
`1`	`3`	# Linking `libmruby` to your application
`2`	`4`
`3`	`5`	You have two ways to link `libmruby` to your application.
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+<!-- summary: About Memory Allocator Customization -->`
	`2`	`+`
`1`	`3`	`# Memory Allocation`
`2`	`4`
`3`	`5`	`There are three methods to customize memory allocation in mruby.`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+<!-- summary: About Build-time Configurations -->`
	`2`	`+`
`1`	`3`	`# mruby configuration macros`
`2`	`4`
`3`	`5`	`## The configuration file`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+<!-- summary: About the Build-time Library Manager -->`
	`2`	`+`
`1`	`3`	`# mrbgems`
`2`	`4`
`3`	`5`	`mrbgems is a library manager to integrate C and Ruby extensions in an easy and`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+<!-- summary: About the Symbols -->`
	`2`	`+`
`1`	`3`	`# Symbols`
`2`	`4`
`3`	`5`	Symbols in `mruby` C source code is represented by `mrb_sym` which is alias of
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+<!-- summary: About Value Boxing -->`
	`2`	`+`
`1`	`3`	`# Boxing`
`2`	`4`
`3`	`5`	The mruby objects and data are represented by C data type `mrb_value`. There are three options how to pack the data values in the `mrb_value`.