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
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
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