adjusted structure of navigation bar

dos-group · Oct 10, 2023 · 1987681 · 1987681
1 parent 31c8707
commit 1987681
Show file tree

Hide file tree

Showing 10 changed files with 237 additions and 71 deletions.
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -9,10 +9,9 @@ build:
   tools: 
     python: "3.8"
   commands:
-    - pip install poetry
+    - pip install poetry pdoc
     - poetry config virtualenvs.create false
     - poetry install --extras "sil analysis"
-    - pip install pdoc
-    - pdoc --docformat google -o docs/ vessim/ examples/cosim_example.py examples/sil_example.py 
+    - pdoc --docformat google --template-dir docs/custom/ -o docs/output/ vessim/ examples/cosim_example.py examples/sil_example.py docs/extra/About\ Vessim.py docs/extra/Concept.py docs/extra/Getting\ Started docs/extra/Installation.py
     - mkdir --parents $READTHEDOCS_OUTPUT/html/
-    - cp --recursive docs/* $READTHEDOCS_OUTPUT/html/
+    - cp --recursive docs/output/* $READTHEDOCS_OUTPUT/html/
diff --git a/docs/custom/custom.css b/docs/custom/custom.css
@@ -0,0 +1,4 @@
+/*
+This file is empty by default.
+Override it in your custom template to provide additional CSS rules.
+*/
diff --git a/docs/custom/module.html.jinja2 b/docs/custom/module.html.jinja2
@@ -0,0 +1,157 @@
+{% extends "default/module.html.jinja2" %}
+{% block title %}{{ module.modulename }} API documentation{% endblock %}
+{% block nav %}
+    {% block module_list_link %}
+        {% set parentmodule = ".".join(module.modulename.split(".")[:-1]) %}
+        {% if parentmodule and parentmodule in all_modules %}
+            <a class="pdoc-button module-list-button" href="../{{ parentmodule.split(".")[-1] }}.html">
+                {% include "resources/box-arrow-in-left.svg" %}
+                &nbsp;
+                {{- parentmodule -}}
+            </a>
+        {% elif not root_module_name %}
+            <a class="pdoc-button module-list-button" href="{{ "../" * module.modulename.count(".") }}vessim.html">
+                {% include "resources/box-arrow-in-left.svg" %}
+                &nbsp;
+                Overview
+            </a>
+        {% endif %}
+    {% endblock %}
+
+    {% block nav_title %}
+        {% if logo %}
+            {% if logo_link %}<a href="{{ logo_link }}">{% endif %}
+            <img src="{{ logo }}" class="logo" alt="project logo"/>
+            {% if logo_link %}</a>{% endif %}
+        {% endif %}
+    {% endblock %}
+
+    {% block search_box %}
+        {% if search and all_modules|length > 1 %}
+            {# we set a pattern here so that we can use the :valid CSS selector #}
+            <input type="search" placeholder="Search..." role="searchbox" aria-label="search"
+                   pattern=".+" required>
+        {% endif %}
+    {% endblock %}
+
+    {% block nav_index %}
+        {% set index = module.docstring | to_markdown | to_html | attr("toc_html") %}
+        {% if index %}
+            <h2><a href="vessim.html">Overview</a></h2>
+            {{ index | safe }}
+        {% endif %}
+    {% endblock %}
+
+    {% block nav_submodules %}
+            {% if module.submodules %}
+                <h2>Intro to Vessim</h2>
+                    <ul>
+                        <li><a href="Concept.html">Concept</a></li>
+                        <li><a href="Installation.html">Installation</a></li>
+                        <li><a href="Getting Started.html">Getting Started</a></li>
+                    </ul>
+            {% endif %}
+            {% for submodule in module.submodules if is_public(submodule) | trim%}
+                    {% if submodule.name == "analysis" %}
+                        <h2>Utility Modules</h2>
+                        <ul>
+                            <li>{{ submodule.taken_from | link(text="Analysis") }}</li>
+                            {% for file in ['cosim_example', 'sil_example'] %}
+                                <li><a href="{{ file }}.html">{{ file }}</a></li>
+                            {% endfor %}
+                        </ul>
+                    {% elif submodule.name == "cosim" %}
+                        <h2><a href="cosimulation.html">Co-simulation</a></h2>
+                    {% elif submodule.name == "sil" %}
+                        <h2><a href="softwareintheloop.html">Software-in-the-loop</a></h2>
+                    {% endif %}
+            {% endfor %}
+            {% if module.submodules %}
+                    <h2>API Documentation</h2>
+                    <ul>
+                        {% for submodule in module.submodules if is_public(submodule) | trim %}
+                            <li>{{ submodule.taken_from | link(text=submodule.name) }}</li>
+                        {% endfor %}
+                    </ul>
+                    <h2><a href="About Vessim.html">About Vessim</a></h2>
+            {% endif %}
+    {% endblock %}
+
+    {% block nav_members %}
+        {% if module.members %}
+            <h2>API Documentation</h2>
+            {{ nav_members(module.members.values()) }}
+        {% endif %}
+    {% endblock %}
+
+    {% block nav_footer %}
+        {% if footer_text %}
+            <footer>{{ footer_text }}</footer>
+        {% endif %}
+    {% endblock %}
+
+    {% block attribution %}
+        <a class="attribution" title="pdoc: Python API documentation generator" href="https://pdoc.dev" target="_blank">
+            built with <span class="visually-hidden">pdoc</span><img
+                alt="pdoc logo"
+                src="data:image/svg+xml,
+                        {%- filter urlencode %}{% include "resources/pdoc-logo.svg" %}{% endfilter %}"/>
+        </a>
+    {% endblock %}
+{% endblock nav %}
+{% block content %}
+    <main class="pdoc">
+        {% block module_info %}
+            <section class="module-info">
+                {% block edit_button %}
+                    {% if edit_url %}
+                        {% if "github.com" in edit_url %}
+                            {% set edit_text = "Edit on GitHub" %}
+                        {% elif "gitlab" in edit_url %}
+                            {% set edit_text = "Edit on GitLab" %}
+                        {% else %}
+                            {% set edit_text = "Edit Source" %}
+                        {% endif %}
+                        <a class="pdoc-button git-button" href="{{ edit_url }}">{{ edit_text }}</a>
+                    {% endif %}
+                {% endblock %}
+                {{ module_name() }}
+                {{ docstring(module) }}
+                {{ view_source_state(module) }}
+                {{ view_source_button(module) }}
+                {{ view_source_code(module) }}
+            </section>
+        {% endblock %}
+        {% block module_contents %}
+            {% for m in module.flattened_own_members if is_public(m) | trim %}
+                <section id="{{ m.qualname or m.name }}">
+                    {{ member(m) }}
+                    {% if m.kind == "class" %}
+                        {% for m in m.own_members if m.kind != "class" and is_public(m) | trim %}
+                            <div id="{{ m.qualname }}" class="classattr">
+                                {{ member(m) }}
+                            </div>
+                        {% endfor %}
+                        {% set inherited_members = inherited(m) | trim %}
+                        {% if inherited_members %}
+                            <div class="inherited">
+                                <h5>Inherited Members</h5>
+                                <dl>
+                                    {{ inherited_members }}
+                                </dl>
+                            </div>
+                        {% endif %}
+                    {% endif %}
+                </section>
+            {% endfor %}
+        {% endblock %}
+    </main>
+    {% if mtime %}
+        {% include "livereload.html.jinja2" %}
+    {% endif %}
+    {% block search_js %}
+        {% if search and all_modules|length > 1 %}
+            {% include "search.html.jinja2" %}
+        {% endif %}
+    {% endblock %}
+{% endblock content %}
diff --git a/docs/extra/About Vessim.py b/docs/extra/About Vessim.py
@@ -0,0 +1,11 @@
+"""
+## Publications
+
+- Philipp Wiesner, Ilja Behnke, and Odej Kao. "[A Testbed for Carbon-Aware Applications and Systems](https://arxiv.org/pdf/2306.09774.pdf)". arXiv:2302.08681 [cs.DC]. 2023.
+
+## Contact
+
+Vessim was developed at the research group for [Distributed and Operating Systems (DOS)](https://www.dos.tu-berlin.de), at TU Berlin.
+
+In case of questions, please reach out to [Philipp Wiesner](https://www.dos.tu-berlin.de/menue/people/wiesner_philipp/).
+"""
diff --git a/docs/extra/Concept.py b/docs/extra/Concept.py
@@ -0,0 +1,26 @@
+"""
+## What can I do with it?
+
+Vessim allows users to test real applications within a co-simulation testbed composed of domain-specific simulators on energy system components.
+The following Figure shows the different aspects of carbon-aware systems that can be investigated through Vessim.
+
+<div style="text-align: center;">
+    <img src="pics/CarbonAware_vessim_Aspects.png" alt="Carbon Aware Vessim Aspects" width="700">
+</div>
+As depicted in the above Figure, Vessim enables research on various aspects related to the interplay of energy and computing systems.
+
+- **Energy system composition**: Examine how integrating components like solar panels affects computing systems. Evaluate requirements for energy-autonomous data centers and potential impacts of future technologies.
+- **Energy system abstractions**: Vessim simplifies microgrid complexities through simulation, focusing on safety and carbon-aware applications while virtualizing energy systems.
+- **Energy system interfaces**: Investigate integration of new components, handling external data, and ensuring secure, controlled access across geo-distributed systems.
+- **Carbon-aware applications**: Vessim allows rapid prototyping of carbon-aware computing ideas, offering access to current standards and promoting common dataset use.
+
+Besides facilitating research, Vessim can support the development and quality assurance of carbon-aware applications and systems. 
+For example, it can be applied in continuous integration testing, or used to validate software roll-outs in a controlled environment.
+Additionally, using Vessim as a digital twin, carbon-aware datacenters can predict future system states, aid decision-making, and assess risks during extreme events like power outages.
+
+
+## How does it work?
+<div style="text-align: center;">
+    <img src="pics/Experiment_SiL_Design.png" alt="Experiment SiL Design" width="700">
+</div>
+"""
diff --git a/docs/extra/Getting Started.py b/docs/extra/Getting Started.py
@@ -0,0 +1,16 @@
+"""
+## 🚀
+
+To ease your start with Vessim, we provide two examples:
+
+### cosim_example
+
+The [cosim_example](https://github.com/dos-group/vessim/blob/main/examples/cosim_example.py) runs a fully simulated example scenario over the course of two days.
+See `cosim_example` for more details.
+
+### sil_example
+
+The [sil_example](https://github.com/dos-group/vessim/blob/main/examples/sil_example.py) is a co-simulation example with software-in-the-loop. 
+This scenario builds on cosim_example.py but connects to a real computing system through software-in-the-loop integration. This example is experimental and documentation is still in progress.
+See `sil_example` for more details.
+"""
diff --git a/docs/extra/Installation.py b/docs/extra/Installation.py
@@ -0,0 +1,17 @@
+"""
+## ⚙️
+
+If you are using Vessim for the first time, we recommend to clone and install this repository, so you have all code and examples at hand:
+
+```
+$ pip install -e .
+```
+
+
+Alternatively, you can also install our [latest release](https://pypi.org/project/vessim/)
+via [pip](https://pip.pypa.io/en/stable/quickstart/):
+
+```
+$ pip install vessim
+```
+"""
diff --git a/docs/pics/CarbonAware_vessim_Aspects.png → ...utput/pics/CarbonAware_vessim_Aspects.png b/docs/pics/CarbonAware_vessim_Aspects.png → ...utput/pics/CarbonAware_vessim_Aspects.png
diff --git a/docs/pics/Experiment_SiL_Design.png → docs/output/pics/Experiment_SiL_Design.png b/docs/pics/Experiment_SiL_Design.png → docs/output/pics/Experiment_SiL_Design.png
diff --git a/vessim/__init__.py b/vessim/__init__.py
@@ -1,77 +1,13 @@
 """
-## What is vessim?
-
 Vessim is a versatile **co-simulation testbed for carbon-aware applications and systems**. 
 It lets users connect domain-specific simulators for energy system components such as renewable power generation, energy storage, and power flow analysis with real software and hardware.
 It is based on [mosaik](https://mosaik.offis.de/), a general-purpose co-simulation framework.
 Mosaik connects simulators of any language and real systems via TCP and ensures their synchronization. It also offers an API for defining simulation scenarios. 
 
 Vessim is in alpha stage and under active development. Functionality and documentation will improve in the next weeks and months.
 
-## What can I do with it?
-
-Vessim allows users to test real applications within a co-simulation testbed composed of domain-specific simulators on energy system components.
-The following Figure shows the different aspects of carbon-aware systems that can be investigated through Vessim.
-
-<div style="text-align: center;">
-    <img src="pics/CarbonAware_vessim_Aspects.png" alt="Carbon Aware Vessim Aspects" width="700">
-</div>
-As depicted in the above Figure, Vessim enables research on various aspects related to the interplay of energy and computing systems.
-
-- **Energy system composition**: Examine how integrating components like solar panels affects computing systems. Evaluate requirements for energy-autonomous data centers and potential impacts of future technologies.
-- **Energy system abstractions**: Vessim simplifies microgrid complexities through simulation, focusing on safety and carbon-aware applications while virtualizing energy systems.
-- **Energy system interfaces**: Investigate integration of new components, handling external data, and ensuring secure, controlled access across geo-distributed systems.
-- **Carbon-aware applications**: Vessim allows rapid prototyping of carbon-aware computing ideas, offering access to current standards and promoting common dataset use.
-
-Besides facilitating research, Vessim can support the development and quality assurance of carbon-aware applications and systems. 
-For example, it can be applied in continuous integration testing, or used to validate software roll-outs in a controlled environment.
-Additionally, using Vessim as a digital twin, carbon-aware datacenters can predict future system states, aid decision-making, and assess risks during extreme events like power outages.
-
-## How does it work?
-<div style="text-align: center;">
-    <img src="pics/Experiment_SiL_Design.png" alt="Experiment SiL Design" width="700">
-</div>
-
-## ⚙️ Installation
-
-If you are using Vessim for the first time, we recommend to clone and install this repository, so you have all code and examples at hand:
-
-```
-$ pip install -e .
-```
-
-
-Alternatively, you can also install our [latest release](https://pypi.org/project/vessim/)
-via [pip](https://pip.pypa.io/en/stable/quickstart/):
-
-```
-$ pip install vessim
-```
-
-
-## 🚀 Getting started
-
-To ease your start with Vessim, we provide two examples:
-
-### cosim_example
-
-The [cosim_example](https://github.com/dos-group/vessim/blob/main/examples/cosim_example.py) runs a fully simulated example scenario over the course of two days.
-See `cosim_example` for more details.
-
-### sil_example
-
-The [sil_example](https://github.com/dos-group/vessim/blob/main/examples/sil_example.py) is a co-simulation example with software-in-the-loop. 
-This scenario builds on cosim_example.py but connects to a real computing system through software-in-the-loop integration. This example is experimental and documentation is still in progress.
-See `sil_example` for more details.
-
-
-## Publications
-
-- Philipp Wiesner, Ilja Behnke, and Odej Kao. "[A Testbed for Carbon-Aware Applications and Systems](https://arxiv.org/pdf/2306.09774.pdf)". arXiv:2302.08681 [cs.DC]. 2023.
-
-## Contact
-
-Vessim was developed at the research group for [Distributed and Operating Systems (DOS)](https://www.dos.tu-berlin.de), at TU Berlin.
+**Getting started with Vessim**
+ - 
+ - 
 
-In case of questions, please reach out to [Philipp Wiesner](https://www.dos.tu-berlin.de/menue/people/wiesner_philipp/).
 """