notwa/rc
1
0
Fork 0
mirror of https://github.com/notwa/rc synced 2024-11-05 03:39:02 -08:00
Code Issues Releases Wiki Activity

add documentation tool (no docstrings yet)

Browse source
This commit is contained in:
Connor Olding 2021-07-30 16:35:00 -07:00
parent adc53a5b68
commit 691b8251df
2 changed files with 141 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
README.md
View file

@ -8,10 +8,6 @@ quick install for random boxes:
cd && curl -L https://github.com/notwa/rc/archive/master.tar.gz | tar zx && mv rc-master rc && rc/install
```
## stuff defined in RC files
**NOTE:** everything below this line is overwritten and regenerated by `sh/document`.
hold on, this needs to be rewritten.
## shell scripts
hold on, this needs to be rewritten.
<!-- DOCUMENT -->

139
sh/document Normal file
View file

@ -0,0 +1,139 @@
#!/usr/bin/env dash
# NO_ZSH
# NO_BASH
# YES_DASH
# okay, so this probably does run with zsh and bash, but why bother?
# NOTE: a lot of boilerplate code is pulled from the pure sh bible:
# https://github.com/dylanaraps/pure-sh-bible
document2() {
local f="$1"
local c=0
local e="${f#sh/}"
[ "$f" != "$e" ] || e=""
[ "$e" != document ] || return 0
while IFS= read -r line; do
: $((c+=1))
case "$line" in *'###'*) :;; *) continue;; esac
local code="${line%%###*}" docs="${line#*###}"
code="${code#${code%%[![:space:]]*}}" # ltrim
docs="${docs#${docs%%[![:space:]]*}}" # ltrim
local s=' ' n=''
case "$docs" in
@-*)
s="$code"
n="${s%%[!a-zA-Z0-9_-]*}"
while [ -z "$n" -o "$n" = function -o "$n" = alias ]; do
[ -n "$s" ] || break
s="${s#${s%%[!a-zA-Z0-9_-]*}}"
s="${s#*[!a-zA-Z0-9_-]}"
n="${s%%[!a-zA-Z0-9_-]*}"
done
s="${docs#@-}"
s="${s#${s%%[![:space:]]*}}" # ltrim
;;
@*-*)
n="${docs%%-*}"
s="${docs#*-}"
n="${n#@}"
n="${n#${n%%[![:space:]]*}}" # ltrim
n="${n%${n##*[![:space:]]}}" # rtrim
s="${s#${s%%[![:space:]]*}}" # ltrim
;;
@*)
n="${docs#@}"
n="${n#${n%%[![:space:]]*}}" # ltrim
;;
*)
s="${docs#${docs%%[![:space:]]*}}" # ltrim
;;
esac
if [ -n "$n" ]; then
local url
[ "$url" != "${url#sh/}" ] && url="/sh/$f#L$c" || url="/home/${f#.}#L$c"
if [ "$n" = "$e" ]; then
printf '\n### [%s](%s)\n\n' "$n" "$url" >> rc/README.md~ || return 5
else
printf '\n### [%s](%s)\n\n' "$n.${f#.}" "$url" >> rc/README.md~ || return 5
#printf '\n### %s\n\n* defined in [%s](%s)\n\n' "$n" "$f" "$url" >> rc/README.md~ || return 5
fi
fi
if [ "$s" != ' ' ]; then
printf '%s\n' "$s" >> rc/README.md~ || return 5
fi
done < "$f" || return 4
}
document1() {
# NOTE: in the future, it'd be nice to support arbitary files through arguments.
[ $# -le 0 ] || return 1
cd || return 2
[ -d rc ] && [ -d sh ] && [ -f .zshrc ] && [ -f .-shrc ] && [ -f .bashrc ] || return 3
: > rc/README.md~ || return 4
local line
if [ -f rc/README.md ]; then
while IFS= read -r line; do
printf '%s\n' "$line" >> rc/README.md~ || return 5
case "$line" in *DOCUMENT*) break;; esac
done < rc/README.md || return 4
fi
printf '\n## %s\n' 'shell functions' >> rc/README.md~ || return 5
for f in sh/*; do
[ -e "$f" ] || continue
document2 "$f" || return $?
done
printf '\n## %s\n' 'miscellaneous' >> rc/README.md~ || return 5
document2 .zshrc || return $?
document2 .bashrc || return $?
document2 .-shrc || return $?
}
document() { ### @ document
### generate a markdown file out of docstrings in shell scripts.
### **TODO:** describe. i have a rough outline written in my scrap file.
document1 "$@"
local ret=$?
case $ret in
0)
return 0;;
1)
printf '%s\n' "$0: too many arguments" >&2
return 1;;
2)
printf '%s\n' "$0: failed to change directory" >&2
return 1;;
3)
printf '%s\n' "$0: essential files are missing" >&2
return 1;;
4)
printf '%s\n' "$0: failed to open file" >&2
return 1;;
5)
printf '%s\n' "$0: failed to read line" >&2
return 1;;
*)
printf '%s\n' "$0: unknown error occurred" >&2
return 1;;
esac
}
[ "${SOURCING:-0}" -gt 0 ] || document "$@"