SysMLv2 Model Overview and other MkDocs tricks

As of now, most of it is just demonstrating mkdocs and Python features. More and more of it will be replaced by meaningful SysML V2 model analyses using the SysIDE Automator library.

The code blocks are shown in this page for educational purposes using the markdown-exec mkdocs plugin, but in real documentation, the source code used to render things will be hidden most of the time.

Basics

LaTex

$\alpha$

\(\alpha\)

HTML attribute lists and image resizing

The attr_list python-markdown extension is installed, which allows adding HTML attributes to a markdown element.

A typical use case is to resize an image, for instance:

![My image](https://i.ytimg.com/vi/U_662Tvmj64/sddefault.jpg){width=40%}

My image

![My image](https://i.ytimg.com/vi/U_662Tvmj64/sddefault.jpg){width=20%}

My image

Interactive plots

From JSON data

The mkdocs-plotly-plugin allows plotting plotly interactive graphs in JSON format.

```plotly
{
    "data": [
        {
            "x": ["giraffes", "orangutans", "monkeys"],
            "y": [20, 14, 23],
            "type": "bar"
        }
    ]
}
```

{ "data": [ { "x": ["giraffes", "orangutans", "monkeys"], "y": [20, 14, 23], "type": "bar" } ] }

From inline Python code

```python exec="on"
import plotly.express as px
import numpy as np
t = np.linspace(0, 4*np.pi, 100)

fig = px.line(x=t, y=np.cos(t), labels={'x':'t', 'y':'cos(t)'})
print("```plotly\n" + fig.to_json() + "\n```")
```

{"data":[{"hovertemplate":"t=%{x}\u003cbr\u003ecos(t)=%{y}\u003cextra\u003e\u003c\u002fextra\u003e","legendgroup":"","line":{"color":"#636efa","dash":"solid"},"marker":{"symbol":"circle"},"mode":"lines","name":"","orientation":"v","showlegend":false,"x":{"dtype":"f8","bdata":"AAAAAAAAAACRGkt8Vz\u002fAP5EaS3xXP9A\u002f2qdwOgNf2D+RGkt8Vz\u002fgPzXhXVstT+Q\u002f2qdwOgNf6D9+boMZ2W7sP5EaS3xXP\u002fA\u002f433Ua0JH8j814V1bLU\u002f0P4dE50oYV\u002fY\u002f2qdwOgNf+D8sC\u002fop7mb6P35ugxnZbvw\u002f0NEMCcR2\u002fj+RGkt8Vz8AQDrMD\u002fRMQwFA433Ua0JHAkCML5njN0sDQDXhXVstTwRA3pIi0yJTBUCHROdKGFcGQDD2q8INWwdA2qdwOgNfCECDWTWy+GIJQCwL+inuZgpA1by+oeNqC0B+boMZ2W4MQCcgSJHOcg1A0NEMCcR2DkB5g9GAuXoPQJEaS3xXPxBAZnMtOFLBEEA6zA\u002f0TEMRQA8l8q9HxRFA433Ua0JHEkC41rYnPckSQIwvmeM3SxNAYYh7nzLNE0A14V1bLU8UQAo6QBco0RRA3pIi0yJTFUCz6wSPHdUVQIdE50oYVxZAXJ3JBhPZFkAw9qvCDVsXQAVPjn4I3RdA2qdwOgNfGECuAFP2\u002feAYQINZNbL4YhlAV7IXbvPkGUAsC\u002fop7mYaQABk3OXo6BpA1by+oeNqG0CpFaFd3uwbQH5ugxnZbhxAUsdl1dPwHEAnIEiRznIdQPt4Kk3J9B1A0NEMCcR2HkCkKu\u002fEvvgeQHmD0YC5eh9ATdyzPLT8H0CRGkt8Vz8gQPtGPNpUgCBAZnMtOFLBIEDQnx6WTwIhQDrMD\u002fRMQyFApPgAUkqEIUAPJfKvR8UhQHlR4w1FBiJA433Ua0JHIkBNqsXJP4giQLjWtic9ySJAIgOohToKI0CML5njN0sjQPZbikE1jCNAYYh7nzLNI0DLtGz9Lw4kQDXhXVstTyRAoA1PuSqQJEAKOkAXKNEkQHRmMXUlEiVA3pIi0yJTJUBJvxMxIJQlQLPrBI8d1SVAHRj27BoWJkCHROdKGFcmQPJw2KgVmCZAXJ3JBhPZJkDGybpkEBonQDD2q8INWydAmyKdIAucJ0AFT45+CN0nQG97f9wFHihA2qdwOgNfKEBE1GGYAKAoQK4AU\u002fb94ChAGC1EVPshKUA="},"xaxis":"x","y":{"dtype":"f8","bdata":"AAAAAAAA8D9o+gYFGL7vPyN\u002fFo5v+e4\u002fXLHeqjC17T9foQT4kvbrP1YykSHGxOk\u002ftDkVSdQo5z9AE3HJfC3kP1wsoPEH3+A\u002fthLH2SiW2j9bQ2NRvgDTP4xzC34aOsY\u002fcyCwKKhcqD8MyeikuUm0v0\u002feq9oaN8q\u002fPSGBd67u1L+LyZhelmvcv8\u002fm3JG2ueG\u002fhlh3f5705L9dUsfUNNnnv10cd\u002f2OW+q\u002fwfLvCVdx7L8bLVJC9hHuv0PyRoe4Nu+\u002fXjTx7ufa778HB0As4PvvvwQ9tXAZme+\u002fV1DNmyq07r\u002fZTwivwlDtv4lZi6GZdOu\u002fJeDa0Vgn6b\u002faPrV2e3Lmv8y0DJEnYeO\u002f+f\u002f\u002f\u002f\u002f\u002f\u002f3783i\u002fTn4LnYv4yAwi7oDdG\u002f3kQPZF83wr9U+ijPKj+QvxHsuGvkX7w\u002fk1rgSlktzj+GU4hOOdfWP1m1P3WwOd4\u002fAasNgtOP4j+XUJVeWbblPzdQz6Jvg+g\u002fuvBkh4zr6j99NRQyxuTsP\u002fFJcov7Zu4\u002fJuk3u\u002fVr7z+VSynBge\u002fvP5RLKcGB7+8\u002fJek3u\u002fVr7z\u002fvSXKL+2buP381FDLG5Ow\u002fuPBkh4zr6j86UM+ib4PoP5RQlV5ZtuU\u002fBasNgtOP4j9TtT91sDneP45TiE4519Y\u002fhVrgSlktzj807Lhr5F+8P8f6KM8qP5C\u002fzUQPZF83wr+TgMIu6A3Rvy+L9Ofgudi\u002fBwAAAAAA4L\u002fPtAyRJ2Hjv9k+tXZ7cua\u002fI+Da0Vgn6b+NWYuhmXTrv9pPCK\u002fCUO2\u002fV1DNmyq07r8DPbVwGZnvvwgHQCzg+++\u002fXjTx7ufa779E8kaHuDbvvx4tUkL2Ee6\u002fwPLvCVdx7L9dHHf9jlvqv2BSx9Q02ee\u002fgVh3f5705L\u002fM5tyRtrnhv4zJmF6Wa9y\u002fRSGBd67u1L8x3qvaGjfKv\u002fDI6KS5SbS\u002fbSCwKKhcqD9zcwt+GjrGP2ZDY1G+ANM\u002fuRLH2SiW2j9aLKDxB9\u002fgPzsTccl8LeQ\u002fuDkVSdQo5z9WMpEhxsTpP16hBPiS9us\u002fX7HeqjC17T8kfxaOb\u002fnuP2j6BgUYvu8\u002fAAAAAAAA8D8="},"yaxis":"y","type":"scatter"}],"layout":{"template":{"data":{"histogram2dcontour":[{"type":"histogram2dcontour","colorbar":{"outlinewidth":0,"ticks":""},"colorscale":[[0.0,"#0d0887"],[0.1111111111111111,"#46039f"],[0.2222222222222222,"#7201a8"],[0.3333333333333333,"#9c179e"],[0.4444444444444444,"#bd3786"],[0.5555555555555556,"#d8576b"],[0.6666666666666666,"#ed7953"],[0.7777777777777778,"#fb9f3a"],[0.8888888888888888,"#fdca26"],[1.0,"#f0f921"]]}],"choropleth":[{"type":"choropleth","colorbar":{"outlinewidth":0,"ticks":""}}],"histogram2d":[{"type":"histogram2d","colorbar":{"outlinewidth":0,"ticks":""},"colorscale":[[0.0,"#0d0887"],[0.1111111111111111,"#46039f"],[0.2222222222222222,"#7201a8"],[0.3333333333333333,"#9c179e"],[0.4444444444444444,"#bd3786"],[0.5555555555555556,"#d8576b"],[0.6666666666666666,"#ed7953"],[0.7777777777777778,"#fb9f3a"],[0.8888888888888888,"#fdca26"],[1.0,"#f0f921"]]}],"heatmap":[{"type":"heatmap","colorbar":{"outlinewidth":0,"ticks":""},"colorscale":[[0.0,"#0d0887"],[0.1111111111111111,"#46039f"],[0.2222222222222222,"#7201a8"],[0.3333333333333333,"#9c179e"],[0.4444444444444444,"#bd3786"],[0.5555555555555556,"#d8576b"],[0.6666666666666666,"#ed7953"],[0.7777777777777778,"#fb9f3a"],[0.8888888888888888,"#fdca26"],[1.0,"#f0f921"]]}],"contourcarpet":[{"type":"contourcarpet","colorbar":{"outlinewidth":0,"ticks":""}}],"contour":[{"type":"contour","colorbar":{"outlinewidth":0,"ticks":""},"colorscale":[[0.0,"#0d0887"],[0.1111111111111111,"#46039f"],[0.2222222222222222,"#7201a8"],[0.3333333333333333,"#9c179e"],[0.4444444444444444,"#bd3786"],[0.5555555555555556,"#d8576b"],[0.6666666666666666,"#ed7953"],[0.7777777777777778,"#fb9f3a"],[0.8888888888888888,"#fdca26"],[1.0,"#f0f921"]]}],"surface":[{"type":"surface","colorbar":{"outlinewidth":0,"ticks":""},"colorscale":[[0.0,"#0d0887"],[0.1111111111111111,"#46039f"],[0.2222222222222222,"#7201a8"],[0.3333333333333333,"#9c179e"],[0.4444444444444444,"#bd3786"],[0.5555555555555556,"#d8576b"],[0.6666666666666666,"#ed7953"],[0.7777777777777778,"#fb9f3a"],[0.8888888888888888,"#fdca26"],[1.0,"#f0f921"]]}],"mesh3d":[{"type":"mesh3d","colorbar":{"outlinewidth":0,"ticks":""}}],"scatter":[{"fillpattern":{"fillmode":"overlay","size":10,"solidity":0.2},"type":"scatter"}],"parcoords":[{"type":"parcoords","line":{"colorbar":{"outlinewidth":0,"ticks":""}}}],"scatterpolargl":[{"type":"scatterpolargl","marker":{"colorbar":{"outlinewidth":0,"ticks":""}}}],"bar":[{"error_x":{"color":"#2a3f5f"},"error_y":{"color":"#2a3f5f"},"marker":{"line":{"color":"#E5ECF6","width":0.5},"pattern":{"fillmode":"overlay","size":10,"solidity":0.2}},"type":"bar"}],"scattergeo":[{"type":"scattergeo","marker":{"colorbar":{"outlinewidth":0,"ticks":""}}}],"scatterpolar":[{"type":"scatterpolar","marker":{"colorbar":{"outlinewidth":0,"ticks":""}}}],"histogram":[{"marker":{"pattern":{"fillmode":"overlay","size":10,"solidity":0.2}},"type":"histogram"}],"scattergl":[{"type":"scattergl","marker":{"colorbar":{"outlinewidth":0,"ticks":""}}}],"scatter3d":[{"type":"scatter3d","line":{"colorbar":{"outlinewidth":0,"ticks":""}},"marker":{"colorbar":{"outlinewidth":0,"ticks":""}}}],"scattermap":[{"type":"scattermap","marker":{"colorbar":{"outlinewidth":0,"ticks":""}}}],"scattermapbox":[{"type":"scattermapbox","marker":{"colorbar":{"outlinewidth":0,"ticks":""}}}],"scatterternary":[{"type":"scatterternary","marker":{"colorbar":{"outlinewidth":0,"ticks":""}}}],"scattercarpet":[{"type":"scattercarpet","marker":{"colorbar":{"outlinewidth":0,"ticks":""}}}],"carpet":[{"aaxis":{"endlinecolor":"#2a3f5f","gridcolor":"white","linecolor":"white","minorgridcolor":"white","startlinecolor":"#2a3f5f"},"baxis":{"endlinecolor":"#2a3f5f","gridcolor":"white","linecolor":"white","minorgridcolor":"white","startlinecolor":"#2a3f5f"},"type":"carpet"}],"table":[{"cells":{"fill":{"color":"#EBF0F8"},"line":{"color":"white"}},"header":{"fill":{"color":"#C8D4E3"},"line":{"color":"white"}},"type":"table"}],"barpolar":[{"marker":{"line":{"color":"#E5ECF6","width":0.5},"pattern":{"fillmode":"overlay","size":10,"solidity":0.2}},"type":"barpolar"}],"pie":[{"automargin":true,"type":"pie"}]},"layout":{"autotypenumbers":"strict","colorway":["#636efa","#EF553B","#00cc96","#ab63fa","#FFA15A","#19d3f3","#FF6692","#B6E880","#FF97FF","#FECB52"],"font":{"color":"#2a3f5f"},"hovermode":"closest","hoverlabel":{"align":"left"},"paper_bgcolor":"white","plot_bgcolor":"#E5ECF6","polar":{"bgcolor":"#E5ECF6","angularaxis":{"gridcolor":"white","linecolor":"white","ticks":""},"radialaxis":{"gridcolor":"white","linecolor":"white","ticks":""}},"ternary":{"bgcolor":"#E5ECF6","aaxis":{"gridcolor":"white","linecolor":"white","ticks":""},"baxis":{"gridcolor":"white","linecolor":"white","ticks":""},"caxis":{"gridcolor":"white","linecolor":"white","ticks":""}},"coloraxis":{"colorbar":{"outlinewidth":0,"ticks":""}},"colorscale":{"sequential":[[0.0,"#0d0887"],[0.1111111111111111,"#46039f"],[0.2222222222222222,"#7201a8"],[0.3333333333333333,"#9c179e"],[0.4444444444444444,"#bd3786"],[0.5555555555555556,"#d8576b"],[0.6666666666666666,"#ed7953"],[0.7777777777777778,"#fb9f3a"],[0.8888888888888888,"#fdca26"],[1.0,"#f0f921"]],"sequentialminus":[[0.0,"#0d0887"],[0.1111111111111111,"#46039f"],[0.2222222222222222,"#7201a8"],[0.3333333333333333,"#9c179e"],[0.4444444444444444,"#bd3786"],[0.5555555555555556,"#d8576b"],[0.6666666666666666,"#ed7953"],[0.7777777777777778,"#fb9f3a"],[0.8888888888888888,"#fdca26"],[1.0,"#f0f921"]],"diverging":[[0,"#8e0152"],[0.1,"#c51b7d"],[0.2,"#de77ae"],[0.3,"#f1b6da"],[0.4,"#fde0ef"],[0.5,"#f7f7f7"],[0.6,"#e6f5d0"],[0.7,"#b8e186"],[0.8,"#7fbc41"],[0.9,"#4d9221"],[1,"#276419"]]},"xaxis":{"gridcolor":"white","linecolor":"white","ticks":"","title":{"standoff":15},"zerolinecolor":"white","automargin":true,"zerolinewidth":2},"yaxis":{"gridcolor":"white","linecolor":"white","ticks":"","title":{"standoff":15},"zerolinecolor":"white","automargin":true,"zerolinewidth":2},"scene":{"xaxis":{"backgroundcolor":"#E5ECF6","gridcolor":"white","linecolor":"white","showbackground":true,"ticks":"","zerolinecolor":"white","gridwidth":2},"yaxis":{"backgroundcolor":"#E5ECF6","gridcolor":"white","linecolor":"white","showbackground":true,"ticks":"","zerolinecolor":"white","gridwidth":2},"zaxis":{"backgroundcolor":"#E5ECF6","gridcolor":"white","linecolor":"white","showbackground":true,"ticks":"","zerolinecolor":"white","gridwidth":2}},"shapedefaults":{"line":{"color":"#2a3f5f"}},"annotationdefaults":{"arrowcolor":"#2a3f5f","arrowhead":0,"arrowwidth":1},"geo":{"bgcolor":"white","landcolor":"#E5ECF6","subunitcolor":"white","showland":true,"showlakes":true,"lakecolor":"white"},"title":{"x":0.05},"mapbox":{"style":"light"}}},"xaxis":{"anchor":"y","domain":[0.0,1.0],"title":{"text":"t"}},"yaxis":{"anchor":"x","domain":[0.0,1.0],"title":{"text":"cos(t)"}},"legend":{"tracegroupgap":0},"margin":{"t":60}}}

From Python macro (mass budget using SysML v2 and SysIDE)

Mass budget from model root

Source

{{ mass_budget("models/example_model_mass.sysml") }}

Result

Mass budget from given element

Source

{{ mass_budget("models/example_model_mass.sysml", "chassis") }}

Result

Tables

From inline Python

```python exec="on"
import itables
df = itables.sample_dfs.get_countries(html=False)
print(itables.to_html_datatable(df.head(15)))
```

Loading ITables v2.4.4 from the internet... (need help?)

Tip: use the itables python library to make pandas dataframes interactive, but you can also render dataframes to markdown:

```python exec="on"
import itables
df = itables.sample_dfs.get_countries(html=False)
print(df.head(3).to_markdown())
```

code	region	country	capital	longitude	latitude
AW	Latin America & Caribbean	Aruba	Oranjestad	-70.0167	12.5167
AF	South Asia	Afghanistan	Kabul	69.1761	34.5228
AO	Sub-Saharan Africa	Angola	Luanda	13.242	-8.81155

Markdown tables can also embed HTML, for instance:

```python exec="on"
import itables
df = itables.sample_dfs.get_countries(html=True)
print(df.head(3).to_markdown())
```

code	region	country	capital	longitude	latitude
AW	Latin America & Caribbean	Aruba	Oranjestad	-70.0167	12.5167
AF	South Asia	Afghanistan	Kabul	69.1761	34.5228
AO	Sub-Saharan Africa	Angola	Luanda	13.242	-8.81155

From Python macro (using SysML v2 and SysIDE)

Source

{{ sysml_req_table("models/reqs.sysml") }}

Result

Loading ITables v2.4.4 from the internet... (need help?)

From Inventree via Python macro

Default settings

Source

{{inventree_part(pk=3840)}}

Result

Name	Value
Manufacturer	Vishay
Name	100kR (FR293)
Description	Chip-resistor, 0402, 0.13W, ±0.1%, ±10ppm/°C
Image

Setting image size

Source

{{inventree_part(pk=3840, pic_width_per=20)}}

Result

Name	Value
Manufacturer	Vishay
Name	100kR (FR293)
Description	Chip-resistor, 0402, 0.13W, ±0.1%, ±10ppm/°C
Image

Hiding image

Source

{{inventree_part(pk=3840, pic_width_per=None)}}

Result

Name	Value
Manufacturer	Vishay
Name	100kR (FR293)
Description	Chip-resistor, 0402, 0.13W, ±0.1%, ±10ppm/°C

Inventree part parameters

Source

{{inventree_part(pk=3846)}}

Result

Name	Value
Manufacturer	Sodern
Name	Auriga
Description	Star tracker
Link	https://sodern.com/en/star-trackers/#auriga-en
Mass	0.225 kg
Image

Hiding Inventree part parameters

Source

{{inventree_part(pk=3846, with_part_params=False)}}

Result

Name	Value
Manufacturer	Sodern
Name	Auriga
Description	Star tracker
Link	https://sodern.com/en/star-trackers/#auriga-en
Image

Mermaid diagrams

Diagrams can be drawn from code using the mermaid library. Tip: use the live editor to write your mermaid diagrams, and then copy-paste your code here: https://mermaid.live/

Here's an example, but Mermaid has plenty more features:

```mermaid
graph TD
    A[Start] --> B{Is it?};
    B -->|Yes| C[OK];
    C --> D[Rethink];
    D --> B;
    B ---->|No| E[End];
```

graph TD
    A[Start] --> B{Is it?};
    B -->|Yes| C[OK];
    C --> D[Rethink];
    D --> B;
    B ---->|No| E[End];

Code docstring

It is possible to print code documentation and source code, for now only in Python using mkdocstrings, for instance:

::: mkdocs_tub.inventree.part_to_df

Describes an Inventree part as a pandas DataFrame.

Parameters:

Name	Type	Description	Default
`pk`	`int`	the Inventree part number to look for.	required
`with_part_params`	`bool`	if True, will also print all part parameters (Ref: https://docs.inventree.org/en/stable/part/parameter/)	`True`

Returns:

Type	Description
`DataFrame \| None`	a DataFrame containing the part description, or None if the part or the Inventree server were not found

Source code in src/mkdocs_tub/inventree.py

def part_to_df(pk: int, with_part_params: bool = True) -> pd.DataFrame | None:
    """Describes an Inventree part as a pandas DataFrame.
    :param pk: the Inventree part number to look for.
    :param with_part_params: if True, will also print all part parameters (Ref: https://docs.inventree.org/en/stable/part/parameter/)
    :return: a DataFrame containing the part description, or None if the part or the Inventree server were not found
    """
    if not api:
        return None
    part = Part(api, pk=pk)
    part_dict = part_description(api, part)
    if with_part_params:
        part_dict.update(get_all_part_params(part))
    return pd.DataFrame(part_dict, index=["Value"])

sphinx Python docstring style is expected, but this can be changed to other codestyles in mkdocstring's configuration in mkdocs.yml or locally in a ::: statement.

SysMLv2 Model Overview and other MkDocs tricks

Table of contents

Basics

LaTex

HTML attribute lists and image resizing

Interactive plots

From JSON data

From inline Python code

From Python macro (mass budget using SysML v2 and SysIDE)

Mass budget from model root

Mass budget from given element

Tables

From inline Python

From Python macro (using SysML v2 and SysIDE)

From Inventree via Python macro

Default settings

Setting image size

Hiding image

Inventree part parameters

Hiding Inventree part parameters

Mermaid diagrams

Code docstring