[Debian-astro-commits] [cpl-plugin-template] 25/76: Bugfixes; add HTML documentation
Ole Streicher
olebole at moszumanska.debian.org
Wed Sep 23 09:59:48 UTC 2015
This is an automated email from the git hooks/post-receive script.
olebole pushed a commit to branch debian
in repository cpl-plugin-template.
commit d42245ae236644069df34bf33abfaf1853aadce9
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 9a2b5fa..800a84c 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/giraffe/giraf-pipe-recipes.html
Vcs-Git: git://anonscm.debian.org/debian-science/packages/cpl-plugin-giraf.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-astro/packages/cpl-plugin-template.git
More information about the Debian-astro-commits
mailing list