13. Tools

Besides the scripts from section 2.5, Document administration, there are a couple of local tools available.

The script bin/inst.sh installs the programs in the appropriate places. See section Activity Diagrams for bin/inst.sh.

13.1. Document Generation Issues

  • ImageMagick permissions problems with PDF (see imagemagick - convert:not authorized aaaa @ error/constitute.c/ReadImage/453):

    In file /etc/ImageMagick-6/policy.xml (or /etc/ImageMagick/policy.xml)

    1. comment line (security risk!)

      <!-- <policy domain="coder" rights="none" pattern="MVG" /> -->

    2. change lines

      <policy domain="coder" rights="none" pattern="PS" />
<policy domain="coder" rights="none" pattern="EPS" />
<policy domain="coder" rights="none" pattern="PDF" />

      to

      <policy domain="coder" rights="read|write" pattern="PS" />
<policy domain="coder" rights="read|write" pattern="EPS" />
<policy domain="coder" rights="read|write" pattern="PDF" />

    3. add line

      <policy domain="coder" rights="read|write" pattern="LABEL" />

  • ImageMagick conversion problems SVG -> PNG with inkscape (see convert aus ImageMagick verhält sich anders)

    In file /etc/ImageMagick-6/delegates.xml (or /etc/ImageMagick/delegates.xml)

    1. change line

      <delegate decode="svg:decode" stealth="True" command="&quot;inkscape&quot; &quot;%s&quot; --export-eps=&quot;%s&quot; --export-dpi=&quot;%s&quot; --export-background=&quot;%s&quot; --export-background-opacity=&quot;%s&quot; &gt; &quot;%s&quot; 2&gt;&amp;1"/>

      to

      <delegate decode="svg:decode" stealth="True" command="&quot;inkscape&quot; &quot;%s&quot; --export-png=&quot;%s&quot; --export-dpi=&quot;%s&quot; --export-background=&quot;%s&quot; --export-background-opacity=&quot;%s&quot; &gt; &quot;%s&quot; 2&gt;&amp;1"/>

      This avoids the mentioned artifacts (actually caused by ghostscript, not inkscape).

13.2. Activity Diagrams for rst2md.sh

@startuml /' a0 '/ skinparam padding 1 partition "rst2md.sh" { start floating note right rst2md.sh - convert ReST to Markdown using pandoc usage: rst2md.sh [FILE ..] Removes ://rem//: comments before conversion. end note if (no arguments supplied?) then (yes) :use standard input,; endif while (for each file argument) is (do) :remove ://rem//: comments; :convert with pandoc to markdown_github; :write to stdout; endwhile stop } /' move before //stop//, if there are subsections '/ @enduml

13.3. Activity Diagrams for sphinx-doc-locate.sh

@startuml /' a0 '/ skinparam padding 1 partition "sphinx-doc-locate.sh" { start floating note right sphinx-doc-locate.sh - locate documentation directories usage: sphinx-doc-locate.sh [OPTIONS] OPTIONS --grep ARG .. run grep-find in directories with ARGS --home special -sed FILTER: only directories in ${HOME} --sed FILTER sed(1) script for filtering directories end note :setup options; while (for each document directory) is (do) if (directory passes //--sed// filter) then (yes) :print directory path; if (//--grep//) then (yes) :run grep-find in directory; endif endif endwhile stop } @enduml

13.4. Activity Diagrams for bin/inst.sh

@startuml /' a0 '/ skinparam padding 1 partition "Install Documentation Requirements" { start floating note right inst.sh - install documentation requirements usage: inst.sh [OPTIONS] OPTIONS | option | args | description | | -l, --link | | install with symbolic links | | -U, --upgrade | | upgrade python package when installing | | -d, --debug | | do not execute commands | | -h, --help | | show this help | | --umlx | RX[:TYP] | extract UML diagrams matching RX | end note if (root?) then (yes) else : run as root; end endif partition "Setup" #ccccee { :Install System Packages| :Extra Application Setup| :Python Environment Configuration| :Select and Install Python Packages| :Install Documentation Tools| } /' move after //stop//, if there are no subsections '/ stop } @enduml

@startuml /' a1 '/ skinparam padding 1 partition "Install System Packages" { :setup needed and wanted system packages; :show host info; :setup ws-local repository; :determine missing packages; :install missing packages; } @enduml

@startuml /' a2 '/ skinparam padding 1 partition "Extra Application Setup" { :PlantUML update; :Install webvector (CSSBox); } @enduml

@startuml /' a3 '/ skinparam padding 1 partition "Python Environment Configuration" { :set PY_PACKAGE_DIRS; while (**for** env **in** SYSTEM PYRAMID) is (set) : set PY_BIN_DIR_env, PY_VER_env, PY_LIB_DIRS_env; : set PY_PACKAGE_PARAM_env with **make_package_param** env| endwhile : set PY_PACKAGE_PARAM_ALL; note right PY_PACKAGE_PARAM_ALL: system /usr/bin /usr/lib/python2.7/dist-packages ... pyramid /usr/local/pyramid/bin /usr/local/pyramid/... end note :Setup Python 2 Site Customization; } @enduml

@startuml /' a4 '/ skinparam padding 1 partition "Select and Install Python Packages" { : generate install programs **py_add_install_package_command** **py_add_install_src_package_command**| note right py_install_system_packages: /usr/bin/easy_install 'src/Sphinx-1.7.4.tar.gz' /usr/bin/easy_install 'src/sphinx-bootstrap-theme-0.6.5.tar.gz' py_install_pyramid_packages: /usr/local/pyramid/bin/easy_install 'src/Sphinx-1.7.4.tar.gz' /usr/local/pyramid/bin/easy_install 'src/python-sphinxcontrib... /usr/local/pyramid/bin/easy_install 'src/sphinx-bootstrap... end note :execute install programs; :check fallback packages; :execute install programs; } @enduml

@startuml /' a5 '/ skinparam padding 1 partition "Install Documentation Tools" { :install PyJsMo; note right install bin_progs: * find_documentation.py * grep-doc.sh * line_diversion.py * sphinx_doc_snip.py * sphinx_doc_glossary.py * rst2md.sh * sphinx-doc-admin.sh * sphinx-doc-init.sh * sphinx-doc-locate.sh * sphinx-doc-update.sh * sphinx-readme.sh to destination directories: * /usr/local/bin * /srv/ftp/pub end note while (for each bin_prog) is (do) if (bin_prog is python) then (yes) :implode with adhoc(1)\nto //dist// directory; if (implode fails) then (yes) :copy from /srv/ftp/pub; if (copy fails) then (yes) end endif endif endif while (for _dest_dir in ${dest_dirs}) is (do) if (test ! -r "${_dest_dir}") then (yes) :vexec mkdir -p "${_dest_dir}"; endif if (test ${opt_debug} = 1 || test -w "${_dest_dir}") then (yes) if (destination file\nis a symbolic link) then (yes) else (no) :copy bin_prog from //dist//\nor current directory to\n//destination directory//; endif endif endwhile endwhile :make shortcut link to sphinx-doc-admin.sh; } @enduml