mkpythonproj Developer's Guide

Table of Contents

• Architecture
  • Directories
  • Templates
  • Outputs
    • Full project dir tree
    • Simple script
    • Setup
    • Documents
• Implementation Issues

Architecture

Directories

The untarred package has:

  mkpythonproj/
    AUTHORS
    COPYING
    MANIFEST
    README
    mkpythonproj.py      the main script
    mkpythonproj/        the supporting module
      __init__.py
      styles.py          pdx styles for the documentation
      templates.py       code chunks
      licenses/
        README           how to add more licenses
        GPL.py
        LGPL.py
    setup.py             distutils-based
    doc/
      go
      index.{pdx,html}
      deshist.{pdx,html} design history
      devguide.{pdx,html} developers' guide
      manual.{pdx,html}  manual (empty for now)

During installation, the mkpythonproj package goes to site-packages (or wherever setup.py options say to go). The mkpythonproj.py is copied to a bin dir on the PATH.

Templates

The outputs are generated from triple-quoted blocks of text. Small blocks are left on the main script, others are in templates.py or in the various license modules. Thus we are using python to generate python. This is generally ok. However, in the generation of "setup.py", there are problems when the generated code has quote blocks of its own. In those cases, we cannot use %s or %(name)s formatting, and must just concatenate our text pieces.

The package ships with GPL and LGPL, with LGPL as the default. Others can be added as needed. In each case, the license file has two triple-quoted blocks:

LICENSE

The big one-file-per-project statement

LICENSE_PREFIX

The smaller for-each-script header comment

Outputs

Full project dir tree

The result is a full dir tree, rooted where the mkpythonproj is run. It builds:

  myproj/
    RCS/
    AUTHORS              Pointer to doc/index.html
    COPYING              GPL license
    MANIFEST             list of included files
    README               Pointer to doc/index.html
    VERSION              used by setup to establish vernum of package
    setup.py             distutils "setup.py" plus doc and test options
    myproj.py            the same script as the simple case
    go                   runs the test
    doc/
      go                 builds the documents
      article_style.pdx  style sheet for pdx
      default_cfg.pdx    default configuration
      devguide.pdx       developer's guide
      devguide.html      same, output to html
      deshist.pdx        design history
      deshist.html       same, output to html
      manual.pdx         user's manual
      manual.html        same, output to html
    test/
      go                 the test script, which runs the ../myproj.py
                         (edit or extedn as needed for this project)

The actual script (here, myproj.py) has:

• copyright statement
• module name, version, and option globals
• standard imports
• functions for usage, debug, and fatal
• the main object class, with the inheritance parent commented out
• a "__main__" section which picks up getopt style options

Simple script

The "--script" option generates a single script. It is the same script as generated in the full project, but it is made in the current dir, not in a new dir. Thus, it can be used to make several scripts in the same package dir.

Setup

The "--setup" option generates a new setup.py file. This is in anticipation of future improvements to distutils. An old setup.py is renamed to ".bak".

Documents

The "--doc" option generates new document files. Old doc files are renamed to ".bak". The initial doc templates are pdx-centric, but could be changed to pythondoc-centric.

Implementation Issues