diff options
author | Viktor Söderqvist <viktor.soderqvist@est.tech> | 2021-01-13 15:14:51 +0100 |
---|---|---|
committer | Oran Agra <oran@redislabs.com> | 2021-01-15 13:33:56 +0200 |
commit | ebf20b83b2cfcaf326f037a8274848662a3a9603 (patch) | |
tree | 269c711d77f943c054cd95c90841ccf498a67e08 /src/modules | |
parent | 108afbc0bbde9153e4cb08bf50a724c4feb9626e (diff) | |
download | redis-ebf20b83b2cfcaf326f037a8274848662a3a9603.tar.gz |
Modules API reference formatting fixes
Fixes markdown formatting errors and some functions not showing
up in the generated documentation at all.
Ruby script (gendoc.rb) fixes:
* Modified automatic instertion of backquotes:
* Don't add backquotes around names which are already preceded by a
backquote. Fixes for example \`RedisModule_Reply\*\` which turning
into \`\`RedisModule_Reply\`\*\` messes up the formatting.
* Add backquotes around types such as RedisModuleString (in addition
to function names `RedisModule_[A-z()]*` and macro names
`REDISMODULE_[A-z]*`).
* Require 4 spaces indentation for disabling automatic backquotes, i.e.
code blocks. Fixes continuations of list items (indented 2 spaces).
* More permissive extraction of doc comments:
* Allow doc comments starting with `/**`.
* Make space before `*` on each line optional.
* Make space after `/*` and `/**` optional (needed when appearing on
its own line).
Markdown fixes in module.c:
* Fix code blocks not indented enough (4 spaces needed).
* Add black line before code blocks and lists where missing (needed).
* Enclose special markdown characters `_*^<>` in backticks to prevent them
from messing up formatting.
* Lists with `1)` changed to `1.` for proper markdown lists.
* Remove excessive indentation which causes text to be unintentionally
rendered as code blocks.
* Other minor formatting fixes.
Other fixes in module.c:
* Remove blank lines between doc comment and function definition. A blank
line here makes the Ruby script exclude the function in docs.
Diffstat (limited to 'src/modules')
-rw-r--r-- | src/modules/gendoc.rb | 15 |
1 files changed, 9 insertions, 6 deletions
diff --git a/src/modules/gendoc.rb b/src/modules/gendoc.rb index ee6572884..249c8b6ea 100644 --- a/src/modules/gendoc.rb +++ b/src/modules/gendoc.rb @@ -4,16 +4,18 @@ # Convert the C comment to markdown def markdown(s) s = s.gsub(/\*\/$/,"") - s = s.gsub(/^ \* {0,1}/,"") - s = s.gsub(/^\/\* /,"") + s = s.gsub(/^ ?\* ?/,"") + s = s.gsub(/^\/\*\*? ?/,"") s.chop! while s[-1] == "\n" || s[-1] == " " lines = s.split("\n") newlines = [] + # Backquote function, macro and type names, except if already backquoted and + # in code blocks indented by 4 spaces. lines.each{|l| - if l[0] != ' ' - l = l.gsub(/RM_[A-z()]+/){|x| "`#{x}`"} - l = l.gsub(/RedisModule_[A-z()]+/){|x| "`#{x}`"} - l = l.gsub(/REDISMODULE_[A-z]+/){|x| "`#{x}`"} + if not l.start_with?(' ') + l = l.gsub(/(?<!`)RM_[A-z()]+/){|x| "`#{x}`"} + l = l.gsub(/(?<!`)RedisModule[A-z()]+/){|x| "`#{x}`"} + l = l.gsub(/(?<!`)REDISMODULE_[A-z]+/){|x| "`#{x}`"} end newlines << l } @@ -41,6 +43,7 @@ def docufy(src,i) end puts "# Modules API reference\n\n" +puts "<!-- This file is generated from module.c using gendoc.rb -->\n\n" src = File.open("../module.c").to_a src.each_with_index{|line,i| if line =~ /RM_/ && line[0] != ' ' && line[0] != '#' && line[0] != '/' |