Autogenerera UML och dokumentation

Att kunna autogenerera UML diagram och dokumentation sparar en himla massa tid och kraft. Python och Pylint har en del inbyggda verktyg för just detta. Vi ska titta lite närmare på ett verktyg för att skapa UML-diagram utifrån koden och ett verktyg för att skapa html-sidor med dokumentation.

#Förutsättning

Du kan grunderna i Python och du vet vad variabler, typer och funktioner innebär.

#Autogenerera UML-diagram

Verktyget “Pyreverse” är sedan 2008 integrerat med Pylint och tillåter oss att skapa olika diagram utifrån färdig kod. Det är så kallad “reverse engineering”. Man plockar isär något färdigt för att ta reda på hur det är uppbyggt.

Man kan generera olika typer av diagram och i olika format. För att ta reda på vilka format som finns tillgängliga kan man använda:

$ dot -Tx
Format: "x" not recognized. Use one of: canon cmap cmapx cmapx_np dot eps fig gd gd2 gif gv imap imap_np ismap jpe jpeg jpg pdf pic plain plain-ext png pov ps ps2 svg svgz tk vml vmlz vrml wbmp x11 xdot xdot1.2 xdot1.4 xlib

Du kan behöva något extra paket för att få till en .png-fil men Pyreverse säger till vad som behövs om du försöker skapa en.

Antagligen är det Graphviz som fattas och det installerar du med din vanliga pakethanterare.

Windows/Cygwin:

apt-cyg install graphviz

Mac:

brew install graphviz

Linux:

apt-get install graphviz

Vi utgår ifrån filen car.py:

#!/usr/bin/env python3

class Car():
    wheels = 4
    carCount = 0
    equipment = []

    def __init__(self, model, price):
        self.model = model
        self.price = price
        self.__priv = 4

        Car.carCount += 1

    def printPriv(self):
        print(self.__priv)

    def presentCar(self):
        print("Model: {m}, Price: {p}".format(m=self.model, p=self.price))

    def addEquipment(self, newEquipment):
        self.equipment.append(newEquipment)

    def printEquipment(self):
        for eq in self.equipment:
            print("* " + eq)

    def __add__(self, other):
        return self.price + other.price

I samma mapp använder vi Pyreverse:

$ pyreverse -o png car

Nu genereras en .png-fil med ett diagram över klassen Car från car.py. Vi har inte angivit något namn för filen så den heter: “classes_No_Name.png”.

För att sätta ett namn använder man flaggan -p someName. För att se en lista på vad man kan åstadkomma skriver man:

$ pyreverse -h

#Autogenerera dokumentation

Python(3) kommer med verktyget Pydoc. Det hjälper oss att utifrån färdig kod, generera dokumentation alternativt se dokumentationen från exempelvis inbyggda moduler och klasser: (Använder du Cygwin kan du behöva starta med pydoc3)

# Visa dokumentationen från den inbyggda klassen "str"
$ pydoc str

Vi testar att kika på dokumentationen över vår klass “Car”. Vi ställer oss i mappen som har filen car.py och skriver:

$ pydoc car

#Skapa html-fil

Vi utgår ännu en gång från klassen “Car” och exekverar kommandot pydoc -w car för att skapa en .html-fil med den extraherade dokumentationen. Filen kommer hamna i den aktuella mappen.

#Serva html-fil

Pydoc kan även starta en server som tillhandahåller html-filerna för granskning. Då använder man kommandot pydoc -p 1337 (Startar servern på port 1337). Man får även se dokumentationen över inbyggda moduler funktioner. Det är kanske mer aktuellt att få den dokumentationen om python3 så vi startar servern med pydoc3 -p 1337:

$ pydoc3 -p 1337
Server ready at http://localhost:1337/
Server commands: [b]rowser, [q]uit
server>

Starta en webbläsare och skriv in http://localhost:1337 i adressfältet:

Som vi ser har vi vår Car-klass i mappen “.” vilket representerar mappen vi startade servern från.

#Avslutningsvis

Det finns självklart mycket mer att gå igenom med dessa verktygen. Vill du veta mer kan du kika på:

1. Pyreverse

2. Pydoc

#Revision history