Metadata-Version: 2.1
Name: shellman
Version: 1.0.1
Summary: Write documentation in comments and render it with templates.
Author-Email: =?utf-8?q?Timoth=C3=A9e_Mazzucotelli?= <dev@pawamoy.fr>
License: ISC
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Project-URL: Homepage, https://pawamoy.github.io/shellman
Project-URL: Documentation, https://pawamoy.github.io/shellman
Project-URL: Changelog, https://pawamoy.github.io/shellman/changelog
Project-URL: Repository, https://github.com/pawamoy/shellman
Project-URL: Issues, https://github.com/pawamoy/shellman/issues
Project-URL: Discussions, https://github.com/pawamoy/shellman/discussions
Project-URL: Gitter, https://gitter.im/shellman/community
Project-URL: Funding, https://github.com/sponsors/pawamoy
Requires-Python: >=3.9
Requires-Dist: jinja2>=3
Requires-Dist: importlib-metadata>=4.6; python_version < "3.10"
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://rawgit.com/pawamoy/shellman/master/logo.png">
</p>

<h1 align="center">Shell Script Documentation</h1>

<p align="center">Write documentation in comments and render it with templates.</p>

<p align="center">
  <a href="https://github.com/pawamoy/shellman/actions?query=workflow%3Aci">
    <img alt="ci" src="https://github.com/pawamoy/shellman/workflows/ci/badge.svg" />
  </a>
  <a href="https://pawamoy.github.io/shellman/">
    <img alt="documentation" src="https://img.shields.io/badge/docs-mkdocs%20material-blue.svg?style=flat" />
  </a>
  <a href="https://pypi.org/project/shellman/">
    <img alt="pypi" src="https://img.shields.io/pypi/v/shellman.svg" />
  </a>
  <a href="https://gitpod.io/#https://github.com/pawamoy/shellman">
    <img alt="gitpod" src="https://img.shields.io/badge/gitpod-workspace-blue.svg?style=flat" />
  </a>
  <a href="https://gitter.im/shellman/community">
    <img alt="gitter" src="https://badges.gitter.im/join%20chat.svg" />
  </a>
</p>

`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/.

<h2 align="center">Demo</h2>
<p align="center"><img src="https://rawgit.com/pawamoy/shellman/master/demo.svg"></p>

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

```bash
pip install shellman
```

With [`uv`](https://docs.astral.sh/uv/):

```bash
uv tool 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.).
