From 93da82afad9221373e17d488dcff07f41542c04a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Thu, 2 Aug 2018 19:38:07 +0200 Subject: [PATCH] Initial commit --- .editorconfig | 16 ++++++++++++ .gitignore | 50 ++++++++++++++++++++++++++++++++++++++ CHANGELOG.md | 1 + CONTRIBUTING.md | 21 ++++++++++++++++ LICENSE | 15 ++++++++++++ Makefile | 39 +++++++++++++++++++++++++++++ README.md | 35 ++++++++++++++++++++++++++ bin/doc | 54 +++++++++++++++++++++++++++++++++++++++++ cmp/doc.completion.bash | 0 cmp/doc.completion.zsh | 0 man/doc.1 | 0 man/doc.sh.3 | 0 package.sh | 4 +++ 13 files changed, 235 insertions(+) create mode 100644 .editorconfig create mode 100644 .gitignore create mode 100644 CHANGELOG.md create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE create mode 100644 Makefile create mode 100644 README.md create mode 100755 bin/doc create mode 100644 cmp/doc.completion.bash create mode 100644 cmp/doc.completion.zsh create mode 100644 man/doc.1 create mode 100644 man/doc.sh.3 create mode 100644 package.sh diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..53e9d3a --- /dev/null +++ b/.editorconfig @@ -0,0 +1,16 @@ +root = true + +[*] +charset = utf-8 +# end_of_line = git +indent_size = 2 +indent_style = space +insert_final_newline = true +trim_trailing_whitespace = true + +[*.py] +indent_size = 4 +indent_style = space + +[*.md] +trim_trailing_whitespace = false diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..056098a --- /dev/null +++ b/.gitignore @@ -0,0 +1,50 @@ + +# Created by https://www.gitignore.io/api/windows,osx,linux,git + +### OSX ### +*.DS_Store +.AppleDouble +.LSOverride + +# Icon must end with two \r +Icon +# Thumbnails +._* +# Files that might appear in the root of a volume +.DocumentRevisions-V100 +.fseventsd +.Spotlight-V100 +.TemporaryItems +.Trashes +.VolumeIcon.icns +.com.apple.timemachine.donotpresent +# Directories potentially created on remote AFP share +.AppleDB +.AppleDesktop +Network Trash Folder +Temporary Items +.apdisk + + +### Linux ### +*~ + +# temporary files which can be created if a process still has a handle open of a deleted file +.fuse_hidden* + +# KDE directory preferences +.directory + +# Linux trash folder which might appear on any partition or disk +.Trash-* + +# .nfs files are created when an open file is removed but is still being accessed +.nfs* + + +### Git ### +*.orig + +### Custom ### +deps/ +wiki/ diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..420e6f2 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1 @@ +# Change Log diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..a355c91 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,21 @@ +# Contributing +Contributions are welcome, and they are greatly appreciated! + +Every little bit helps, and credit will always be given. + +## Types of Contributions + +### Bug Reports, Feature Requests, and Feedback +Create a [new project issue][1]! Try to be as descriptive as possible. + +### Bug Fixes, New Features and Documentation +Create a [new merge/pull request][2]! Make sure to follow the guidelines. + +## Merge/Pull Request Guidelines +Make sure to have atomic commits and contextual commit messages! + +[Check out this awesome blog post by Chris Beams for more information.][3] + +[1]: https://gitlab.com/shellm/doc/issues/new +[2]: https://github.com/shellm/doc/merge_requests/new +[3]: http://chris.beams.io/posts/git-commit/ diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..1520d57 --- /dev/null +++ b/LICENSE @@ -0,0 +1,15 @@ +ISC License + +Copyright (c) 2018, Timothée Mazzucotelli + +Permission to use, copy, modify, and/or distribute this software for any +purpose with or without fee is hereby granted, provided that the above +copyright notice and this permission notice appear in all copies. + +THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..1717a91 --- /dev/null +++ b/Makefile @@ -0,0 +1,39 @@ +.PHONY: rmdoc + +BINDIR := bin +LIBDIR := lib +MANDIR := man +WIKIDIR := wiki + +MANPAGES := $(addprefix $(MANDIR)/,doc.1 doc.sh.3) +WIKIPAGES := $(addprefix $(WIKIDIR)/,bin/doc.md lib/doc.sh.md) + +ifeq ($(PREFIX), ) +PREFIX := /usr/local +endif + +all : doc + +install : + @./install.sh $(PREFIX) + +$(MANDIR)/%.1 : $(BINDIR)/% + @shellman --format man $< > $@ + +$(MANDIR)/%.sh.3 : $(LIBDIR)/%.sh + @shellman --format man $< > $@ + +$(WIKIDIR)/bin/%.md : $(BINDIR)/% + @shellman --format markdown $< > $@ + +$(WIKIDIR)/lib/%.sh.md : $(LIBDIR)/%.sh + @shellman --format markdown $< > $@ + +man : $(MANPAGES) + +wiki : $(WIKIPAGES) + +doc : man wiki + +rmdoc: + @rm man/* wiki/bin/* wiki/lib/* diff --git a/README.md b/README.md new file mode 100644 index 0000000..6175de9 --- /dev/null +++ b/README.md @@ -0,0 +1,35 @@ +# doc +Documentation for your shell scripts! + +- Authors: https://gitlab.com/shellm/doc/AUTHORS.md +- Changelog: https://gitlab.com/shellm/doc/CHANGELOG.md +- Contributing: https://gitlab.com/shellm/doc/CONTRIBUTING.md +- Documentation: https://gitlab.com/shellm/doc/wiki +- License: ISC - https://gitlab.com/shellm/doc/LICENSE + +## Installation +Installation with [basher](https://github.com/basherpm/basher): +```bash +basher install shellm/doc +``` + +Installation from source: +```bash +git clone https://gitlab.com/shellm/doc +cd doc +sudo ./install.sh +``` + +## Usage +Command-line: +``` +doc -h +``` + +As a library: +```bash +# with basher's include +include shellm/doc lib/doc.sh +# with shellm's include +shellm-include shellm/doc lib/doc.sh +``` diff --git a/bin/doc b/bin/doc new file mode 100755 index 0000000..01578dd --- /dev/null +++ b/bin/doc @@ -0,0 +1,54 @@ +#!/usr/bin/env bash + +## \brief Documentation for your shell scripts! + +shellm-source shellm/doc + +if [ $# -eq 0 ]; then + doc --print-usage "$0" + exit 1 +fi + +__doc_get() { + local re='^[[:space:]]*##[[:space:]]*[@\]'"$1"'[[:space:]]' + grep "${re}" "$2" | expand | sed 's/'"${re}"'*//' + # shellcheck disable=SC2086 + return ${PIPESTATUS[0]} +} + +main() { + while [ $# -ne 0 ]; do + case "$1" in + ## \option -h, --help + ## Print this help and exit. + -h|--help) doc --print-help "$0"; exit 0 ;; + + ## \option --print-help SCRIPT + ## Print help for the given script. + --print-help) + if ! command -v shellman &>/dev/null; then + if ! man "$(basename "$1")"; then + echo "doc: please install shellman dependency with pip install shellman" >&2 + return 1 + fi + return 0 + fi + shellman "$1" + ;; + + ## \option --print-usage SCRIPT + ## Print usage for the given script. + --print-usage) + usages="$(__doc_get usage "$1")" + echo "usage: $(echo "${usages}" | head -n1)" + echo "${usages}" | tail -n+2 | while read -r line; do + echo " ${line}" + done + ;; + esac + shift + done +} + +## \usage doc [-h] +main "$@" diff --git a/cmp/doc.completion.bash b/cmp/doc.completion.bash new file mode 100644 index 0000000..e69de29 diff --git a/cmp/doc.completion.zsh b/cmp/doc.completion.zsh new file mode 100644 index 0000000..e69de29 diff --git a/man/doc.1 b/man/doc.1 new file mode 100644 index 0000000..e69de29 diff --git a/man/doc.sh.3 b/man/doc.sh.3 new file mode 100644 index 0000000..e69de29 diff --git a/package.sh b/package.sh new file mode 100644 index 0000000..742c48d --- /dev/null +++ b/package.sh @@ -0,0 +1,4 @@ +BINS="bin/doc" +DEPS="gitlab.com/shellm/core" +BASH_COMPLETIONS="cmp/doc.completion.bash" +ZSH_COMPLETIONS="cmp/doc.completion.zsh"