Tools

Besides the scripts from chapter 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.

Python modules:

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

      <!-- <policy domain="coder" rights="none" pattern="MVG" /> -->
      
    2. change line

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

      to

      <policy domain="coder" rights="read|write" pattern="PDF" />
      
    3. add line

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

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

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

Activity Diagrams for bin/inst.sh

@startuml /' a0 '/
skinparam padding 1
!include call-behavior.puml
partition "Install Documentation Requirements" {
start
floating note right
inst.sh - install documentation requirements

usage: inst.sh
end note
if (root) then (yes)
else
: run as root;
end
endif
:Install System Packages|
:Extra Application Setup|
:Python Environment Configuration|
:Select and Install Python Packages|
:Install Documentation Tools|
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
!include call-behavior.puml
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;
:    CALL(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
!include call-behavior.puml
partition "Select and Install Python Packages" {
:generate install programs
CALL(**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:
* 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)
            :mkdir -p "${_dest_dir}";
        endif
        if (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