«Стандартизированная» строка документации / самодокументирование скриптов bash

Question

Фон

Например, скрипты Python могут иметь несколько «уровней» документации через docstrings.Что в этом хорошего, так это то, что они могут быть определены на уровне отдельных функций, уровнях методов, уровнях классов и, самое главное (в контексте моего вопроса): уровнях файлов.Например, верхняя часть файла может выглядеть так:

#!/usr/bin/env python
"""
@brief  A script that does cool stuff.
"""

Что особенно полезно в этой функции, так это то, что ее легко извлечь и распечатать во время выполнения.

---

Вопрос

Поддерживают ли сценарии bash такую ​​функцию?т. е. существует ли «стандартизированный» подход к созданию набора документации на уровне файлов (т. е. удобочитаемое описание цели сценария, usage синтаксис и т. д., так что это легко для другогосценарий для автоматического анализа / извлечения этой информации? Моя цель - создать несколько сценариев отладки, которые самодокументируются, и, если для этого уже существует стандартный / де-факто лучший способ, я бы хотел-изобретая колесо.

Answer 1

Раздел «Заголовок файла» руководства по стилю оболочки Google - это один из способов добавить строку документации в ваши скрипты bash.

По сути, ответом является использование #вместо кавычек, как с Python.

Answer 2

Вы можете сделать это для Bash легко, это немного сложнее, если вам нужно обеспечить совместимость только с оболочками POSIX, такими как / bin / sh, и в основном с занятыми системами, такими как Alpine.

Проект документации Linux имеетВот несколько замечательных примеров.

http://tldp.org/LDP/abs/html/here-docs.html

Еще один поворот этого изящного трюка делает возможным «самодокументирование» сценариев.

Пример 19-12.Самодокументируемый скрипт

#!/bin/bash
# self-document.sh: self-documenting script
# Modification of "colm.sh".

DOC_REQUEST=70

if [ "$1" = "-h"  -o "$1" = "--help" ]     # Request help.
then
  echo; echo "Usage: $0 [directory-name]"; echo
  sed --silent -e '/DOCUMENTATIONXX$/,/^DOCUMENTATIONXX$/p' "$0" |
  sed -e '/DOCUMENTATIONXX$/d'; exit $DOC_REQUEST; fi


: <<DOCUMENTATIONXX
List the statistics of a specified directory in tabular format.
---------------------------------------------------------------
The command-line parameter gives the directory to be listed.
If no directory specified or directory specified cannot be read,
then list the current working directory.

DOCUMENTATIONXX

if [ -z "$1" -o ! -r "$1" ]
then
  directory=.
else
  directory="$1"
fi  

echo "Listing of "$directory":"; echo
(printf "PERMISSIONS LINKS OWNER GROUP SIZE MONTH DAY HH:MM PROG-NAME\n" \
; ls -l "$directory" | sed 1d) | column -t

exit 0

Использование сценария cat - альтернативный способ сделать это.

DOC_REQUEST=70

if [ "$1" = "-h"  -o "$1" = "--help" ]     # Request help.
then                                       # Use a "cat script" . . .
  cat <<DOCUMENTATIONXX
List the statistics of a specified directory in tabular format.
---------------------------------------------------------------
The command-line parameter gives the directory to be listed.
If no directory specified or directory specified cannot be read,
then list the current working directory.

DOCUMENTATIONXX
exit $DOC_REQUEST
fi

Несколько более элегантный пример использования функций для обработки документации исообщения об ошибках.

#!/bin/sh

usage() {
cat << EOF
Usage: 
  $0 [-u [username]] [-p]
  Options:
    -u <username> : Optionally specify the new username to set password for.  
    -p : Prompt for a new password.
EOF
}

die() {
  echo
  echo "$1, so giving up.  Sorry."
  echo
  exit 2
}

if [ -z "$USER" ] ; then
  die "Could not identify the existing user"
fi

if $PSET ; then
  passwd $USER || die "Busybox didn't like your password"
fi

https://github.com/jyellick/mficli/blob/master/util/changecreds.sh

Answer 3

Стандартов для строк документации для bash не существует.Хотя всегда приятно иметь справочные страницы (например, https://www.cyberciti.biz/faq/linux-unix-creating-a-manpage/), или информационные страницы (https://unix.stackexchange.com/questions/164443/how-to-create-info-documentation).

).