Multiple input files to multiple output files with links ?

[jeffchulg]

Hi,

I would like to know if you already used this tool to take multiple files (like a set of tools function files and a script) and generate the documentation for the whole.

Would it be possible to make links automatically between those files or is it mandatory to concat everything to one single file to a single MD file too?

I hope my question is quite understandable...

to illustrate a simple scenario :

MyLib.sh
MyScript.sh (in which there is a `. MyLib.sh`)

`shdoc MyLib.sh MyScript.sh`

=> Generates

- MyScript.md
- MyLib.md

If in 'MyScript.sh', there is a `@See MyLibFunction1` then, the is a link to a section in file 'MyLib.md'

[landure]

Hi,

shdoc being based on awk there is no way for shdoc to process multiple files at once.

But using bash scripting and tools such as find or xargs, it's possible to get the same result:

Example using find:

find . -name '*.sh' -exec bash -c 'file="{}" ; shdoc < "${file}" > "${file%.sh}.md"' \;

Example using xargs:

ls *.sh | xargs -I{} bash -c 'file="{}" ; shdoc < "${file}" > "${file%.sh}.md"'

Example using a while loop:

while read -r 'file'; do
  shdoc < "${file}" > "${file%.sh}.md"
done << EOF
MyLib.sh
MyScript.sh
EOF

[landure]

Another example is using make. See biapy-bashlings Makefile make doc action.

[jeffchulg]

Hi @landure

for generating multiple files, I came up with

# -----------------------------------------------------------
#   @file generate-doc.sh
#
#   @brief
#       Shell script to generate markdown documentation
#
#
#   @version
#       0.1.0 - 2023-10-04
#
#   @description
#   
#       Shell script to generate markdown documentation
#
#       
#   @see https://github.com/reconquest/shdoc
#
#   @author
#       Jefferson ELIAS <jefferson.elias@chuliege.be>
#
#
# -----------------------------------------------------------

SCRIPT_NAME="$(basename "$0")"      # This script name
SCRIPT_PATH="$(dirname "$0")"       # Path to this script

SCRIPTS_DOC="$SCRIPT_PATH/docs/scripts"
SHDOC_EXEC="$SCRIPT_PATH/tools/shdoc/shdoc"
SHDOC_ALT="$(eval echo ~/scripts/LinuxTools/tools/shdoc/shdoc)"

if [[ $(ls -la $SHDOC_EXEC 2>/dev/null | wc -l) -eq 0 ]] ; then

    echo "WARN: SHDOC not found at default path '$SHDOC_EXEC'"
    
    #alternate path 
    
    SHDOC_EXEC="$SHDOC_ALT"
    
    echo "INFO: Using alterate path '$SHDOC_EXEC'"
fi

if [[ $(ls -la $SHDOC_EXEC 2>/dev/null | wc -l) -eq 0  ]] ; then
    echo "ERROR: SHDOC not found at default path '$SHDOC_EXEC'"
    exit 1
fi

function generate_script_doc() {
    local filepath="$1"
    local targetFolder="$SCRIPTS_DOC/$(basename $(dirname $filepath))"
    
    mkdir -p $targetFolder
    
    if [[ $? -ne 0 ]] ; then
        echo "ERROR: Unable to create folder '$targetFolder'"
        return 1
    fi
    
    $SHDOC_EXEC < "${filepath}" > "$targetFolder/$(basename ${filepath%.sh}.md)"
    
    return $?
}

mkdir -p $SCRIPTS_DOC

rm -rf "$SCRIPTS_DOC/*"




total_count=0
docs_count=0
errors_count=0

while IFS= read -r i
do
    if [[ "$ENV_DEBUG_ON" == "1" ]] ; then
        echo "INFO: Checking script '$i'"
    fi

    bash -n $i
    
    if [[ $? -ne 0 ]] ; then
        echo "ERROR: script '$i' has syntax errors"
        errors_count=$(( $errors_count + 1 ))
        continue
    fi

    total_count=$(( $total_count +  1 ))
    if [[ $(grep "@description" "$i" 2>/dev/null | wc -l) -gt 0 ]] ; then
        echo "INFO: will generate documentation on file '$i'"
        generate_script_doc "$i"
        
        if [[ $? -ne 0 ]] ; then 
            echo "ERROR: Unable to generate documentation for script '$i'"
            errors_count=$(( $errors_count + 1 ))
            continue
        fi
        docs_count=$(( $docs_count + 1 ))
    fi
    
done<<< "$(find $SCRIPT_PATH -mindepth 1 -type f -name \*.sh ! -path \*/\.svn/* ! -path */tools/\* ! -path \*/assets/\*)"


exit_code=1

if [[ $errors_count -eq 0 ]] ; then
    echo "INFO: Completed successfully - Generated $docs_count documents"

    if [[ $docs_count -ne $total_count ]] ; then
        echo "WARN: $(( $total_count - $docs_count )) scripts are NOT documented"
    fi

    exit_code=0
else
    echo "INFO: Completed with $errors_count error(s)"
fi

Thanks for your help