Skip to content

Commit 2f41e4d

Browse files
codie3611codie3611
authored
refactor: migrate from sphinx to mkdocs
* migrate docs * fix video stuff * update README * add changelog and coverage to docs
1 parent afe9fbf commit 2f41e4d

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

82 files changed

+2761
-1825
lines changed

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,3 +71,6 @@ venv.bak/
7171
#*.so
7272
*.dylib
7373
*.dll
74+
75+
# Ignore generated changelog
76+
CHANGELOG.md

‎.markdownlint.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# There are different style types for markdown code blocks and strangely
2+
# indentation is the default. We change it here to the more often used 'fenced'
3+
# style denoted by ```
4+
MD046:
5+
style: fenced

‎README.rst‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -19,17 +19,19 @@ The library is now maintained by an open-source community.
1919
Module Overview:
2020
- `lasso.dyna`_
2121
- `lasso.dimred`_
22+
- `lasso.femzip`_
2223
- `lasso.diffcrash`_
2324

2425
For further infos please read the Documentation:
2526

2627
|DOCS| `Documentation`_
2728

2829
.. _LASSO GmbH: https://www.lasso.de/en
29-
.. _Documentation: https://open-lasso-python.github.io/lasso-python/build/html/index.html
30-
.. _lasso.dyna: https://open-lasso-python.github.io/lasso-python/build/html/dyna/dyna.html
31-
.. _lasso.diffcrash: https://open-lasso-python.github.io/lasso-python/build/html/diffcrash/diffcrash.html
32-
.. _lasso.dimred: https://lasso-gmbh.github.io/lasso-python/build/html/dimred/dimred.html
30+
.. _Documentation: https://open-lasso-python.github.io/lasso-python/
31+
.. _lasso.dyna: https://open-lasso-python.github.io/lasso-python/dyna/
32+
.. _lasso.dimred: https://open-lasso-python.github.io/lasso-python/diffcrash/diffcrash/
33+
.. _lasso.femzip: https://open-lasso-python.github.io/lasso-python/femzip/
34+
.. _lasso.diffcrash: https://open-lasso-python.github.io/lasso-python/diffcrash/diffcrash/
3335

3436

3537
Installation
@@ -47,14 +49,13 @@ Join our open-source community on:
4749

4850
|DISCORD| `Discord`_
4951

50-
.. _Docspage: https://open-lasso-python.github.io/lasso-python/build/html/index.html
5152
.. _Discord: https://discord.gg/jYUgTsEWtN
5253

53-
.. |LASSO| image:: ./docs/images/lasso-logo.png
54+
.. |LASSO| image:: ./docs/lasso-logo.png
5455
:target: https://open-lasso-python.github.io/lasso-python/build/html/index.html
55-
.. |DOCS| image:: ./docs/images/icon-home.png
56+
.. |DOCS| image:: ./docs/icon-home.png
5657
:target: https://open-lasso-python.github.io/lasso-python/build/html/index.html
57-
.. |DISCORD| image:: ./docs/images/icon-discord.png
58+
.. |DISCORD| image:: ./docs/icon-discord.png
5859
:target: https://discord.gg/GeHu79b
5960

6061

‎Taskfile.yml‎

Lines changed: 37 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,4 +37,40 @@ tasks:
3737
test:
3838
desc: Runs tests on the code
3939
cmds:
40-
- poetry run pytest
40+
- >
41+
poetry run pytest
42+
--cov=lasso
43+
--cov-report=html
44+
45+
docs:serve:
46+
desc: Serve the documentation locally for development and testing
47+
deps:
48+
- test
49+
- docs:changelog
50+
cmds:
51+
- poetry run mkdocs serve
52+
53+
docs:build:
54+
desc: Build the documentation
55+
deps:
56+
- test
57+
- docs:changelog
58+
cmds:
59+
- poetry run mkdocs build
60+
61+
docs:deploy:
62+
desc: Deploys the docs to GitHub (be careful!)
63+
deps:
64+
- test
65+
- docs:changelog
66+
cmds:
67+
- poetry run mkdocs gh-deploy
68+
69+
docs:changelog:
70+
desc: Generates the changelog
71+
cmds:
72+
- >
73+
poetry run git-changelog .
74+
--output CHANGELOG.md
75+
--style angular
76+
--template angular

‎docs/Makefile‎

Lines changed: 0 additions & 20 deletions
This file was deleted.

‎docs/changelog.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
--8<-- "./CHANGELOG.md"

‎docs/css/video.css‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
.video-wrapper {
2+
position: relative;
3+
display: block;
4+
height: 0;
5+
padding: 0;
6+
overflow: hidden;
7+
padding-bottom: 56.25%;
8+
}
9+
.video-wrapper > iframe {
10+
position: absolute;
11+
top: 0;
12+
bottom: 0;
13+
left: 0;
14+
width: 100%;
15+
height: 100%;
16+
border: 0;
17+
}

‎docs/diffcrash/diffcrash.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# lasso.diffcrash
2+
3+
This is the diffcrash module, which consists of a command line utility
4+
as well as a class for writing scripts.
5+
[Diffcrash] is a software from [Sidact] which is designed for robustness
6+
analysis of simulation runs.
7+
It can be used as a set of independent executables or as a postprocessor plugin.
8+
[Diffcrash] itself must be licensed.
9+
Please therefore contact [Sidact] directly.
10+
This module makes running a Diffcrash analysis much easier.
11+
12+
- Command Line Utility
13+
- Code
14+
15+
[diffcrash]: https://www.sidact.de/diffcrash
16+
[sidact]: https://www.sidact.de/

‎docs/diffcrash/diffcrash_run.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# DiffcrashRun
2+
3+
This class can be used in order to automate diffcrash runs in a hopefully
4+
comfortable manner.
5+
6+
::: lasso.diffcrash.DiffcrashRun

‎docs/diffcrash/run.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# Command Line Tool
2+
3+
## What is Diffcrash?
4+
5+
[Diffcrash] is a software from [Sidact] which is designed for robustness
6+
analysis of simulation runs.
7+
It can be used as a set of independent executables or as a postprocessor plugin.
8+
[Diffcrash] itself must be licensed.
9+
Please therefore contact [Sidact] directly.
10+
This commmand line utility makes running a Diffcrash analysis much
11+
easier.
12+
13+
[diffcrash]: https://www.sidact.de/diffcrash
14+
[sidact]: https://www.sidact.de/
15+
16+
## How to use the utility?
17+
18+
You can get the run info by performing:
19+
20+
```console
21+
$ python -m lasso.diffcrash.run --help
22+
23+
==== D I F F C R A S H ====
24+
25+
an open lasso utility script
26+
27+
usage: run.py [-h] --reference-run REFERENCE_RUN
28+
[--exclude-runs [EXCLUDE_RUNS [EXCLUDE_RUNS ...]]] --crash-code
29+
CRASH_CODE [--start-stage [START_STAGE]]
30+
[--end-stage [END_STAGE]] [--diffcrash-home [DIFFCRASH_HOME]]
31+
[--use-id-mapping [USE_ID_MAPPING]]
32+
[--project-dir [PROJECT_DIR]] [--config-file [CONFIG_FILE]]
33+
[--parameter-file [PARAMETER_FILE]]
34+
[--n-processes [N_PROCESSES]]
35+
[simulation_runs [simulation_runs ...]]
36+
37+
Python utility script for Diffcrash.
38+
39+
positional arguments:
40+
simulation_runs Simulation runs or patterns used to search for
41+
simulation runs.
42+
43+
optional arguments:
44+
-h, --help show this help message and exit
45+
--reference-run REFERENCE_RUN
46+
filepath of the reference run.
47+
--exclude-runs [EXCLUDE_RUNS [EXCLUDE_RUNS ...]]
48+
Runs to exclude from the analysis.
49+
--crash-code CRASH_CODE
50+
Which crash code is used ('dyna', 'pam' or 'radioss').
51+
--start-stage [START_STAGE]
52+
At which specific stage to start the analysis (SETUP,
53+
IMPORT, MATH, EXPORT, MATRIX, EIGEN, MERGE).
54+
--end-stage [END_STAGE]
55+
At which specific stage to stop the analysis (SETUP,
56+
IMPORT, MATH, EXPORT, MATRIX, EIGEN, MERGE).
57+
--diffcrash-home [DIFFCRASH_HOME]
58+
Home directory where Diffcrash is installed. Uses
59+
environment variable 'DIFFCRASHHOME' if unspecified.
60+
--use-id-mapping [USE_ID_MAPPING]
61+
Whether to use id-based mapping (default is nearest
62+
neighbour).
63+
--project-dir [PROJECT_DIR]
64+
Project dir to use for femzip.
65+
--config-file [CONFIG_FILE]
66+
Path to the config file.
67+
--parameter-file [PARAMETER_FILE]
68+
Path to the parameter file.
69+
--n-processes [N_PROCESSES]
70+
Number of processes to use (default: max-1).
71+
```
72+
73+
It is important to specify a `--reference-run` for the
74+
analysis. If the reference run is contained within the rest of the
75+
`simulation_runs`, it is automatically removed from that
76+
list. `simulation_runs` can be either tagged individually
77+
or by using placeholders for entire directories (e.g. '\*.fz') and
78+
subdirectories (e.g. '/\*\*/\*.fz').
79+
80+
!!! warning
81+
Every run clears the project directory entirely!
82+
83+
## Example
84+
85+
```console
86+
$ python -m lasso.diffcrash.run \
87+
$ --reference-run ./runs/run_1.fz \
88+
$ --crash-code dyna \
89+
$ --project-dir diffcrash_project \
90+
$ ./runs/*.fz
91+
92+
93+
==== D I F F C R A S H ====
94+
95+
an open lasso utility script
96+
97+
[/] diffcrash-home : /sw/Linux/diffcrash/V6.1.24
98+
[/] project-dir : test-example-project
99+
[/] crash-code : dyna
100+
[/] reference-run : bus/run_1.fz
101+
[/] use-id-mapping : False
102+
[/] # simul.-files : 37
103+
[/] # excluded files: 0
104+
[/] config-file : None
105+
[!] Config file missing. Consider specifying the path with the option '--config-file'.
106+
[/] parameter-file : None
107+
[!] Parameter file missing. Consider specifying the path with the option '--parameter-file'.
108+
[/] n-processes : 4
109+
110+
---- Running Routines ----
111+
112+
[✔] Running Setup ... done in 3.88s
113+
[✔] Running Imports ... done in 58.20s
114+
[✔] Running Math ... done in 56.22s
115+
[✔] Running Export ... done in 2.22s
116+
[✔] Running Matrix ... done in 9.78s
117+
[✔] Running Eigen ... done in 0.46s
118+
[✔] Running Merge ... done in 23.29s
119+
```

0 commit comments

Comments
 (0)