[cpl-plugin-amber] 02/07: Bugfixes; add HTML documentation

Ole Streicher olebole-guest at alioth.debian.org
Sat Oct 26 12:36:12 UTC 2013


This is an automated email from the git hooks/post-receive script.

olebole-guest pushed a commit to branch debian-template
in repository cpl-plugin-amber.

commit e6b1316fd38c7172d63626f32410a2cb136022ed
Author: Ole Streicher <debian at liska.ath.cx>
Date:   Fri Oct 25 17:20:26 2013 +0200

    Bugfixes; add HTML documentation
---
 debian/control            |    3 +-
 debian/cpl-plugin.docs.in |    1 +
 debian/create_manpage.py  |   70 +++++++++++-------
 debian/create_sphinx.py   |  181 +++++++++++++++++++++++++++++++++++++++++++++
 debian/rules              |   28 ++++---
 5 files changed, 244 insertions(+), 39 deletions(-)

diff --git a/debian/control b/debian/control
index ec0c09f..cef699d 100644
--- a/debian/control
+++ b/debian/control
@@ -3,7 +3,8 @@ Section: science
 Priority: optional
 Maintainer: Debian Science Maintainers <debian-science-maintainers at lists.alioth.debian.org>
 Uploaders: Ole Streicher <debian at liska.ath.cx>
-Build-Depends: debhelper (>= 9), dh-autoreconf, libcpl-dev (>= 5.3.1), python, python-cpl
+Build-Depends: debhelper (>= 9), dh-autoreconf, libcpl-dev (>= 5.3.1), python,
+python-cpl, sphinx
 Standards-Version: 3.9.4
 Homepage: http://www.eso.org/sci/software/pipelines/template
 Vcs-Git: git://git.debian.org/git/debian-science/packages/cpl-plugin-template.git
diff --git a/debian/cpl-plugin.docs.in b/debian/cpl-plugin.docs.in
new file mode 100644
index 0000000..c43af54
--- /dev/null
+++ b/debian/cpl-plugin.docs.in
@@ -0,0 +1 @@
+sphinx/html
diff --git a/debian/create_manpage.py b/debian/create_manpage.py
index a885071..81ccd12 100644
--- a/debian/create_manpage.py
+++ b/debian/create_manpage.py
@@ -3,10 +3,11 @@
 import cpl
 import os
 import sys
+import re
 
 man_template = '''.TH {NAME} "{section}" "{version}" "{name}" "{pipeline} recipes"
 .SH NAME
-{name} \\- {synopsis}
+{name} - {synopsis}
 
 .SH SYNOPSIS
 esorex
@@ -24,27 +25,45 @@ options, along with suitable default values. Please refer to the details
 provided by the 'esorex --help' command.
 
 .SH SEE ALSO
+The full documentation for the {pipeline} pipeline can be downloaded as 
+a PDF file using the following URL:
+.IP
+.B ftp://ftp.eso.org/pub/dfs/pipelines/{pipeline}/{pipeline}-pipeline-manual-{version}.pdf
+.PP
+An overview over the existing ESO pipelines can be found on the web page
+\\fBhttp://www.eso.org/sci/software/pipelines/\\fR.
+.PP
+Basic documentation about the EsoRex program can be found at the esorex (1) 
+man page.
+.PP
+It is possible to call the pipelines from python using the python-cpl package.
+See \\fBhttp://packages.python.org/python-cpl/index.html\\fR for further
+information.
+.PP
+The other recipes of the {pipeline} pipeline are
 {seealso}
 
 .SH VERSION
 {name} {version}
 
-.SH BUGS
-Please report any problems to {email}.
-
 .SH AUTHOR
-{author}
+{author} <{email}>
+
+.SH BUG REPORTS
+Please report any problems to {email}. Alternatively, you may send a report to the ESO User Support Department <usd-help at eso.org>.
 
 .SH LICENSE
 {license}
 '''
 
-opt_template = '''.TP
-\\fB\\-\\-{name}\\fR \\fI<{type}>\\fR
+par_template = '''.TP
+\\fB--{name}\\fR \\fI<{type}>\\fR
 {description}. The full name of this option for the EsoRex configuration
 file is \\fB{fullname}\\fR [default={default}].
 '''
 
+seealso_template = ".IR {name} ({section})"
+
 fname_template ="{name}.{section}"
 
 section = 7
@@ -53,45 +72,42 @@ pipeline = sys.argv[1]
 cpl.Recipe.path = "recipes"
 recipes = cpl.Recipe.list()
 
-def options(recipe):
-    opt = ""
-    for p in recipe.param:
-        opt += opt_template.format(name = p.name,
+def param(recipe, template):
+    return "".join(template.format(name = p.name,
                                    fullname = p.fullname,
                                    type = p.type.__name__,
                                    description = p.__doc__,
                                    default = p.default)
-    return opt
-
-def seealso(recipe):
-    s = "esorex (1)"
-    for name,v in recipes:
-        if (name != recipe.__name__):
-            s += ", {name} ({section})".format(name = name,
-                                               section=section)
-    return s
-
+                   for p in recipe.param)
+
+def seealso(recipe, template):
+    return ",\n".join(template.format(name = name,
+                                      section=section)
+                      for name,v in recipes 
+                      if (name != recipe.__name__))
+    
 def manpage(recipe):
-    description = recipe.description[1] \
-      .replace("\n", "\n.br\n") \
-      .replace("-", "\\-")
+    description = recipe.description[1] 
+    description = re.sub("-"*40+"+", "", description) \
+                    .replace(".\n", ".\n.PP\n")
+    description = re.sub("\n([A-Z][A-Z 0-9]+):?\n----+", "\n.SS \\1", description)
     return man_template.format(name = recipe.__name__,
                                NAME = recipe.__name__.upper(),
                                section = section,
                                version = recipe.__version__,
                                synopsis = recipe.description[0],
                                description = description,
-                               seealso = seealso(recipe),
+                               seealso = seealso(recipe, seealso_template),
                                email = recipe.__email__,
                                author = recipe.__author__,
                                license = recipe.__copyright__,
                                pipeline = pipeline,
-                               options = options(recipe))
+                               options = param(recipe, par_template))
 
 for name, version in recipes:
     recipe = cpl.Recipe(name)
     f = open(os.path.join("man",
                           fname_template.format(name = name,
                                                 section=section)), "w")
-    f.write(manpage(recipe))
+    f.write(manpage(recipe).replace('-', '\\-'))
     f.close()
diff --git a/debian/create_sphinx.py b/debian/create_sphinx.py
new file mode 100644
index 0000000..df17013
--- /dev/null
+++ b/debian/create_sphinx.py
@@ -0,0 +1,181 @@
+#!/usr/bin/env python
+
+import cpl
+import os
+import sys
+
+rst_template = '''{recipe}
+====================================================
+
+.. data:: {recipe}
+
+{synopsis}
+
+{description}
+
+Current version is {recipe}-{version}.
+
+Constructor
+-----------
+
+.. method:: cpl.Recipe("{recipe}")
+   :noindex:
+
+   Create an object for the recipe {recipe}.
+
+::
+
+   import cpl
+   {recipe} = cpl.Recipe("{recipe}")
+
+Parameters
+----------
+
+{pars}
+
+The following code snippet shows the default settings for the available 
+parameters.
+
+::
+
+   import cpl
+   {recipe} = cpl.Recipe("{recipe}")
+
+{pars_example1}
+
+You may also set or overwrite some or all parameters by the recipe 
+parameter `param`, as shown in the following example:
+
+::
+
+   import cpl
+   {recipe} = cpl.Recipe("{recipe}")
+   [...]
+   res = {recipe}( ..., param = {{{pars_example2}}})
+
+.. seealso:: `cpl.Recipe <http://packages.python.org/python-cpl/recipe.html>`_
+   for more information about the recipe object.
+
+Bug reports
+-----------
+
+Please report any problems to {email}. Alternatively, you may send a 
+report to the ESO User Support Department <usd-help at eso.org>.
+
+Copyright
+---------
+
+{license}
+
+.. codeauthor:: {author} <{email}>
+'''
+
+par_template = '''.. py:attribute:: {recipe}.param.{par}
+
+    {description} [default={default}].
+'''
+
+fname_template ="{recipe}.rst"
+
+index_template = '''.. title:: The {pipeline} pipeline
+
+The {PIPELINE} pipeline
+#######################
+
+These pages describe the python interface for the {PIPELINE} pipeline recipes.
+
+{recipes}
+
+.. toctree::
+   :hidden:
+
+{toctree}
+
+.. seealso::
+
+     * The `{PIPELINE} Pipeline User Manual 
+       <ftp://ftp.eso.org/pub/dfs/pipelines/{pipeline}/{pipeline}-pipeline-manual-1.2.3.pdf>`_ in PDF format,
+
+     * an `overview <http://www.eso.org/sci/software/pipelines/>`_
+       over the existing ESO pipelines,
+
+     * the `python-cpl <http://packages.python.org/python-cpl>`_ package.
+    
+Bug reports
+===========
+
+If you experience an unexpected behavior of any component of the {PIPELINE}
+pipeline recipes package, please, first verify that you are using one of the
+above mentioned supported platforms and refer to the list of known problems
+and limitations in the pipeline manual of the current {PIPELINE} pipeline release.
+
+For any other issues or requests, please, send a report to the `ESO User
+Support Department <usd-help at eso.org>`_, describing:
+
+ * the {PIPELINE} pipeline version,
+ * the version of your OS and C compiler,
+ * the exact sequence of actions that were performed before the problem occurred,
+ * what were precisely the symptoms and the possible error message(s),
+ * whether the problem is repeatable.
+'''
+
+conf_template = '''project = u'{PIPELINE} pipeline'
+show_authors = True
+'''
+
+pipeline = sys.argv[1]
+
+cpl.Recipe.path = "recipes"
+recipes = [ cpl.Recipe(name) for name, version in cpl.Recipe.list() ]
+
+def par(recipe, template, delimiter = "", count = None):
+    return delimiter.join(template.format(
+        recipe = recipe.__name__,
+        par = p.name.replace("-","_"),
+        type = p.type.__name__,
+        description = p.__doc__,
+        default = '"{0}"'.format(p.default) if p.type is str else p.default
+    ) for i, p in enumerate(recipe.param) if count is None or i < count)
+
+def rstpage(recipe, template):
+    return template.format(
+        recipe = recipe.__name__,
+        version = recipe.__version__,
+        synopsis = recipe.description[0],
+        description = recipe.description[1].replace('.\n', '.\n\n'),
+        email = recipe.__email__,
+        author = recipe.__author__,
+        license = recipe.__copyright__,
+        pipeline = pipeline,
+        pars = par(recipe, par_template),
+        pars_example1 = par(recipe, '   {recipe}.param.{par} = {default}\n'),
+        pars_example2 = par(recipe, '"{par}":{default}', ', ', 2)
+    )
+
+
+for recipe in recipes:
+    f = open(os.path.join("sphinx",
+                          fname_template.format(recipe = recipe.__name__)), "w")
+    f.write(rstpage(recipe, rst_template))
+    f.close()
+
+toc = "\n".join("   {recipe}".format(
+    recipe = recipe.__name__
+) for recipe in recipes)
+
+toc_recipes = "\n\n".join(":obj:`{recipe}`\n   {synopsis}".format(
+    recipe = recipe.__name__,
+    synopsis = recipe.description[0]
+) for recipe in recipes)
+
+f = open(os.path.join("sphinx", "contents.rst"), "w")
+f.write(index_template.format(toctree = toc,
+                              recipes = toc_recipes,
+                              pipeline = pipeline,
+                              PIPELINE = pipeline.upper()))
+f.close()
+
+f = open(os.path.join("sphinx", "conf.py"), "w")
+f.write(conf_template.format(PIPELINE = pipeline.upper()))
+f.close()
+
diff --git a/debian/rules b/debian/rules
index b02bf80..b9b2279 100755
--- a/debian/rules
+++ b/debian/rules
@@ -11,14 +11,14 @@ get-orig-source:
 	sh ./debian/repackage.sh
 
 %:
-	dh  $@ --with autoreconf
+	dh  $@ --with autoreconf,sphinxdoc
 
 debian_files:
 	if [ -d calib/cal ] ; then \
-	    dfiles=".install .manpages -calib.install" ; \
+	    dfiles=".install .manpages .docs -calib.install" ; \
 	else \
 	    cp -f debian/README.Debian.in debian/README.Debian ; \
-	    dfiles=".install .manpages -calib.postinst -calib.prerm -calib.lintian-overrides" ; \
+	    dfiles=".install .manpages .docs -calib.postinst -calib.prerm -calib.lintian-overrides" ; \
 	fi ; \
 	for f in $$dfiles ; do \
 	    sed "s/__VERSION__/$(VERSION)/g;s/__PIPELINE__/${PIPELINE}/g" \
@@ -34,16 +34,22 @@ override_dh_installman:
 	python debian/create_manpage.py ${PIPELINE}
 	dh_installman
 
+override_dh_installdocs:
+	mkdir -p sphinx
+	python debian/create_sphinx.py ${PIPELINE}
+	sphinx-build sphinx sphinx/html
+	dh_installdocs
+
 override_dh_clean:
 	dh_clean
-	rm -f debian/${DEBPKGNAME}.install \
-              debian/${DEBPKGNAME}.manpages \
-	      debian/${DEBPKGNAME}-calib.lintian-overrides \
-	      debian/${DEBPKGNAME}-calib.install \
-	      debian/${DEBPKGNAME}-calib.postinst \
-              debian/${DEBPKGNAME}-calib.prerm \
-              debian/README.Debian \
-	      man
+	rm -rf debian/${DEBPKGNAME}.install \
+               debian/${DEBPKGNAME}.manpages \
+	       debian/${DEBPKGNAME}-calib.lintian-overrides \
+	       debian/${DEBPKGNAME}-calib.install \
+	       debian/${DEBPKGNAME}-calib.postinst \
+               debian/${DEBPKGNAME}-calib.prerm \
+               debian/README.Debian \
+	       man sphinx
 
 override_dh_auto_configure:
 	dh_auto_configure -- --prefix=/usr/

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-science/packages/cpl-plugin-amber.git



More information about the debian-science-commits mailing list