Package: bmd-py
Bash to Markdown Documentationbmdis the dumbest documentation framework you could find on the earth !
It changes your bash scripts into a useful Markdown documentation.FeaturesIt removes theshebangline for an aesthetic output.It removes the#string of your bash comments.You shouldwrite all your bash comments into a compliant markdown format, and thenit will work.Also, we don't care about all the Markdown flavours. Choose the one for your use cases.But, let's dissipate all doubts by seeing a compatibility table :FlavorbmdGFM✅ExtraMark✅All the others✅Getting startedStart by documenting a hello world :# hello.sh: My Hello World bash script# ------------------------------------## This **hello world** comes from my *heart*.# See [Hello World!](https://en.wikipedia.org/wiki/%22Hello,_World!%22_program)# ```shecho"Hello World!"# ```Indeed, your script code willneverbe compliant with any Markdown formats.So, the purposed solution is to encapsulate your code in a code block withthe 3 backticks.
You can specify the script langage, and you'll have a formated code rendering !
The drawback is : your documentation will be anannotedbash script.By default,bmdwill remove the common scripting langage comment lines but the option--regexshould be used to change all others languages.You can do the trick with a NodeJS script :// # hello.js// You know what I mean// ```jsconsole.log('Hello World!')// ```This one can be changed with./bmd.sh -r '^\/\/ ?' hello.jsThe bash way : bmd.shInstallingThe bash script should be installed by usingcurl:curlhttps://git.sr.ht/~vlnk/bmd/blob/main/src/bmd.sh>bmd.sh
./bmd.sh```sh### How it works ?Itis2`sed`commands.That'sallfolks.```shset-e

bmd(){cat"$1"|\sed"/^#!/d"|\sed-r"s/$2//"}How to use it ?I suggest to do./bmd.sh bmd.sh, but please, follow the help :usage(){echo"bmd - Bash to Markdown Documentation"echo""echo"USAGE: ./bmd.sh [OPTIONS] INPUT"echo""echo"Change the script file INPUT to a Markdown documentation."echo""echo"Options:"echo"-r, --regex PATTERN Specify the regex PATTERN to remove [default: '^# ?']."echo"-h, --help          Print help."}REGEX="^# ?"INPUT=""foriin"$@";docase$iin-h|--help)usage;exit0;;-r|--regex)HAS_REGEX=true;;*)if["$HAS_REGEX"];thenREGEX="$i"unsetHAS_REGEXelseINPUT="$i"fi;;esacdoneif["$INPUT"];thenbmd"$INPUT""$REGEX"elseecho"error: missing required argument 'INPUT'"fiThe python way : bmd.pyInstallingbmdis published onPyPiunder thebmd-pypackage.
You should be able to install it with:pipinstallbmd-py
bmd.py--help```sh### How it works?Thepythonscriptdothesamethingasthebashonebutwithout`sed`,ituses`regex`instead```py
importclick
importregexSHEBANG_REGEX=r'^#!'REGEX_HELP='Specify the TEXT regex pattern to remove.'@click.command()@click.argument('input')@click.option('-r','--regex','pattern',default='^# ?',show_default=True,help=REGEX_HELP)defbmd(input,pattern):"""Change the script file INPUT to a Markdown documentation."""withopen(input)asf:output=[]forlineinf:ifnotregex.match(SHEBANG_REGEX,line):ifregex.match(pattern,line):output.append(regex.sub(pattern,'',line))else:output.append(line)print(''.join(output),end='')if__name__=='__main__':bmd()The javascript way : bmd.jsInstallingbmdis published on npm under thebmd-jspackage.
You should be able to install it with:npminstallbmd-js
bmd-js--helpHow it works?The javascript code is using the NodeJS API to do the same thing as others.
Is uses the asynchronous reading of each line to do the job.constfs=require('fs')constreadline=require('readline');const{program}=require('commander')constSHEBANG_REGEX=/^#!/functionbmd(input,pattern){constoutput=[]constregex=newRegExp(pattern)constrl=readline.createInterface({input:fs.createReadStream(input),output:process.stdout,terminal:false});rl.on('line',(line)=>{if(!line.match(SHEBANG_REGEX)){if(line.match(regex)){output.push(line.replace(regex,''))}else{output.push(line)}}})rl.on('close',()=>{process.stdout.write(output.join('\n')+'\n');});}letinput=''program.name('bmd.js').description('Change the script file INPUT to a Markdown documentation.').arguments('<INPUT>').action(inputArg=>{input=inputArg}).option('-r, --regex <PATTERN>','Specify the regex PATTERN to remove.','^# ?').parse(process.argv)bmd(input,program.regex)ContributingDon't hesitate to submit issues in thebmdtracker.TestingEach new contribution should be applied with an associatedunit test.
Thebmd CIis triggered on every push with:.PHONY:testtest:install-all./tasks/test.shDocumentingI recommand you to use thepre-commithook in order to always generate the newREADME.mdfile:cdbmd
lnhooks/*.git/hooks/But theREADMEcan be generated manually by usingmake doc:.PHONY:docdoc:./tasks/doc.sh'README.md'Building and publishingCheck the supported distributions:pythonjavascriptDon't forget to be logged before publishing a newbmdpackage !The Makefile contains all recipes in order to:install dependencies (bmd-py, bmd-js)bundle package (bmd-py, bmd-js)check package (bmd-py)publish (bmd-py, bmd-js).PHONY:install-pyinstall-py:pip3install-rrequirements.txt.PHONY:build-pybundle-py:python3setup.pysdist.PHONY:check-pycheck-py:bundle-pytwinecheckdist/*.PHONY:publish-pypublish-py:cleanbundle-pytwineuploaddist/*.PHONY:install-jsinstall-js:npminstall.PHONY:bundle-jsbundle-js:npmpack.PHONY:publish-jspublish-js:npmpublish.PHONY:install-allinstall-all:install-pyinstall-js.PHONY:publish-allpublish-all:publish-pypublish-jsclean:if [ -d 'dist' ]; then rm -rd 'dist'; fiif [ -d 'bmd_py.egg-info' ]; then rm -rd 'bmd_py.egg-info'; fiFoire aux QuestionsIs it a joke ?Yes, and no. I wrote this for my own usage, I hope it would be useful for your owns.Is it tested with all the flavours ?Of course not.Where did you get this dumb idea ?From therustdoctool.Is it a meta program?Yes,bmdis documented withitself.KISS,@vlnk