Add links to documentation in README.md

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 `<! -- summary: ANY-TEXT -->`

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).

doc/guides/compile.md

@@ -1,3 +1,5 @@
+<!-- summary: About the Compile -->
+
 # Compile
 
 mruby uses Rake to compile and cross-compile all libraries and

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

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]

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.

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.

doc/guides/mrbconf.md

@@ -1,3 +1,5 @@
+<!-- summary: About Build-time Configurations -->
+
 # mruby configuration macros
 
 ## The configuration file

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

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

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`.

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

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

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