When it comes to code documentation, in my opinion, everyone involved with software get's thrilled.
This is due to two things:
- Having to write software without a good language reference and intensive internet search is horrible, because every line of code might have been so much better if you would have known how to do so.
- Analyzing someone elses code becomes a pain, if he or she did not document hers/his code.
Documentation can be:
- comments directly in the code
- an additional file with Classdiagramms, Sequence charts, ...
- an online help
- a good book on used patterns with the programming language (more a reference)
If you have to any experience in writing code you will more or less agree with me, when I point out that working on a project is much more fun if the documentation is good.
Therefore I like using UML-graphs, sequence diagrams or GUI mockups with salt .
The problem is: I'm lazy! (which according to other programmers is good, cause my aim is to keep it simple)
I don't want to draw all those diagramms with DIA or whatsoever tool.
I want to be able to:
- make rapid changes (like when coding)
- see the result more or less instantly (wysiwyg)
- have a lightweight tool (not 10.000 other (unused) functions
- offline capability
This is where plantuml comes into play. It has many functions (sequence charts, class diagramms, state diagramms, ...) but it is a command line tool which has to be fed with the source file as parameter or it is available as a web service.
I want to make rapid changes and don't like searching for my source files / output images or beeing not able to use it while not having the possibility to reach the web service.
Therefor I wrote a lightweight Python application which is attached in the following steps. Use it as a basis if you are anything like me and want to improve your programmers life with a small lightweight solution for code documentation.
Step 1: Get the Needed Dependencies
For the software the following dependencies are needed
- Java (needed for excecution of plantuml)
- Python (version >= 2.7.9)
- easy_install (for easy loading of Python modules)
- Pillow (graphics module for Python)
Step 2: Get the Software Modules
Install the software modules in the following order.
- download from python.org (link in last step)
- download script from website (link in last step)
- execute script
- open command prompt and insert command "easy_install Pillow"
- close all python instances
- after that you should be able to import PIL(low) in Python (IDLE)
- download from plantuml.com (link in last step
- put in any location you want (just find it later)
- download from www.graphviz.org (link in last step)
Step 3: The Source Code (modification Needed!)
Here is my source code for the application. Look through it and try to understand it.
- config (with simple editor)
- add full directory+filename for plantuml.jar in given python dict
- look for "###" in file (Strg+F for find)
- change file addresses for images (in directory icons) if needed
Step 4: Test It / Use It / Modify It
Take the given source code and the following sites to do so:
- all of the above and way more ;-)
Feel free to leave me some comments and your thoughts.
I can't promise I'll have the time to make improvements, but maybe I'll have the time to do so and publish it here.