librarytemplate_howto.html 11.08 KiB
<?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 &quot;peach&quot; as the name of the schema. You should replace &quot;peach&quot; 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 &quot;peach&quot; and that the name of the module that you generate using <tt class="docutils literal">generateDS.py</tt> will be &quot;peachlib&quot;.</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 &quot;{{schema_name}}&quot; 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 &quot;-s&quot; 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 &quot;*.bak&quot; instead of &quot;*~&quot;.</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>