https://github.com/pawamoy/shellman

Write documentation in comments and render it with templates.
https://github.com/pawamoy/shellman

documentation script shell

Last synced: 15 days ago
JSON representation

Write documentation in comments and render it with templates.

• Host: GitHub
• URL: https://github.com/pawamoy/shellman
• Owner: pawamoy
• License: isc
• Created: 2016-08-07T18:43:48.000Z (over 8 years ago)
• Default Branch: main
• Last Pushed: 2024-01-18T18:59:54.000Z (10 months ago)
• Last Synced: 2024-10-03T12:36:10.416Z (about 1 month ago)
• Topics: documentation, script, shell
• Language: Python
• Homepage: https://pawamoy.github.io/shellman/
• Size: 889 KB
• Stars: 37
• Watchers: 2
• Forks: 1
• Open Issues: 6
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • Contributing: CONTRIBUTING.md
  • Funding: .github/FUNDING.yml
  • License: LICENSE
  • Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

README

        


  



Shell Script Documentation


Write documentation in comments and render it with templates.




  

    

  

  

    

  

  

    

  

  

    

  

  

    

  



`shellman` can generate man pages, wiki pages and help text

using documentation written in shell scripts comments.

For example:

```bash

#!/bin/bash

## \brief Just a demo

## \desc This script actually does nothing.

main() {

  case "$1" in

    ## \option -h, --help

    ## Print this help and exit.

    -h|--help) shellman "$0"; exit 0 ;;

  esac

}

## \usage demo [-h]

main "$@"

```

Output when calling ``./demo -h``:

```

Usage: demo [-h]

This script actually does nothing.

Options:

  -h, --help            Print this help and exit.

```

You can see more examples in the documentation: https://pawamoy.github.io/shellman/.

Demo



In the demo above we saw the three builtin templates:

helptext, manpage and wikipage.

You can use your own templates

by specifying them with the ``--template path:my/template`` syntax.

You can also write a plugin, see the docs: https://pawamoy.github.io/shellman/plugins.

## Installation

With `pip`:

```bash

pip install shellman

```

With [`pipx`](https://github.com/pipxproject/pipx):

```bash

python3.8 -m pip install --user pipx

pipx install shellman

```

## Some projects using shellman

- [shellm](https://github.com/shellm-org) —

  A collection of scripts and libraries

  built on a [core inclusion-system](https://github.com/shellm-org/core),

  all installable with [basher](https://github.com/basherpm/basher).

  Here are a few examples:

  - [daemon](https://github.com/shellm-org/daemon) —

    A library that facilitates the writing of daemonized scripts that consume

    files in a watched directory.

  - [debug](https://github.com/shellm-org/debug) —

    A simple script that sets the verbose/dry-run/debug

    Bash flags before running another script.

  - [format](https://github.com/shellm-org/format) —

    Format your output with style and color.

  - [home](https://github.com/shellm-org/home) —

    A home for your shell scripts! 

  - [loop](https://github.com/shellm-org/loop) —

    Control the flow of your loops (pause/resume/etc.).