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.
- Umbrello must be available in your
PATH
asumbrello5
. - rsvg-convert must be available in your
PATH
(it is required to transform the SVGs produced by Umbrello into PDFs).
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):
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 likeint
) - 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 namestd
(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.
- Logical View
- 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!
To use this program,
just clone this repo
or download the source code
and run ./uml2latex.py
.
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)
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.
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 packagepackage_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!
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/.