This documentation is written using Markdown syntax. Every page or "article" is a Markdown (.md) file located here in the official SUMO GitHub repository. The static html pages are then generated using Mkdocs.
Feel free to contribute and improve the SUMO Documentation. All changes need to be via Pull requests. You can click on the "Edit on GitHub" button in the top right corner of every page, or just simply press the e
key on your keyboard.
Note
Although HTML can be written within Markdown, please avoid using it and keep everything in native Markdown as much as possible.
Creating an article#
To create a new article (or page) just create a Markdown (.md) file in the documentation directory.
Note
Please capitalize the very first letter of the name and use _
(underscores) instead of leaving a (space) between words in the filename.
The very first 3 lines of each page should be:
---
title: Name of the Article
---
If you want to create an fresh new article, please consider first seeing the source code of any existing article, to learn and get some basic notions.
Sections and subsections#
Sections and subsections in a document are marked by using the #
character.
# is equivalent to a <h1> section, ## to an <h2> and so on.
Note
On the toc (table of content) sidebar you see on each page, only #, ## and ### sections are listed. Despite that, all other levels generate an internal link and therefore can be referenced and linked from another page.
Example#
#### This is a sub section, equivalent to <h4>
will display:
This is a sub section, equivalent to <h4>#
CSS classes, IDs and key/value pairs#
Markdown allows to use css classes, ids and key/value pairs: https://python-markdown.github.io/extensions/attr_list/
Custom classes:
.cellNoWrap
: Avoid a line break (useful in tables).
Example#
{: #someid .someclass somekey='some value' }
Styling text#
Element | Code | Will show as |
---|---|---|
Bold | **test** | test |
Italic | *test* | test |
Bold + Italic | ***test*** | test |
Strikethrough | ~~test~~ |
Markdown is compatible with the <sub>
and <sup>
html-Tags.
η<sub>recup</sub>=e<sup>x</sup>
ηrecup=ex
Example#
Lorem *ipsum* dolor sit amet, *consetetur sadipscing elitr*, sed diam **nonumy** eirmod **tempor invidunt ut labore** et ~~dolore~~ magna ***aliquyam erat, sed diam*** voluptua.
will display:
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.
Escape character#
Use the escape character in order to display literal characters which would have special meaning in Markdown. The escape character is \
(backslash). When writing text inside the `` marks (inline code) or in a code block, no escape character are required.
Here are some expressions that need an escape character:
- @ : if not, it would be taken as a GitHub username
- # : if not, it would be taken as a Header or a GitHub issue
- | : when using it inside a table
- >
- {
- }
- *
Example#
`<TEST1>` using code. No escape character is required here.
<TEST2> not using the escape character. Here the element disappears.
<TEST3\> using the escape character
will display:
<TEST1>
using code. No escape character is required here.
<TEST3> using the escape character
Images#
All images must be saved in the images directory. To insert an image, just use the usual Markdown syntax:
![<alt>](images/Wikicommons_rail_fast.jpg "<title>")
replace <alt>
with the alternate text and <title>
with the title to show on Mouseover.
Note
The <alt>
and <title>
attributes are not necessary required, as you can see in the example.
Example#
![](images/Wikicommons_rail_fast.jpg)
will display:
Tables#
See this Online Tables generator to get help creating a Table in Markdown, or to convert an existing spreadsheet (e.g. Microsoft Excel) into Markdown.
A table has a Header (the first row), which is separated by hyphens -
from the rest of the Table.
To separate columns, just use a pipe |
.
Example#
| | | | | |
|---|---|---|---|---|
| | | | | |
| | | | | |
| | | | | |
will display:
Note
It is important to leave an empty line (line break) immediately before and immediately after a table.
Math#
In order to insert Mathematical expressions (symbols or equations), you should write them in LaTeX format. Math elements are being displayed as images, using a html <img>
element.
Just replace <HERE>
with your math expression in the following html element:
<img src="https://latex.codecogs.com/gif.latex?<HERE>" border="0" style="margin:0;"/>
Example#
<img src="https://latex.codecogs.com/gif.latex?R" border="0" style="margin:0;"/>
will display:
<img src="https://latex.codecogs.com/gif.latex?F(x)=\int^a_b\frac{1}{3}x^3" border="0" style="margin:0;"/>
will display:
Macros / Variables#
In order to make writing this Documentation easier, we implemented some Macros. Macros replace some special text with other content.
Example#
{{SUMO}} {{DT_FILE}} {{DT_STR}} {{Version}}
will display:
<SUMO_HOME> <FILE> <STRING> 1.20.0
Note
The full list of available Macros can be found here at the end in the extra
section.
Caution
Macros do not work inside inline code or code blocks.
Links#
When linking to a page within this Documentation, please consider the absolute path to the Markdown file.
Do not forget to add the .md
extension to every internal link.
Links to external pages will display an arrow at the end (e.g. DLR).
Links to files in the SUMO GitHub repo#
Using the {{Source}} Macro, linking to files in the official SUMO repository on GitHub is as easy as:
- [Read the gitignore file]({{Source}}.gitignore) Read the gitignore file
Note
The {{Source}} macro is equivalent to https://github.com/eclipse-sumo/sumo/blob/main/ including the /
at the end. Please analyze the following example:
- [{{SUMO}}/src/sumo_main.cpp]({{Source}}src/sumo_main.cpp) <SUMO_HOME>/src/sumo_main.cpp
Internal Links#
Internal links are used to refer a special section of an article. You can obtain the internal link to a section by hovering the cursor next to the section title (an # character will appear).
Linking to a section within the same page is as easy as this: Read about Math [Read about Math](#math)
Caution
All texts in internal links are in lower case.
To reference a section on another page, do not forget to put the absolute path and the .md
extension, like this: Read about SUMO input [Read about SUMO input](sumo.md#input)
Some characters are being ignored (deleted) or replaced when generating an internal link:
.
is ignored:
is ignored?
is ignored'
is ignored"
is ignored/
is ignored>
is ignored(
is converted to_
)
is converted to_
(space) is converted to
_
Here are some practical examples:
Section title | Actual link |
---|---|
tools fail with a SyntaxError or ImportError or some TypeError concerning ">>" | #tools_fail_with_a_syntaxerror_or_importerror_or_some_typeerror_concerning |
Why do I get errors about missing files / file not found even though the file exists? | #why_do_i_get_errors_about_missing_files_file_not_found_even_though_the_file_exists |
Version 1.3.1 (27.08.2019) | #version_131_27082019 |
Note
No permalink ends with a _
character.
Example#
Go to [sumo-gui](sumo-gui.md), [netconvert options](netconvert.md#options) or [Notation](Basics/Notation.md)
<https://www.dlr.de> or [DLR](https://www.dlr.de)
- [Read the gitignore file]({{Source}}.gitignore)
- [{{SUMO}}/src/sumo_main.cpp]({{Source}}src/sumo_main.cpp)
will display:
Go to sumo-gui, netconvert options or Notation
GitHub issues, commits and users#
In order to use the # and @ characters freely, please use the escape character.
Element | Code | Will show as |
---|---|---|
GitHub issue | #5697 | #5697 |
GitHub user | @namdre | @namdre |
GitHub commit | 3aa106d1bf3221031cca75cfe259913d9d3e88ae (the complete Commit Hash) |
3aa106d |
Example#
The issue #5697 was reported by @angelobanse. @behrisch commited 3aa106d1bf3221031cca75cfe259913d9d3e88ae to close that issue.
will display:
The issue #5697 was reported by @angelobanse. @behrisch commited 3aa106d to close that issue.
Notes#
The NOTE and CAUTION elements are useful for highlighting important information. You can also use a custom note type.
Inside a Note element you can use Markdown syntax to insert links, stylize text and even insert images.
Caution
Unfortunately, you cannot insert a note in a Table.
Example#
!!! note
When citing SUMO in general please use our current reference
publication: ["Microscopic Traffic Simulation using SUMO"](https://elib.dlr.de/124092/);
Pablo Alvarez Lopez, Michael Behrisch, Laura Bieker-Walz, Jakob Erdmann, Yun-Pang Flötteröd,
Robert Hilbrich, Leonhard Lücken, Johannes Rummel, Peter Wagner, and Evamarie Wießner.
IEEE Intelligent Transportation Systems Conference (ITSC) 2018.
!!! caution
The list of not allowed characters is incomplete
!!! incomplete "Missing:"
This is just a test
{{Outdated}}
will display:
Note
When citing SUMO in general please use our current reference publication: "Microscopic Traffic Simulation using SUMO"; Pablo Alvarez Lopez, Michael Behrisch, Laura Bieker-Walz, Jakob Erdmann, Yun-Pang Flötteröd, Robert Hilbrich, Leonhard Lücken, Johannes Rummel, Peter Wagner, and Evamarie Wießner. IEEE Intelligent Transportation Systems Conference (ITSC) 2018.
Caution
The list of not allowed characters is incomplete
Missing:
This is just a test