-
Dave Kuhlman authoreddfe21aaf
<?xml version="1.0" encoding="utf-8" ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8" /><meta name="generator" content="Docutils 0.14: http://docutils.sourceforge.net/" /><title>How to package a generateDS.py generated library</title><meta name="author" content="Dave Kuhlman" /><style type="text/css">/* css */body { font: 90% 'Lucida Grande', Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif; background: #ffffff; color: black; margin: 2em; padding: 2em;}a[href] { color: #436976; background-color: transparent;}a.toc-backref { text-decoration: none;}h1 a[href] { text-decoration: none; color: #fcb100; 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 { text-decoration: underline;}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;}h1, h2, h3, h4, h5, h6 { color: #003a6b; background-color: transparent;7172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140
font: 100% 'Lucida Grande', Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
margin: 0;
padding-top: 0.5em;
}
h1 {
font-size: 160%;
margin-bottom: 0.5em;
border-bottom: 1px solid #fcb100;
}
h2 {
font-size: 140%;
margin-bottom: 0.5em;
border-bottom: 1px solid #aaa;
}
h3 {
font-size: 130%;
margin-bottom: 0.5em;
text-decoration: underline;
}
h4 {
font-size: 110%;
font-weight: bold;
}
h5 {
font-size: 100%;
font-weight: bold;
}
h6 {
font-size: 80%;
font-weight: bold;
}
ul a, ol a {
text-decoration: underline;
}
dt {
font-weight: bold;
}
dt a {
text-decoration: none;
}
dd {
line-height: 1.5em;
margin-bottom: 1em;
}
legend {
background: #ffffff;
padding: 0.5em;
}
form {
margin: 0;
}
dl.form {
margin: 0;
padding: 1em;
}
dl.form dt {
width: 30%;
float: left;
margin: 0;
padding: 0 0.5em 0.5em 0;
text-align: right;
141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210
}
input {
font: 100% 'Lucida Grande', Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
color: black;
background-color: white;
vertical-align: middle;
}
abbr, acronym, .explain {
color: black;
background-color: transparent;
}
q, blockquote {
}
code, pre {
font-family: monospace;
font-size: 1.2em;
display: block;
padding: 10px;
border: 1px solid #838183;
background-color: #eee;
color: #000;
overflow: auto;
margin: 0.5em 1em;
}
div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
margin: 2em ;
border: medium outset ;
padding: 1em }
div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
font-weight: bold ;
font-family: sans-serif }
div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
color: red ;
font-weight: bold ;
font-family: sans-serif }
tt.docutils {
background-color: #dddddd;
}
ul.auto-toc {
list-style-type: none }
</style>
</head>
<body>
<div class="document" id="how-to-package-a-generateds-py-generated-library">
<h1 class="title">How to package a generateDS.py generated library</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>Dave Kuhlman</td></tr>
<tr><th class="docinfo-name">Address:</th>
<td><pre class="address">
dkuhlman (at) davekuhlman (dot) org
<a class="last reference external" href="http://www.davekuhlman.org">http://www.davekuhlman.org</a>
211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280
</pre>
</td></tr>
</tbody>
</table>
<!-- version -->
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">revision:</th><td class="field-body">2.29.25</td>
</tr>
</tbody>
</table>
<!-- version -->
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">date:</th><td class="field-body">October 05, 2018</td>
</tr>
</tbody>
</table>
<div class="section" id="introduction">
<h1>Introduction</h1>
<p>This document explains how to use the generateDS.py library
template to create a package enabling you to distribute a module
generated with generateDS.py. This package and the instructions
below will help you to create the following:</p>
<ul class="simple">
<li>A directory structure in which to hang things.</li>
<li>A directory for sample scripts (sample_code/)</li>
<li>A directory for sample XML instance documents</li>
<li>A directory for schemas</li>
<li>A (mostly empty file in which to place utility functions to help
with the use of your generated module</li>
<li>A script (quick_start.py) that does a bit of name replacement</li>
<li>A directory for documentation containing some boiler plate
material and also a set-up for generating document in various
formats (for example HTML, LaTeX, PDF) with Sphinx</li>
</ul>
<p>The latest copy of these instructions is here:</p>
<blockquote>
<a class="reference external" href="http://www.davekuhlman.org/librarytemplate_howto.html">http://www.davekuhlman.org/librarytemplate_howto.html</a></blockquote>
<p>and the template package itself is here:</p>
<blockquote>
<a class="reference external" href="http://www.davekuhlman.org/librarytemplate-1.0a.zip">http://www.davekuhlman.org/librarytemplate-1.0a.zip</a></blockquote>
<p>These instructions assume the name "peach" as the name of the
schema. You should replace "peach" in these instructions with the
name of your schema.</p>
<p>Find out more about generateDS.py here:
<a class="reference external" href="http://www.davekuhlman.org/generateDS.html">http://www.davekuhlman.org/generateDS.html</a></p>
<p>You will need to install Sphinx in order to build the documentation
in your package. Learn about Sphinx here: <a class="reference external" href="http://sphinx.pocoo.org/">http://sphinx.pocoo.org/</a>.</p>
</div>
<div class="section" id="details">
<h1>Details</h1>
<p>In the instructions that follow, I'll assume that the name of your
XML schema is "peach" and that the name of the module that you
generate using <tt class="docutils literal">generateDS.py</tt> will be "peachlib".</p>
<p>Follow these steps:</p>
<ol class="arabic">
<li><p class="first">Unroll the library template (librarytemplate-x.y.zip), for
example:</p>
<pre class="literal-block">
$ unzip librarytemplate-1.0a.zip
</pre>
</li>
<li><p class="first">Rename the top-level directory created by the previous step, for
example:</p>
<blockquote>
281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350
<p>$ mv librarytemplate-x.y peachlib-1.0a</p>
</blockquote>
<p>Or, on MS Windows:</p>
<blockquote>
<p>$ rename librarytemplate-x.y peachlib-1.0a</p>
</blockquote>
</li>
<li><p class="first">Go to the new directory. For example:</p>
<pre class="literal-block">
$ cd peachlib-1.0a
</pre>
</li>
<li><p class="first">Copy your generated modules into this directory. Suggested name
is <tt class="docutils literal">{schema_name}lib.py</tt>. For example <tt class="docutils literal">peachlib.py</tt>.</p>
</li>
<li><p class="first">Run <tt class="docutils literal">quick_start.py</tt> (which is in the top level directory).
<tt class="docutils literal">quick_start.py</tt> makes changes in the boiler plate provided by
librarytemplate; it changes occurrences of "{{schema_name}}" to
the name of your schema, which is entered on the command line.
For example:</p>
<pre class="literal-block">
$ python quick_start.py --help
$ python quick_start.py --schema-name=peach
</pre>
</li>
<li><p class="first">Add some more content to the documentation. It is likely that
you will want to make additions and changes in the following
files:</p>
<ul class="simple">
<li>README.txt</li>
<li>docs/intro.txt</li>
<li>sample_code/README.txt</li>
</ul>
</li>
<li><p class="first">Generate the documentation. This step requires Sphinx.</p>
<p>First, add the top-level directory of your distribution to your
PYTHONPATH environment variable. Sphinx needs to be able to
import your library module (peachlib.py). Then, go to
the ./docs/ directory and build the HTML documentation:</p>
<pre class="literal-block">
$ cd docs
$ make clean
$ make html
</pre>
<p>You also can build other forms of documentation, e.g. LaTeX and
PDF. See the Sphinx documentation, or type:</p>
<pre class="literal-block">
$ make help
</pre>
<p>By default, the generated documentation for the module includes
lists of the member functions for each class. You can change
this by removing the <tt class="docutils literal">:members:</tt> and <tt class="docutils literal"><span class="pre">:undoc-members:</span></tt>
options from the file <tt class="docutils literal">docs/module_contents.txt</tt>, and then
run:</p>
<pre class="literal-block">
$ make clean
$ make html
</pre>
<p>again.</p>
</li>
<li><p class="first">Add some functionality and sample code. In particular:</p>
<ul class="simple">
<li>Add some helper functions in peachlibutils.py.</li>
<li>Add example applications in directory sample_code/.
Suggestions: (1) Rename and add code to
sample_code/example01.txt. (2) Generate a subclass module
(using the "-s" command line option with <tt class="docutils literal">generateDS.py</tt>,
then add a bit of code to a few of the subclasses.</li>
<li>List and describe any example applications that you add in the
file sample_code/README.txt.</li>
351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389
</ul>
</li>
<li><p class="first">It might be a good idea to include the XML schema from which you
generated your library module. You can copy the schema(s) to
the schemas/ directory, and/or add a link in file
schemas/README.txt that points to a location where it can be
found.</p>
</li>
<li><p class="first">Create a distribution file. For example, use either:</p>
<pre class="literal-block">
$ tar czf peachlib-1.0a.tar.gz peachlib-1.0a
</pre>
<p>or:</p>
<pre class="literal-block">
$ zip -r peachlib-1.0a.zip peachlib-1.0a
</pre>
<p>In order to avoid including backup files and compiled Python
modules, you might want to use something like the following:</p>
<pre class="literal-block">
$ zip -r peachlib-1.0a.zip peachlib-1.0a -x \*~ -x \*.pyc
</pre>
<p>See the man page on zip for more on the -x command line option.
The backslash avoids the shell filename substitution. Adjust
this command for your needs. For example, you may need to use
"*.bak" instead of "*~".</p>
</li>
</ol>
</div>
</div>
<div class="footer">
<hr class="footer" />
<a class="reference external" href="librarytemplate_howto.txt">View document source</a>.
Generated on: 2018-10-05 19:59 UTC.
Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
</div>
</body>
</html>