solenv/bin/mkdocs.sh

   1 #!/usr/bin/env bash
   2 #
   3 # This file is part of the LibreOffice project.
   4 #
   5 # This Source Code Form is subject to the terms of the Mozilla Public
   6 # License, v. 2.0. If a copy of the MPL was not distributed with this
   7 # file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8 #
   9 # Doxygen / README doc generation
  10 #
  11 # See git for contributors
  12 #
  13
  14 function header {
  15   title=$1
  16   breadcrumb=$2
  17   output=$3
  18
  19   cat - > $output <<EOF
  20 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
  21 <html>
  22 <head>
  23     <title>$title</title>
  24
  25     <style>
  26     * { margin: 0; padding: 0; }
  27     body { font-family: sans-serif; font-size: 12px; }
  28         #head { padding: 20px; background: #00A500; }
  29     #head a { color: #000; }
  30     #body { padding: 20px; }
  31     #foot { padding: 10px; font-size: 9px; border-top: 1px #18A303 solid; margin-top: 25px; }
  32     p { line-height: 1.7em; margin-bottom: 1em; }
  33     pre { margin-bottom: 0.5em; }
  34         .multi-col { -moz-column-width: 20em; -webkit-column-width: 20em; -moz-column-gap: 1em; -webkit-column-gap: 1em; }
  35         h1 { margin-bottom: 0.5em; }
  36     h2,h3,h4 { margin: 1.3em 0 0.5em 0; }
  37     ul, ol { margin: 0.5em 1.5em; }
  38     </style>
  39 </head>
  40 <body>
  41     <div id="head">
  42     <h1>$title</h1>
  43     <p>$breadcrumb</p>
  44     </div>
  45         <div id="body" style="multi-col">
  46 EOF
  47 }
  48
  49 function footer {
  50   output=$1
  51
  52   cat - >> $output <<EOF
  53
  54 </div>
  55 <div id="foot">
  56   <small>
  57     <p>Generated by Libreoffice <a href="https://git.libreoffice.org/core/+/refs/heads/master/solenv/bin/mkdocs.sh">Module Description Tool</a></p>
  58     <p>Last updated:
  59 EOF
  60 LANG= date >> $output
  61 cat - >> $output <<EOF
  62     </p>
  63   </small>
  64 </div>
  65 </body>
  66 </html>
  67 EOF
  68
  69 }
  70
  71 function proc_text {
  72   # Local links: [[...]]
  73   # Git links: [git:...]
  74   # Other remote links: [...]
  75   # Headings: == bleh ==
  76   # Paragraphs: \n\n
  77   sed -re ' s/\[\[([-_a-zA-Z0-9]+)\]\]/<a href="\1.html">\1<\/a>/g' - \
  78   | sed -re ' s/\[git:([^]]+)\]/<a href="https:\/\/git.libreoffice.org\/core\/+\/refs\/heads\/master\/\1">\1<\/a>/g' \
  79   | sed -re ' s/\[([^]]+)\]/<a href="\1">\1<\/a>/g' \
  80   | sed -re ' s/====([^=]+)====/<h4>\1<\/h4>/g' \
  81   | sed -re ' s/===([^=]+)===/<h3>\1<\/h3>/g' \
  82   | sed -re ' s/==([^=]+)==/<h2>\1<\/h2>/g' \
  83   | sed -re ':a;N;$!ba;s/\n\n/<\/p><p>/g' \
  84   | awk 'BEGIN { print "<p>" } { print } END { print "</p>" }'
  85 }
  86
  87 function proc_text_markdown {
  88   sed -re ' s/\[git:([^]]+)\]/<a href="\.\.\/\1">\1<\/a>/g'
  89 }
  90
  91 function check_cmd {
  92   cmds_needed="$1"
  93   error_msg="$2"
  94
  95   found=0; cmd=
  96   for cmd_needed in $cmds_needed; do
  97     command -v $cmd_needed > /dev/null && { found=1; cmd=$cmd_needed; }
  98   done
  99   if [ $found = 0 ]; then
 100       echo "$error_msg" >&2
 101       exit 1
 102   fi
 103   export "${cmds_needed%% *}"=$cmd
 104 }
 105
 106 function setup {
 107   parm=$1
 108   if [ -z "${!parm}" ] ; then
 109     echo "grep \"${parm}=\" ./config_host.mk | sed -re \" s/${parm}=//\")"
 110     echo "$parm=$(grep \"${parm}=\" ./config_host.mk | sed -re \" s/${parm}=//\")"
 111     eval "$parm=$(grep \"${parm}=\" ./config_host.mk | sed -re \" s/${parm}=//\")"
 112   fi
 113   if [ -z "${!parm}" ] ; then
 114     echo "could not determine $parm" >&2
 115     exit 1
 116   fi
 117 }
 118
 119 # binaries that we need
 120 check_cmd doxygen "You need doxygen for doc generation"
 121 check_cmd dot "You need the graphviz tools to create the nice inheritance graphs"
 122 check_cmd "markdown markdown2 markdown2-3" "You need either markdown or markdown2 in order to convert README.md into html"
 123
 124 # suck setup
 125 setup "SOLARINC"
 126 shopt -s nullglob
 127
 128 # Title of the documentation
 129 DOXYGEN_PROJECT_PREFIX="LibreOffice"
 130
 131 # get list of modules
 132 if [ -z "$INPUT_PROJECTS" ]; then
 133     INPUT_PROJECTS="`ls */Module_*.mk | sed 's#/.*##'`"
 134 fi
 135
 136
 137 # output directory for generated documentation
 138 BASE_OUTPUT="$1"
 139 mkdir -p "$BASE_OUTPUT" || {
 140     echo "Cannot create $BASE_OUTPUT"
 141     exit 1
 142 }
 143
 144 # paths for binary and configuration file
 145 BASE_PATH=`pwd`
 146 DOXYGEN_CFG="$2"
 147 if test ! -f "$DOXYGEN_CFG"; then
 148     echo "doxygen.cfg not found"
 149     exit 1
 150 fi
 151
 152 # strip -I. and bin -I prefix; exclude system headers
 153 DOXYGEN_INCLUDE_PATH=`echo $SOLARINC | sed -e 's/-I\.//g' -e 's/ -I/ /'g -e 's/ -isystem/ /g' -e 's|/usr/[^ ]*| |g'`
 154
 155 # setup version string
 156 DOXYGEN_VERSION="master"
 157
 158
 159 ###################################################
 160 #
 161 # Generate docs
 162 #
 163 ###################################################
 164
 165 # cleanup
 166 echo "cleaning up" && rm -rf $BASE_OUTPUT/*
 167
 168 # make the stuff world-readable
 169 umask 022
 170
 171 # generate docs
 172 echo "generating doxygen docs"
 173 DOXYGEN_REF_TAGFILES=""
 174 for PROJECT in $INPUT_PROJECTS;
 175 do
 176   # avoid processing of full project subdirs, only add source and inc
 177
 178   # project header files can be in $PROJECT/inc and/or include/$PROJECT
 179   if [ -d "$PROJECT/inc" ]; then
 180       PROJECT_INCLUDE="$PROJECT/inc"
 181   else
 182       PROJECT_INCLUDE=""
 183   fi
 184
 185   if [ -d "include/$PROJECT" ]; then
 186       PROJECT_INCLUDE="$PROJECT_INCLUDE include/$PROJECT"
 187       if [ "$PROJECT" = "sal" ]; then
 188           PROJECT_INCLUDE="$PROJECT_INCLUDE include/osl include/rtl"
 189       fi
 190   fi
 191
 192   DOXYGEN_INPUT=`printf "%s" "$PROJECT/source $PROJECT_INCLUDE"`
 193
 194   DOXYGEN_OUTPUT="$BASE_OUTPUT/$PROJECT"
 195   DOXYGEN_OUR_TAGFILE="$DOXYGEN_OUTPUT/$PROJECT.tags"
 196   DOXYGEN_PROJECTNAME="$DOXYGEN_PROJECT_PREFIX Module $PROJECT"
 197
 198   # export variables referenced in doxygen config file
 199   export DOXYGEN_INPUT
 200   export DOXYGEN_OUTPUT
 201   export DOXYGEN_INCLUDE_PATH
 202   export DOXYGEN_VERSION
 203   export DOXYGEN_OUR_TAGFILE
 204   export DOXYGEN_REF_TAGFILES
 205   export DOXYGEN_PROJECTNAME
 206
 207   # debug
 208   echo "Calling $DOXYGEN_PATH/doxygen $DOXYGEN_CFG with"
 209   echo "Input:      $DOXYGEN_INPUT"
 210   echo "Output:     $DOXYGEN_OUTPUT"
 211   echo "Include:    $DOXYGEN_INCLUDE_PATH"
 212   echo "Version:    $DOXYGEN_VERSION"
 213   echo "Tagfile:    $DOXYGEN_OUR_TAGFILE"
 214   echo "Ref-Tags:   $DOXYGEN_REF_TAGFILES"
 215   echo "Title:      $DOXYGEN_PROJECTNAME"
 216
 217   nice -15 doxygen "$DOXYGEN_CFG" >>$BASE_OUTPUT/doxygen.log 2>&1 || exit 1
 218
 219   # setup referenced tagfiles for next round
 220   DOXYGEN_REF_TAGFILES="$DOXYGEN_REF_TAGFILES $DOXYGEN_OUR_TAGFILE=$BASE_URL/$PROJECT/html"
 221 done
 222
 223 # generate entry page
 224 echo "generating index page"
 225 header "LibreOffice Modules" " " "$BASE_OUTPUT/index.html"
 226 for module_name in *; do
 227   if [ -d $module_name ]; then
 228     cur_file=$(echo $module_name/README.md)
 229     if [ -f "$cur_file" ]; then
 230       # write index.html entry
 231       text=$(echo -e "<h2><a href=\"${module_name}.html\">${module_name}</a></h2>\n")
 232
 233       if [ ${cur_file: -3} == ".md" ]; then
 234         # This is a markdown file.
 235         header_text="$(head -n1 $cur_file)"
 236         header_text="$(echo ${header_text} | sed -e 's/^\#*//g')"
 237         text="${text}${header_text}"
 238       else
 239         text="${text}$(head -n1 $cur_file | proc_text)"
 240       fi
 241       echo -e "$text" >> "$BASE_OUTPUT/index.html"
 242
 243       # write detailed module content
 244       header "$module_name" "<a href=\"index.html\">LibreOffice</a> &raquo; ${module_name}" "$BASE_OUTPUT/${module_name}.html"
 245       text="<p><b>View module in:</b>"
 246       text="${text} &nbsp; <a href=\"https://git.libreoffice.org/core/+/refs/heads/master/${module_name}\">git</a>"
 247       if $(echo $INPUT_PROJECTS | grep -q $module_name); then
 248         text="${text} &nbsp; <a href=\"${module_name}/html/classes.html\">Doxygen</a>"
 249       fi
 250       text="${text} </p><p>&nbsp;</p>"
 251       echo -e "$text" >> "$BASE_OUTPUT/${module_name}.html"
 252
 253       if [ ${cur_file: -3} == ".md" ]; then
 254         # This is a markdown file.
 255         text="$(${markdown} $cur_file | proc_text_markdown)"
 256         echo -e "$text" >> "$BASE_OUTPUT/${module_name}.html"
 257       else
 258         proc_text < $cur_file >> "$BASE_OUTPUT/${module_name}.html"
 259       fi
 260       footer "$BASE_OUTPUT/${module_name}.html"
 261     else
 262       empty_modules[${#empty_modules[*]}]=$module_name
 263     fi
 264   fi
 265 done
 266
 267 if [ ${#empty_modules[*]} -gt 10 ]; then
 268   echo -e "<p>&nbsp;</p><p>READMEs were not available for these modules:</p><ul>\n" >> "$BASE_OUTPUT/index.html"
 269   for module_name in "${empty_modules[@]}"; do
 270     # Do not process these directories
 271     if [[ "$module_name" =~ ^(autom4te.cache|dictionaries|docs|helpcompiler|helpcontent2|include|instdir|lo|translations|workdir)$ ]]; then
 272       continue
 273     fi
 274     echo -e "<li><a href=\"https://git.libreoffice.org/core/+/refs/heads/master/${module_name}\">${module_name}</a></li>\n" >> "$BASE_OUTPUT/index.html"
 275   done
 276   echo -e "</ul>\n" >> "$BASE_OUTPUT/index.html"
 277 fi
 278
 279 footer "$BASE_OUTPUT/index.html"
 280
 281 ## done