ItEr29S15DocumentacionFormacionItEr25S04: User document in reStructured text with some tools for making HTML and Pdf.

doc/src/asignacion/asignacion.rst

@@ -0,0 +1,6 @@
+Asignación de recursos
+######################
+
+.. contents::
+
+Contidos...

doc/src/avances/avances.rst

@@ -0,0 +1,7 @@
+Avances
+#######
+
+.. contents::
+
+Contidos...
+

doc/src/calendarios/calendarios.rst

@@ -0,0 +1,6 @@
+Calendarios
+###########
+
+.. contents::
+
+Contidos...

doc/src/criterios/criterios.rst

@@ -0,0 +1,6 @@
+Criterios
+#########
+
+.. contents::
+
+Contidos...

doc/src/etiquetas/etiquetas.rst

@@ -0,0 +1,7 @@
+Etiquetas 
+#########
+
+.. contents::
+
+Contidos...
+

doc/src/introducion/.#introducion.rst

@@ -0,0 +1 @@
+xavi@127.0.1.1.4137:1254405172

doc/src/introducion/introducion.rst

@@ -0,0 +1,18 @@
+Introdución
+##############
+
+.. contents::
+
+A aplicación para xestión da produción do sector auxiliar do naval pretende resolver principalmente o problema da planificación nas empresas pertencentes ó sector. Para elo desenvolvéronse unha serie de funcionalidades que dan solución a certos problemas detectados durante a análise do proxecto.
+
+A modo de resumo, poderíamos destacar os conceptos básicos cos que traballará a aplicación
+   * Criterios: Os criterios son unha entidade do sistema que permitirán clasificar os recursos (tanto humanos como máquinas) e as tarefas. Os recursos satisfarán criterios e por outro lado as tarefas requiren criterios para ser realizadas.
+   * Calendarios: Os calendarios determinarán as horas produtivas dispoñibles dos diferentes recursos. O usuario poderá crear calendarios xerais da empresa e derivar as características para calendarios máis concretos, chegando ata a nivel de calendario por recurso ou tarefa.
+   * Avances: A aplicación permitirá xestionar diversos tipos de avances. Un proxecto pode ser medido en porcentaxe de avance, sen embargo, pode querer ser medido en unidades, presuposto acordado, etc. Será responsabilidade da persoa que xestiona a planificación decidir qué tipo de avance será utilizado para contrastar avances a niveis superiores de proxecto. 
+   * Recursos: Serán de dous tipos diferentes: humanos e máquinas. Os recursos humanos serán os traballadores da empresa que se utilizarán para controlar a carga da empresa e de uso dos mesmos. Por outro lado, as máquinas, dependentes das persoas que as xestionan, serán outros recursos que tamén serán controlables na aplicación.
+   * Pedido e elementos de pedido: Os traballos solicitados polos clientes terán un reflexo na aplicación en forma de pedido, que se estrutura en elementos de pedido. O pedido cos seus elementos conformarán unha estrutura xerárquina en n niveis. Esta árbore de elementos será sobre a que se traballe á hora de planificar traballos.
+   * Tarefas: As tarefas son los elementos de planificación da aplicación. Serán utilizadas para temporalizar os traballos a realizar. As características máis importantes das tarefas serán: teñen dependencias entre si e poden requerir criterios a ser satisfeitos para asignar recursos.
+   * Partes de traballo: Son os partes dos traballadores das empresas, indicando as horas traballadas e por outro lado as tarefas asignadas ás horas que un traballador realizou. Con esta información, o sistema é capaz de calcular cantas horas foron consumidas dunha tarefa con respecto ó total de horas presupostadas, permitindo contrastar os avances respecto do consumo de horas real.
+   * Etiquetas: Serán elementos que se usarán para o etiquetado das tarefas dos proxectos. Con estas etiquetas o usuario da aplicación poderá realizar agrupacións conceptuais das tarefas para posteriormente poder consultar información das mesmas de xeito agrupado e filtrado.
+
+

doc/src/lsr.css

@@ -0,0 +1,251 @@
+/*
+Author: Peter Parente
+Date: 2008/01/22
+Version: 1.0
+Copyright: This stylesheet has been placed in the public domain - free to edit and use for all uses.
+*/
+
+body {
+  font: 100% sans-serif;
+  background: #ffffff;
+  color: black;
+  margin: 2em;
+  padding: 0em 2em;
+}
+
+p.topic-title {
+  font-weight: bold;
+}
+
+table.docinfo {
+  text-align: left;
+  margin: 2em 0em;
+}
+
+a[href] {
+  color: #436976;
+  background-color: transparent;
+}
+
+a.toc-backref {
+  text-decoration: none;
+}
+
+h1 a[href] {
+  color: #003a6b;
+  text-decoration: none;
+  background-color: transparent;
+}
+
+a.strong {
+  font-weight: bold;
+}
+
+img {
+  margin: 0;
+  border: 0;
+}
+
+p {
+  margin: 0.5em 0 1em 0;
+  line-height: 1.5em;
+}
+
+p a:visited {
+  color: purple;
+  background-color: transparent;
+}
+
+p a:active {
+  color: red;
+  background-color: transparent;
+}
+
+a:hover {
+  text-decoration: none;
+}
+
+p img {
+  border: 0;
+  margin: 0;
+}
+
+p.rubric {
+  font-weight: bold;
+  font-style: italic;
+}
+
+h1.title {
+  color: #003a6b;
+  font-size: 250%;
+  margin-bottom: 0em;
+}
+
+h2.subtitle {
+  color: #003a6b;
+  border-bottom: 0px;
+}
+
+h1, h2, h3, h4, h5, h6 {
+  color: #555;
+  background-color: transparent;
+  margin: 0em;
+  padding-top: 0.5em;
+}
+
+h1 {
+  font-size: 160%;
+  margin-bottom: 0.5em;
+  border-bottom: 2px solid #aaa;
+}
+
+h2 {
+  font-size: 140%;
+  margin-bottom: 0.5em;
+  border-bottom: 1px solid #aaa;
+}
+
+h3 {
+  font-size: 130%;
+  margin-bottom: 0.5em;
+}
+
+h4 {
+  font-size: 110%;
+  font-weight: bold;
+  margin-bottom: 0.5em;
+}
+
+h5 {
+  font-size: 105%;
+  font-weight: bold;
+  margin-bottom: 0.5em;
+}
+
+h6 {
+  font-size: 100%;
+  font-weight: bold;
+  margin-bottom: 0.5em;
+}
+
+dt {
+  font-style: italic;
+}
+
+dd {
+  margin-bottom: 1.5em;
+}
+
+div.admonition, div.note, div.tip, div.caution, div.important, div.warning {
+  margin: 2em 2em;
+  padding: 0em 1em;
+  border-top: 1px solid #aaa;
+  border-left: 1px solid #aaa;
+  border-bottom: 2px solid #555;
+  border-right: 2px solid #555;
+}
+
+div.important {
+  background: transparent url('../images/important.png') 10px 2px no-repeat;
+}
+
+div.caution {
+  background: transparent url('../images/caution.png') 10px 2px no-repeat;
+}
+
+div.note {
+  background: transparent url('../images/note.png') 10px 2px no-repeat;
+}
+
+div.tip {
+  background: transparent url('../images/tip.png') 10px 2px no-repeat;
+}
+
+div.admonition-example {
+  background: transparent url('../images/tip.png') 10px 2px no-repeat;
+}
+
+div.admonition-critical-example {
+  background: transparent url('../images/important.png') 10px 2px no-repeat;
+}
+
+p.admonition-title {
+  font-weight: bold;
+  border-bottom: 1px solid #aaa;
+  padding-left: 30px;
+}
+
+table.docutils {
+  text-align: left;
+  border: 1px solid gray;
+  border-collapse: collapse;
+  width: 100%;
+  margin: 1.5em 0em;
+}
+
+table.docutils caption {
+  font-style: italic;
+}
+
+table.docutils td, table.docutils th {
+  padding: 0.25em 0.5em;
+}
+
+table.docutils th {
+  background-color: #dddddd;
+}
+
+div.sidebar {
+  width: 33%;
+  float: right;
+  margin: 0em 2em;
+  padding: 0em 1em;
+  border-top: 1px solid #aaa;
+  border-left: 1px solid #aaa;
+  border-bottom: 2px solid #555;
+  border-right: 2px solid #555;
+}
+
+p.sidebar-title {
+  margin-bottom: 0em;
+  color: #003a6b;
+  border-bottom: 1px solid #aaa;
+  font-weight: bold;
+}
+
+p.sidebar-subtitle {
+  margin-top: 0em;
+  font-style: italic;
+  color: #003a6b;
+}
+
+div.figure {
+	text-align: center;
+}
+
+div.figure img {
+	background: #f8f8f8;
+	padding: 0.25em;
+	border: 1px solid #888;
+	border-radius: 5px;
+	-moz-border-radius: 5px;
+	-webkit-border-radius: 5px;
+}
+
+div.figure img:hover {
+	background: #e0e0e0;
+}
+
+div.figure p.caption {
+	text-align: center;
+	margin-top: 0.1em;
+	font-style: italic;
+	color: #444;
+}
+
+pre.literal-block {
+	padding: 0.15em;
+	background: #f8f8f8;
+	border: 1px solid #dfdfdf;
+	border-left: 0.25em solid #dfdfdf
+}

doc/src/partes/partes.rst

@@ -0,0 +1,7 @@
+Partes de traballo
+##################
+
+.. contents::
+
+Contidos...
+

doc/src/parts

@@ -0,0 +1,20 @@
+#
+# First word:
+#   Identifier of the section to include. It cannot contain spaces. For
+#   a section named “foo”, a file “foo/foo.rst” must exist.
+#
+# Rest of the line:
+#   Free form text for specifying who is in charge. It will be passed to
+#   docutils as-is, so you can add markup if needed.
+#
+#
+introducion      Xavier Castaño (xcastanho@igalia.com)
+criterios        Xavier Castaño (xcastanho@igalia.com)
+calendarios      Xavier Castaño (xcastanho@igalia.com)
+avances          Xavier Castaño (xcastanho@igalia.com)
+recursos         Xavier Castaño (xcastanho@igalia.com)
+pedidos          Xavier Castaño (xcastanho@igalia.com)
+planificacion    Xavier Castaño (xcastanho@igalia.com)
+asignacion       Xavier Castaño (xcastanho@igalia.com)
+partes           Xavier Castaño (xcastanho@igalia.com)
+etiquetas        Xavier Castaño (xcastanho@igalia.com)

doc/src/pedidos/pedidos.rst

@@ -0,0 +1,7 @@
+Pedidos e elementos de pedidos
+##############################
+
+.. contents::
+
+Contidos...
+

doc/src/planificacion/planificacion.rst

@@ -0,0 +1,7 @@
+Planificación de tarefas
+########################
+
+.. contents::
+
+Contidos...
+

doc/src/recursos/recursos.rst

@@ -0,0 +1,7 @@
+Xestión de recursos
+###################
+
+.. contents::
+
+Contidos...
+

doc/tools/doctool

@@ -0,0 +1,273 @@
+#! /usr/bin/env python
+
+import sys, shlex, subprocess
+from optparse import OptionParser, OptionGroup
+from docutils.writers import latex2e
+
+try:
+    import locale
+    locale.setlocale(locale.LC_ALL, '')
+except:
+    pass
+
+
+class AttributedDict(object):
+    def __init__(self):
+        object.__setattr__(self, "_items", dict())
+
+    def __getattr__(self, key):
+        return self._items.get(key)
+
+    def __delattr__(self, key):
+        if key in self._items:
+            del self._items[key]
+        else:
+            object.__delattr__(self, key)
+
+    def __setattr__(self, key, val):
+        if hasattr(self, key):
+            object.__setattr__(self, key, val)
+        else:
+            self._items[key] = val
+
+
+parser = OptionParser(usage="Usage: %prog <command> [options]")
+OPT = AttributedDict()
+
+OPT.common = OptionGroup(parser, "Common options")
+
+OPT.docinfo = OptionGroup(parser, "Documentation information")
+OPT.docinfo.add_option("-i", "--info", dest="docinfo",
+        default=None, metavar="FILE",
+        help="Read project information from FILE")
+
+
+def optparser(*groups):
+    parser.add_option_group(OPT.common)
+    [parser.add_option_group(g) for g in groups]
+    return parser
+
+
+class DupRefsRemover(object):
+    def __init__(self, out):
+        self.out = out
+        self.ref = dict()
+
+    def handle_line(self, line):
+        if line.startswith(".. _") and ":" in line:
+            r = map(lambda x: x.strip(), line[4:].split(":", 1))
+            if r[0] in self.ref:
+                # Do some sanity check
+                if self.ref[r[0]] != r[1]:
+                    raise ValueError("Reference '%s' mismatch (%s - %s)"
+                            % (r[0], self.ref[r[0]], r[1]))
+            else:
+                # Add reference and print it out
+                self.ref[r[0]] = r[1]
+                self.out.write(line)
+        else:
+            self.out.write(line)
+
+
+
+class ShellEscapeRunner(object):
+    def __init__(self, out):
+        self.out = out
+
+    def _expand(self, cmdline):
+        cmd = shlex.split(cmdline, False)
+        pipe = subprocess.Popen(cmd, stdout=subprocess.PIPE)
+        return "\n  ".join(pipe.communicate()[0].rstrip().splitlines())
+
+
+    def handle_line(self, line):
+        index = line.find("!!")
+        if index < 0:
+            self.out.write(line)
+            return
+
+        self.out.write(line[:index].replace("\\!", "!"))
+        cmd = line[index+2:]
+        end = cmd.find("!!")
+        if end > index:
+            self.out.write(self._expand(cmd[:end].replace("\\!", "!")))
+            self.out.write(cmd[end+2:].replace("\\!", "!"))
+        else:
+            self.out.write(self._expand(cmd.replace("\\!", "!")))
+            self.out.write("\n")
+
+
+
+LATEX_SETTINGS = {
+    "documentclass"      : "scrbook",
+    "documentoptions"    : "11pt,oneside,a4paper",
+    "table_style"        : "booktabs",
+    "use_latex_footnotes": 1,
+    "use_latex_citations": 1,
+    "use_latex_toc"      : 1,
+    "use_latex_docinfo"  : 0,
+    "use_latex_abstract" : 1,
+}
+
+EBOOK_SETTINGS = dict(LATEX_SETTINGS)
+EBOOK_SETTINGS["documentoptions"] = "14pt,oneside,b5paper"
+
+HTML_SETTINGS = {
+    "field_name_limit"     : 20,
+    "cloak_email_addresses": 1,
+}
+
+
+# Those are two mocks needed to properly reuse the LaTeX code generator, but
+# avoiding generation of all the cruft from the preamble and the postamble,
+# and only the middle part.
+#
+class LaTeXStandaloneTranslator(latex2e.LaTeXTranslator):
+    def __init__(self, document):
+        latex2e.LaTeXTranslator.__init__(self, document)
+
+        # XXX We rely on DocumentClass having a document_class attribute and
+        #     on it not changing the attribute once initialization was done
+        #
+        if self.d_class.document_class == "igaliabk":
+            self.d_class.document_class = "book"
+
+class LaTeXInsertTranslator(LaTeXStandaloneTranslator):
+    def astext(self):
+        return "".join(self.body)
+
+class LaTeXCustomWriter(latex2e.Writer):
+    def __init__(self, translator_class):
+        latex2e.Writer.__init__(self)
+        self.translator_class = translator_class
+
+
+
+class DocTool(object):
+
+    def main(self, argv=None):
+        if argv is None:
+            argv = sys.argv
+
+        if len(argv) < 2:
+            raise SystemExit("Insufficient number of arguments")
+
+        method = getattr(self, "cmd_" + argv[1], self.no_command)
+        method(*argv[1:])
+
+    def cmd_rstinsert(self, cmd, *args):
+        from docutils.core import publish_cmdline, default_description
+        description = (
+            "Generates LaTeX portions to be included in documents " +
+            "from standalone reStructuredText sourtces " +
+            default_description)
+
+        publish_cmdline(writer=LaTeXCustomWriter(LaTeXInsertTranslator),
+                description=description,
+                argv=list(args)
+                )
+
+    def cmd_rst2latex(self, cmd, *args):
+        from docutils.core import publish_cmdline, default_description
+        description = (
+            'Generates LaTeX documents from RST sources. ' +
+            default_description)
+
+        publish_cmdline(writer=LaTeXCustomWriter(LaTeXStandaloneTranslator),
+                settings_overrides=LATEX_SETTINGS,
+                description=description,
+                argv=list(args),
+                )
+
+    def cmd_rst2ebook(self, cmd, *args):
+        from docutils.core import publish_cmdline, default_description
+        description = (
+            'Generates LaTeX documents from RST sources. ' +
+            default_description)
+
+        publish_cmdline(writer=LaTeXCustomWriter(LaTeXStandaloneTranslator),
+                settings_overrides=EBOOK_SETTINGS,
+                description=description,
+                argv=list(args),
+                )
+
+    def cmd_rst2html(self, cmd, *args):
+        from docutils.core import publish_cmdline, default_description
+        description = (
+            'Generates HTML documents from RST sources. ' +
+            default_description)
+
+        publish_cmdline(writer_name="html",
+                settings_overrides=HTML_SETTINGS,
+                description=description,
+                argv=list(args),
+                )
+
+    def cmd_toplevel(self, cmd, *args):
+        opts, args = optparser(OPT.docinfo).parse_args(list(args))
+
+        if opts.docinfo:
+            f = file(opts.docinfo, "rU")
+            e = ShellEscapeRunner(sys.stdout)
+            map(e.handle_line, f.readlines())
+            f.close()
+            print
+
+        print ".. contents::"
+        print
+
+        out = DupRefsRemover(sys.stdout)
+
+        for name in args:
+            if not name.endswith(".rst"):
+                continue
+
+            f = file(name, "rU")
+            map(out.handle_line,
+                    filter(lambda l: ".. contents::" not in l,
+                        f.readlines())
+                    )
+            f.close()
+            print
+
+
+    def cmd_htmlindex(self, cmd, *args):
+        opts, args = optparser(OPT.docinfo).parse_args(list(args))
+
+        if opts.docinfo:
+            f = file(opts.docinfo, "rU")
+            e = ShellEscapeRunner(sys.stdout)
+            map(e.handle_line, f.readlines())
+            f.close()
+            print
+
+        for name in args:
+            # Skip non-RST inputs
+            if not name.endswith(".rst"):
+                continue
+
+            f = file(name, "rU")
+            line = f.readline().strip()
+            f.close()
+            print "#. `%s <%s.html>`__" % (line, name[:-4])
+
+
+    def cmd_help(self, cmd, *args):
+        if args:
+            self.main([args[0], args[0], "--help"])
+        else:
+            print "Available commands:"
+            for k in dir(self):
+                if k.startswith("cmd_"):
+                    print " ", k[4:].replace("_", "-")
+
+    cmd_commands = cmd_help
+
+    def no_command(self, cmd, *args):
+        raise SystemExit("No such command '%s'" % cmd)
+
+
+
+if __name__ == "__main__":
+    DocTool().main()
+

doc/tools/toplevel-html

@@ -0,0 +1,61 @@
+#! /bin/bash
+
+header='
+===================
+ Service Catalogue
+===================
+'
+
+longest ()
+{
+	local -i len=0
+	local item
+	for item in "$@" ; do
+		[[ ${#item} -gt ${len} ]] && len=${#item}
+	done
+	echo "${len}"
+}
+
+
+sects=( )
+texts=( )
+title=( )
+
+echo "${header}"
+while read -r item ; do
+	if [[ ${item} = \#* ]] ; then
+		continue
+	elif expr "${item}" : '^[[:space:]]*$' &> /dev/null ; then
+		continue
+	else
+		# Gather data
+		read -r sect text <<< "${item}"
+		title=( "${title[@]}" "$(head -n 1 "${sect}/${sect}.rst")" )
+		sects=( "${sects[@]}" "${sect}" )
+		texts=( "${texts[@]}" "${text}" )
+	fi
+done
+
+repeat_char ()
+{
+	local i
+	for (( i=0; i < $2 ; i++ )) ; do
+		echo -n "$1"
+	done
+}
+
+title_longest=$(longest "${title[@]}")
+sects_longest=$(longest "${sects[@]}")
+title_longest=$((title_longest + 2 * sects_longest + 12))
+title_sub=$(repeat_char '=' ${title_longest})
+
+printf "%-${title_longest}s ================\n" "${title_sub}"
+printf "%-${title_longest}s Person in charge\n" "Section"
+printf "%-${title_longest}s ================\n" "${title_sub}"
+for (( i=0 ; i < ${#title[@]} ; i++ )) ; do
+	printf "%-${title_longest}s %s\n" \
+		"\`${title[$i]} <${sects[$i]}/${sects[$i]}.html>\`_" \
+		"${texts[$i]}"
+done
+printf "%-${title_longest}s ================\n" "${title_sub}"
+

doc/tools/toplevel-tex

@@ -0,0 +1,81 @@
+#! /bin/bash
+
+header='
+===================
+ Service Catalogue
+===================
+'
+
+mangle_sed='
+/^\\.\\.[ \\t]contents::/d
+s,\\(image::[[:space:]]*\\)\\(.*\\),\\1%s/\\2,
+s,\\(figure::[[:space:]]*\\)\\(.*\\),\\1%s/\\2,
+'
+
+# mangle_input [basedir]
+#
+mangle_input ()
+{
+	local program
+	printf -v program "${mangle_sed}" "$1" "$1"
+	sed -e "${program}"
+}
+
+
+longest ()
+{
+	local -i len=0
+	local item
+	for item in "$@" ; do
+		[[ ${#item} -gt ${len} ]] && len=${#item}
+	done
+	echo "${len}"
+}
+
+
+sects=( )
+texts=( )
+title=( )
+
+echo "${header}"
+while read -r item ; do
+	if [[ ${item} = \#* ]] ; then
+		continue
+	elif expr "${item}" : '^[[:space:]]*$' &> /dev/null ; then
+		continue
+	else
+		# Gather data
+		read -r sect text <<< "${item}"
+		title=( "${title[@]}" "$(head -n 1 "${sect}/${sect}.rst")" )
+		sects=( "${sects[@]}" "${sect}" )
+		texts=( "${texts[@]}" "${text}" )
+	fi
+done
+
+repeat_char ()
+{
+	local i
+	for (( i=0; i < $2 ; i++ )) ; do
+		echo -n "$1"
+	done
+}
+
+title_longest=$(longest "${title[@]}")
+title_longest=$((title_longest + 3))
+title_sub=$(repeat_char '=' ${title_longest})
+
+printf "%-${title_longest}s ================\n" "${title_sub}"
+printf "%-${title_longest}s Person in charge\n" "Section"
+printf "%-${title_longest}s ================\n" "${title_sub}"
+for (( i=0 ; i < ${#title[@]} ; i++ )) ; do
+	printf "%-${title_longest}s %s\n" "\`${title[$i]}\`_" "${texts[$i]}"
+done
+printf "%-${title_longest}s ================\n" "${title_sub}"
+
+printf "\n.. contents::\n\n"
+
+for sect in "${sects[@]}" ; do
+		mangle_input "$(dirname "${sect}/${sect}.rst")" < "${sect}/${sect}.rst"
+		echo
+done
+