Developers
This page contains the instructions for developers that want to modify and contribute to the PySI project.
The topics covered here are:
- Code develpment and releases
- Coding Standards
- PySIApp help system development
- Package documentation
- Code testing
Currently there are two main branches of the git repository used.
- changes - where all derived branches for code development should be made from.
- master - where the released code is.
For the time being, only the originator of PySI retains the ability to check in on the master branch. Anyone can check in on any other branches. Periodically, during development, developers should merge the branch changes onto their branch to keep up to date with any currently approved changes - meaning they are not released, but they are intended to be released at some point in time. When any development branches are complete enough, the changes branch should be merged onto the development branch, any problems resolved, and then the development branch should be merged onto changes. A release occurs by merging the changes branch onto the master branch.
PySI doesn't really adhere strictly to any particular coding standards. There are, however, a few things to make sure of. One is that unit tests are generated for any new code and that code coverage is checked. Because this code is developed in conjunction with a text book, there are listings that appear in the book and this causes the need for certain special things done during the existing unit tests. You will find that some tests write listings that are included in the book. The code that writes these listings strip off the comments (as these can be read in the accompanying code documentation), and removes certain esoteric code that is deemed to not be of interest in the textbook. In other words, the textbook is concentrating on the algorithms themselves and as such don't need to list certain exception checking and handling, results caching and other things that would detract from the understanding of the algorithm. The control over the listings is performed through the use of comment lines containing the word pragma . Comment lines containing this will look for other tokens that control how the pragma is executed during code listing generation:
- exclude - tells the generator to begin excluding lines.
- include - tells the generator to begin including lines again.
- silent - tells the generator to be silent when excluding lines. Silent exclusion means the lines simply disappear from the listing. Otherwise, excluded lines are replaced with an ellipses (...) to indicate that something is not being shown.
- outdent - sometimes code is excluded that would normally cause the subsequent code to be indented, and removing the code would cause the indentation to be incorrect. For example, the removal of an if statement. outdent tells the generator to outdent the subsequent code.
- indent - after a section that is usually indented, but has been outdented in the listing, indent tells the generator to begin indenting again. All of this detail really only pertains to the accompanying book, but while code is being modified, it is good to keep these areas properly up to date. Since the code listings are written in unit tests, the regression tests will fail whenever code that generates a listing is modified, but prior to relearning the test, the proper listing format should be checked. Also, code listings that appear in the book must meet certain criteria that is also tested by the unit tests, these are:
- number of lines (cannot exceed a hard-coded constant number currently set to 67)
- line length (cannot exceed a hard-coded constant number currently set to 88 characters) Any listing generated that exceeds these numbers and fails the test simply cannot be included in the book until fixed. Fixing can be made by reduction of line lengths, usually by breaking lines, and reduction of code length either through the use of pragmas, or by breaking up the method. Class listings are made often with multiple methods listed, and sometimes these class listings can be broken into multiple listings showing the multiple methods.
The help system for PySIApp is written in LyX in the file PySIHelp.lyx. The file is converted into a sort of website under the directory PySIHelp.html.LyXconv using a program called elyxer project. I have only ever been successful in setting this up on a linux machine, and when set up properly, the help system is built using the file convert.sh. Linkage between the help system and PySIApp is very important, especially in the area of control help. If you examine PySIApp, you will find that the UI is put together using a class called Doers. Doers do something when executed and maintain the help system linkage (through labels placed throughout the help system) and the code that the doer executes, the pull-down menu system and ribbon bar icons. This was mostly done to avoid all of the coordination required with activating and deactivating things (a doer can be deactivated and it's ribbon bar icon goes gray along with the pull-down menu item. But the important thing here is to maintain the connection between the help system links in each doer and the labels in the help system. Someday a test should be made for this, but for now, one simply needs to be careful.
The SignalIntegrity library is organized in packages starting at a level just under PySI called SignalIntegrity. In the SignalIntegrity directory is an init file that works its way through all of the other package directories importing them from the SignalIntegrity base. Usually a script begins with the line:
import SignalIntegrity as si
then all of the objects are listed as si.xxx where xxx are the initials in init (using the initials added by other, deeper init calls.
A software developer using scripts based on the SignalIntegrity package uses the package documentation. This documentation was generated using a tool called Doxygen. Unfortunately, Doxygen is a tool made for C++ and Java and is not perfect for Python. I chose it originally because it is capable of creating LaTeX documentation that was originally intended with my book - that idea was abandoned. But still, it produces a very good documentation system. Again, I've only been successful setting this up on a Linux machine. When properly set up, it is invoked from the Doc directory using:
doxygen SignalIntegrity
This uses the configuration provided in the SignalIntegrity configuration file and blows out two directories underneath - one called latex with the LaTeX documentation and another called xhtml with the web documentation.
SignalIntegrity is brought to you by:
