/uml2latex

A tool for transforming Umbrello's XMI format into LaTeX formatting.

Primary LanguagePythonGNU General Public License v3.0GPL-3.0

uml2latex

A tool for transforming Umbrello's XMI format into LaTeX formatting.

uml2latex reads your Umbrello project file and automatically generates a LaTeX file from it. It will render your class and sequence diagrams to PDF and include them in the document along with individual package documentation and class lists as well as documentation for individual classes - attributes, operations, template parameters, dependencies, associations, and inheritance relationships are all extracted.

uml2latex will use Umbrello's documentation fields (available for essentially every object) to generate the descriptive texts for each diagram / package / class. Class and package names will also be linked to each other within the LaTeX document. You can even use arbitrary LaTeX formatting within the documentation fields in Umbrello - it will be transferred to the final file verbatim.

You can also define orderings, custom formatting for certain packages, and much more via "template override" files in a directory passed to uml2latex. They use a format where you can specify arbitrary LaTeX and put special macros on their own lines, where uml2latex will replace them with e.g. the appropriate diagram or a list of class methods. You can even reorder the entire generated document.

LaTeX examples

package listing example class description example

Requirements

  • Umbrello must be available in your PATH as umbrello5.
  • rsvg-convert must be available in your PATH (it is required to transform the SVGs produced by Umbrello into PDFs).

LaTeX document file

The LaTeX file generated by uml2latex is not suitable for direct compilation and must instead be included in another document (via \include{<generated_document>.tex}).

uml2latex uses commands defined by some auxiliary LaTeX packages, which must be loaded in the main file.

These are (in the following order, make sure to load nameref and hyperref last):

(Current) Limitations

uml2latex originated as a script I put together in a weekend after I realized our team didn't have a good way to turn our Umbrello design and documentation into the required final LaTeX document. I have now reworked it into a more organized piece of software. However, it still has some limitations given its origin. None of these problems are unsolvable - I just haven't gotten around to solving them yet.

  • uml2latex still contains some hardcoded strings with things like German section titles. WORKAROUND: Just replace them with your own strings.
  • There is some inconsistent naming: packages and modules are the same thing, but both terms are used. That needs to be cleaned up.
  • Class diagrams are automatically sorted into two categories: Those with the same name as a packages, which are placed by the package listing, and "free" diagrams, which are placed into their own section. Currently, which diagrams appear in the free diagram section depends on whether the package listing section came before or after it. WORKAROUND: Make sure the package listings come before the free diagrams.
  • uml2latex assumes a specific structure in the Umbrello project:
    • Logical View
      • All class diagrams belong on this level
      • Packages containing classes and data types
        • No nested packages or classes
      • A folder named Sequenzdiagramme (hardcoded string) containing sequence diagrams
      • A folder named Datatypes containing types you don't want to document (things like int)
      • A package named std containing types from the standard library The biggest limitations here are likely the "no nested packages" rule and the standard library name std (Yes, the original project was in C++). Adding the capability to handle nested packages mostly requires some thought into how they should be presented in the LaTeX document.
  • General naive parsing of the XMI file that might lead to missed elements.

If you feel like tackling one of these problems (or any of the 2000 others I haven't noticed or mentioned here), feel free to submit a PR!

Usage

To use this program, just clone this repo or download the source code and run ./uml2latex.py.

Command line

usage: uml2latex.py [-h] [-n] [-o OUTPUT] [-t TEMPLATES] [-i OUTIMAGES] FILE

Create LaTeX documentation from an Umbrello file

positional arguments:
  FILE                  The Umbrello UML file to read

optional arguments:
  -h, --help            show this help message and exit
  -n, --no-pics         Do not generate class diagram images
  -o OUTPUT, --output OUTPUT
                        Output to the given file instead of stdout
  -t TEMPLATES, --templates TEMPLATES
                        The directory to read template override files from ('template_override' by default)
  -i OUTIMAGES, --outImages OUTIMAGES
                        The directory to place the produced images in ('outImages' by default)

Generated LaTeX

uml2latex will generate multiple sections for different parts of the documentation. Which sections appear and their order can be controlled using template override files (see the Configuration section).

The currently supported sections are:

  • An architecture section listing all the packages in the project along with a list of their member classes and (if available) a class diagram from Umbrello (which must have the same name as the package).
  • A free class diagram section featuring all the class diagrams not associated with a particular package.
  • A class descriptions section featuring descriptions, method lists, etc. for all the classes by package shown in the architecture section.
  • A sequence diagram section featuring all the sequence diagrams in the Umbrello "Sequenzdiagramme" folder.

If you want to reference some element of the generated documentation in the rest of your LaTeX document, you can use the command \nameref{<name>} with the correct class, package, or diagram name to generate a link to it. uml2latex will do this automatically in the LaTeX that it generates (method parameters for example), but you'll have to do it yourself in any documentation you write in Umbrello.

Configuration

Despite the limitations mentioned above, uml2latex supports a relatively powerful configuration method in the form of "template override" files.

uml2latex will check the given template directory ($PWD/template_override by default) for files with specific names (see below for a list). The contents of those files are then applied to the generation of the LaTeX document.

There are two different types of files:

  • Lists that specify an order for elements of some sort of list, or just specify a list of elements in general. These should consist only of names of the list elements, separated by newlines. If one of these files isn't given, the list it controls is considered empty and any ordering of its elements is undefined. If an element does not appear in a list that controls element ordering, that element will not be included in the final document.
  • Descriptions that contain arbitrary LaTeX formatting to be used as the describing text in a section. If one of these files isn't given, no describing text will be used.
  • Macro files that can contain arbitrary LaTeX formatting along with macros starting with %, which must be placed on their own lines. In document generation, the macros will be replaced with the corresponding formatting (docstrings, diagrams, etc.) and the resulting text will be used in the final document. The special macro %FULL will be replaced with the entire default-generated formatting in any macro file. You can use these macros to introduce special formatting, notes, extra documentation, or to reorder parts of the documentation. If one of these files isn't given, it is treated as if it existed and contained only one line with the %FULL macro, which is equivalent to using all the macros available for that file in the order given below.

These list files can be placed in the template override directory:

  • %DIAGRAM_ORDER: Controls the order of the class diagrams in the free class diagram section. Use the names of the diagrams as visible in Umbrello.
  • %SEQUENCE_DIAGRAM_ORDER: Controls the order of the sequence diagrams in the sequence diagram section. Use the names of the diagrams as visible in Umbrello.
  • %MODULE_ORDER: Controls the order of packages in the package list and class description sections. Use the names of the packages as visible in Umbrello.
  • %NOREF: Class and datatype names in this file will not be linked to in LaTeX, preventing broken links to library types or built-in types. Use the names of the classes or data types as visible in Umbrello.
  • %CUSTOM_WIDTH: A list of space separated class name and integer pairs. Unfortunately, Umbrello doesn't automatically scale classes correctly when generating the images for the class descriptions, so the width and height of the diagram have to be approximated. The height approximation works pretty well, but the width approximation may fail when very long methods or argument lists are involved. In those cases, you can place the class name and a desired width for the diagram in a line in this file like so: <class_name> <width> That width will then be used when generating the image for that class.
  • <package_name>%ORDER: Controls the order of the classes in the package package_name in the package member list and that package's class description section. Use the names of the classes as visible in Umbrello.

These description files can be placed in the template override directory:

  • %ARCHITECTURE_DESC: Controls the text placed before the %MODULES package list.
  • %SEQUENCE_DESC: Controls the text placed before the %SEQUENCES sequence diagram section.
  • %CLASSES_DESC: Controls the text placed before the %DESCRIPTIONS class description section.

These macro files can be placed in the template override directory:

  • %ROOT: Controls the arrangement of the top-level ("root") sections in the final document. The following macros can be used in this file:
    • %MODULES: Place the list of packages, their classes and diagrams here.
    • %DIAGRAMS: Place the free class diagram section here.
    • %DESCRIPTIONS: Place the class description section here.
    • %SEQUENCES: Place the sequence diagram section here.
  • <package_name>%LISTING: Controls the arrangement of the listing of the given package in the %MODULES package list. The following macros can be used in this file:
    • %HEADER: Place the package name here in a subsection command.
    • %DESCRIPTION: Place the package description (extracted from Umbrello) here.
    • %CLASSLIST: Place the list of classes in this package here (in the same order as in the class description section).
    • %DIAGRAM: Place the diagram with the same name as this package here.
  • <diagram_name>%DIAGRAM: Controls the arrangement of the formatting for the given class or sequence diagram in the %SEQUENCES or %DIAGRAMS sections. If Umbrello documentation is available for the diagram, the following macros can be used in this file. If no Umbrello documentation is available, only the %DIAGRAM macro can be used in the file. The diagram will have its name in the top left and will be assigned a subsection.
    • %HEADER: Place the diagram name here in a subsection command.
    • %DESCRIPTION: Place the diagram description (extracted from Umbrello) here.
    • %DIAGRAM: Place the diagram here.
  • <class_name>%CLASS: Controls the arrangement of the description of the given class in the %DESCRIPTIONS class description section. The following macros can be used in this file:
    • %HEADER: Place the class name here in a subsubsection command.
    • %DIAGRAM: Place an image of the class in "UML format" here.
    • %DESCRIPTION: Place the class's description (extracted from Umbrello) here.
    • %TEMPLATE: Place the list of the class's template parameters with descriptions (extracted from Umbrello) here.
    • %OPERATIONS: Place the list of the class's methods and functions with descriptions (extracted from Umbrello) here.
    • %ATTRIBUTES: Place the list of the class's attributes with descriptions (extracted from Umbrello) here.
    • %CHILDREN: Place the list of the class's children with descriptions (extracted from Umbrello) here.
    • %DEPENDENCIES: Place the list of the class's dependencies with descriptions (extracted from Umbrello) here.
    • %ASSOCIATIONS: Place the list of the class's associations with descriptions (extracted from Umbrello) and multiplicities here.

If none of these configuration options are satisfactory, feel free to modify the program itself until you get the desired results.

If you think your modifications would be helpful to others as well, submit a PR!

License

This file is part of uml2latex.

uml2latex is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

uml2latex is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with uml2latex. If not, see https://www.gnu.org/licenses/.