From 6291b55bba19e15b7745c317477f20ef9fc6cc3e Mon Sep 17 00:00:00 2001 From: dearblue Date: Sun, 10 Nov 2024 22:39:14 +0900 Subject: [PATCH] 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 `` --- README.md | 21 +++++++++++++++++++++ doc/guides/compile.md | 2 ++ doc/guides/debugger.md | 2 ++ doc/guides/gc-arena-howto.md | 2 ++ doc/guides/link.md | 2 ++ doc/guides/memory.md | 2 ++ doc/guides/mrbconf.md | 2 ++ doc/guides/mrbgems.md | 2 ++ doc/guides/symbol.md | 2 ++ doc/internal/boxing.md | 2 ++ doc/internal/opcode.md | 2 ++ doc/limitations.md | 2 ++ tasks/doc.rake | 26 ++++++++++++++++++++++++++ 13 files changed, 69 insertions(+) diff --git a/README.md b/README.md index 21ee55c6f..dc125efd0 100644 --- 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 + + + + +- [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) + + ## License mruby is released under the [MIT License](LICENSE). diff --git a/doc/guides/compile.md b/doc/guides/compile.md index b0804e52c..ccb81f79a 100644 --- a/doc/guides/compile.md +++ b/doc/guides/compile.md @@ -1,3 +1,5 @@ + + # Compile mruby uses Rake to compile and cross-compile all libraries and diff --git a/doc/guides/debugger.md b/doc/guides/debugger.md index 4e52b7b8b..fa6039e7d 100644 --- a/doc/guides/debugger.md +++ b/doc/guides/debugger.md @@ -1,3 +1,5 @@ + + # 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 index 2ac2bdfd4..c2d02b0e0 100644 --- a/doc/guides/gc-arena-howto.md +++ b/doc/guides/gc-arena-howto.md @@ -1,3 +1,5 @@ + + # 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 index ac19aa234..978aa6259 100644 --- a/doc/guides/link.md +++ b/doc/guides/link.md @@ -1,3 +1,5 @@ + + # 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 index 8f78ffbe3..adfa6c0fc 100644 --- a/doc/guides/memory.md +++ b/doc/guides/memory.md @@ -1,3 +1,5 @@ + + # Memory Allocation There are three methods to customize memory allocation in mruby. diff --git a/doc/guides/mrbconf.md b/doc/guides/mrbconf.md index a2546f2ba..27c62671e 100644 --- a/doc/guides/mrbconf.md +++ b/doc/guides/mrbconf.md @@ -1,3 +1,5 @@ + + # mruby configuration macros ## The configuration file diff --git a/doc/guides/mrbgems.md b/doc/guides/mrbgems.md index fe086c1e9..fc15c0530 100644 --- a/doc/guides/mrbgems.md +++ b/doc/guides/mrbgems.md @@ -1,3 +1,5 @@ + + # 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 index bae789b64..c98297329 100644 --- a/doc/guides/symbol.md +++ b/doc/guides/symbol.md @@ -1,3 +1,5 @@ + + # 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 index 8945f0699..1e4956d62 100644 --- a/doc/internal/boxing.md +++ b/doc/internal/boxing.md @@ -1,3 +1,5 @@ + + # 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 index 3cc960fdf..7f4fc6982 100644 --- a/doc/internal/opcode.md +++ b/doc/internal/opcode.md @@ -1,3 +1,5 @@ + + # The new bytecode We will reimplement the VM to use 8bit instruction code. By diff --git a/doc/limitations.md b/doc/limitations.md index 3c65f76ec..952136849 100644 --- a/doc/limitations.md +++ b/doc/limitations.md @@ -1,3 +1,5 @@ + + # Limitations and Differences The philosophy of mruby is to be a lightweight implementation of diff --git a/tasks/doc.rake b/tasks/doc.rake index 4d67b34d9..b755ef52d 100644 --- 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 = "\n" + mark_end = "\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(/^/, 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