z.digitalclouds.dev | GitHub | Discussions | Localize


문서화, 공동 작업 또는 매뉴얼로 사용할 수 있도록 스크립트를 구문 분석하고 주석을 추출하는 도구가 있다면? 이동 중에 문서를 작성하는 동안 코드에 집중할 수 있도록 모든 것이 자동화될 수 있다면? 우리는 당신의 등을 ...

Contribute to making it better and get shared extra tools from our projects which are shared between contributors only.
Codenewbies with the right attitude is always welcome.

쉘 스크립트용 Doxygen**

Example of our Z Shell code - https://z.digitalclouds.dev/docs/code

다음을 사용하여 Zsh 및 Bash 스크립트를 구문 분석하고 Asciidoc 문서를 출력합니다.

자동 로드 기능을 포함한 기능 목록,

함수 및 스크립트 본문의 호출 ​​트리,

함수에 대한 주석,

각 기능 및 스크립트 본문에 사용되는 기능(예: eval , read , vared , shopt 등),

add-zsh-hook (Zsh),

에 등록된 후크에 대한 고유 표시

내보낸 변수 목록,

사용된 내보낸 변수 목록과 변수의 출처(예: 다른 스크립트일 수 있음).

호출 트리는 교차 파일 호출(즉, 스크립트가 다른 파일에 정의된 함수를 호출할 때)을 지원합니다.
Zshell 언어로 작성되었습니다.

설치

기본 설치 경로 접두사는 /usr/local 입니다.

git clone https://github.com/z-shell/zsdoc
cd doc
make
sudo make install

PREFIX 호출에서 사용자 정의make 변수의 경우:

# 'sudo' may be required to install

make install PREFIX=~/opt/local
install -c -d ~/opt/local/share/zsdoc
install -c -d ~/opt/local/share/doc/zsdoc

cp build/zsd build/zsd-transform build/zsd-detect build/zsd-to-adoc ~/opt/local/bin
cp README.md NEWS LICENSE ~/opt/local/share/doc/zsdoc
cp zsd.config ~/opt/local/share/zsdoc

➜ cd ~/opt/local

➜ tree.
        ├── bin
        │   ├── zsd
        │   ├── zsd-detect
        │   ├── zsd-to-adoc
        │   └── zsd-transform
        │
        └── share
           ├── doc
           │   └── zsdoc
           │       ├── LICENSE
           │       ├── NEWS
           │       └── README.md
           │
           └── zsdoc
               └── zsd.config

기타 사용 가능한 make 변수는 다음과 같습니다.

용법

zsd [-h/--help] [-v/--verbose] [-q/--quiet] [-n/--noansi] [--cignore <pattern>] {file1} [file2] ...

The files will be processed and their documentation will be generated in subdirectory `zsdoc' (with meta-data in subdirectory `data').

Options:
-h/--help      Usage information
-v/--verbose   More verbose operation-status output
-q/--quiet     No status messages
-n/--noansi    No colors in terminal output
--cignore      Specify which comment lines should be ignored
-f/--fpath     Paths are separated by: pointing to directories with functions
--synopsis     Text to be used in the SYNOPSIS section. Line break "... +\n", paragraph "...\n\n"
--scomm        Strip comment char "#" from function comments
--bash         Output is slightly tailored to Bash specifics (instead of Zsh specifics)

예INSTALL 옵션:

--cignore '\#*FUNCTION:*{{{*'                 - ignore comments like # FUNCTION: usage {{{
--cignore '(\#*FUNCTION:*{{{*|\#*FUN:*{{{*)'  - also ignore comments like: # FUN: usage {{{

The file is parsed for synopsis block, which can be e.g.:
# synopsis {{{my synopsis, can be multi-line}}}

구문 분석되는 또 다른 블록은 환경 변수에 대한 주석입니다. 여러개로 구성되어 있습니다
"VAR_NAME -> var description"줄과 출력 AsciiDoc 문서의 테이블에 결과가 표시됩니다.


예시:

# env-vars {{{
# PATH -> paths to executables
# MANPATH -> paths to manuals }}}

기본 중괄호 블록 구분 기호를 BIN_DIR , SHARE_DIR 로 변경합니다. 블록 본문은 AsciiDoc이어야 합니다.

예

example 1 ,
example 2
(또한 PDF:
example 1 ,
example 2 ).

몇 가지 규칙

프로젝트에서 사용하는 데 도움이 되는 몇 가지 규칙DOC_DIR:

함수 앞에 함수 주석을 작성합니다. 주석과 함수 사이에 빈 줄이 허용됩니다.

특별한 주석을 사용하는 경우. --cignore (또는 --blocka ) 접는 경우 --blockb (Usage 참조)가 있는 이 줄을 무시할 수 있습니다.

피할 수 있는 경우 zsdoc 그렇게 하십시오. 그러면 vim가 더 많은 코드를 분석합니다.

현재 함수에 정의된 함수는 무시되지만 곧 변경될 예정입니다.

데이터 처리를 위해 새 emacs-origami 버전( --cignore )을 크게 최적화했습니다. eval 해당 zsdoc 버전에서 시작하여 긴 소스를 매우 빠르게 구문 분석합니다.

여러 버전Zsh이 설치되어 있는 경우 (예를 들어) 5.4.2에서 zsdoc를 설정합니다.

스크립트 그룹을 변환하려면 Zsh만 있으면 됩니다. 교차 파일 함수 호출이 자동으로 작동하고 여러 파일Zsh이 생성됩니다.

zsh_control_bin="/usr/local/bin/zsh-5.4.2" 대상으로 /usr/local/share/zsdoc/zsd.config를 생성합니다. 즉, zsd file1.zsh file2.zsh ... 입니다. 설명서는 *.adoc 디렉토리에 있습니다.

디렉토리Makefile에는 doc개의 문서(rm -rf zsdoc/data; zsd -v file1.zsh ...개의 파일)를 만드는 데 사용되는 메타 데이터가 있습니다. 제거하거나 직접 분석할 수 있습니다.

다음을 통해 Asciidoctor 도구를 사용하여 PDF를 가져옵니다. zsdoc . 다음과 함께 zsdoc/data를 설치합니다: asciidoc . (체크 아웃 ZI's Makefile .)

HTML: *.adoc .

다음을 통해 asciidoctor -b pdf -r asciidoctor-pdf file1.zsh.adoc 패키지로 매뉴얼 페이지를 얻습니다.

Github는 Asciidoctor 문서를 지원하고 자동으로 렌더링합니다.