Set up docs folder and packaging

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 California Institute of Technology
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,6 +1,8 @@
 # pymerlin
 
+<!-- start elevator-pitch -->
 A python modeling framework for Aerie.
+<!-- end elevator-pitch -->
 
 ### TODO:
 
@@ -49,7 +51,7 @@ hybrid system, which may be more difficult to characterize.
 ## Building pymerlin.jar
 
 ```shell
-cd java
+cd pymerlin-java
 ./gradlew assemble
-mv pymerlin/build/libs/pymerlin.jar ..
+mv pymerlin/build/libs/pymerlin.jar ../pymerlin/_internal/jars
 ```

demo/model.py

@@ -1,4 +1,4 @@
-from pymerlin.decorators import MissionModel
+from pymerlin import MissionModel
 from pymerlin.model_actions import delay, wait_until, spawn
 
 

docs/0_quickstart.md

@@ -0,0 +1,20 @@
+# Quickstart
+
+This section describes how to get started with `pymerlin` 🎉
+
+## Installation
+
+First, make sure you have Java 21 JRE and python 12 installed on your machine.
+
+- Java: https://adoptium.net/temurin/releases/
+- Python: https://www.python.org/downloads/release/python-3120/
+
+Once those are ready, make a [python virtual environment](https://docs.python.org/3/library/venv.html) for your project
+
+After activating that environment, install `pymerlin` with the following command:
+
+```shell
+pip install pymerlin
+```
+
+

docs/1_tutorials/1_gettingstarted.md

@@ -0,0 +1,3 @@
+# Getting Started
+
+This is a tutorial

docs/1_tutorials/index.md

@@ -0,0 +1,8 @@
+# Tutorials
+
+```{toctree}
+:hidden:
+
+1_gettingstarted
+tutorial2
+```

docs/1_tutorials/tutorial2.md

@@ -0,0 +1,3 @@
+# Going further
+
+This is a tutorial

docs/2_guides/datamodel.md

@@ -0,0 +1,3 @@
+# Modeling Data Volume
+
+This is a tutorial

docs/2_guides/index.md

@@ -0,0 +1,10 @@
+# Guides
+
+```{toctree}
+:hidden:
+
+jupyter
+datamodel
+powermodel
+telecom
+```

docs/2_guides/jupyter.md

@@ -0,0 +1,3 @@
+# How to use pymerlin in Jupyter
+
+This is a tutorial

docs/2_guides/powermodel.md

@@ -0,0 +1,3 @@
+# Modeling Power
+
+This is a tutorial

docs/2_guides/telecom.md

@@ -0,0 +1,3 @@
+# Modeling Telecom
+
+This is a tutorial

docs/3_explanation/fidelity.md

@@ -0,0 +1,4 @@
+# Tuning Fidelity
+
+pymerlin (and Aerie's) strength is its ability to compose several subsystem models and observe behavior of the
+integrated system. It is not necessarily the best tool for detailed modeling of individual subsystems.

docs/3_explanation/index.md

@@ -0,0 +1,8 @@
+# Background
+Here, you can learn more about some of the theory of simulation, planning, and simulation.
+
+```{toctree}
+simulation
+planning
+fidelity
+```

docs/3_explanation/planning.md

@@ -0,0 +1,3 @@
+# Planning and Scheduling
+
+This is a tutorial

docs/3_explanation/simulation.md

@@ -0,0 +1,3 @@
+# Discrete Event Simulation
+
+This is a tutorial

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS ?=
+SPHINXBUILD ?= sphinx-build
+SOURCEDIR = .
+BUILDDIR = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+ @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+ @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_templates/custom-class-template.rst

@@ -0,0 +1,32 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+ :members: <-- add at least this line
+ :show-inheritance: <-- plus I want to show inheritance...
+ :inherited-members: <-- ...and inherited members too
+
+ {% block methods %}
+ .. automethod:: __init__
+
+ {% if methods %}
+ .. rubric:: {{ _('Methods') }}
+
+ .. autosummary::
+ {% for item in methods %}
+ ~{{ name }}.{{ item }}
+ {%- endfor %}
+ {% endif %}
+ {% endblock %}
+
+ {% block attributes %}
+ {% if attributes %}
+ .. rubric:: {{ _('Attributes') }}
+
+ .. autosummary::
+ {% for item in attributes %}
+ ~{{ name }}.{{ item }}
+ {%- endfor %}
+ {% endif %}
+ {% endblock %}

docs/_templates/custom-module-template.rst

@@ -0,0 +1,66 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+ {% block attributes %}
+ {% if attributes %}
+ .. rubric:: Module Attributes
+
+ .. autosummary::
+ :toctree: <-- add this line
+ {% for item in attributes %}
+ {{ item }}
+ {%- endfor %}
+ {% endif %}
+ {% endblock %}
+
+ {% block functions %}
+ {% if functions %}
+ .. rubric:: {{ _('Functions') }}
+
+ .. autosummary::
+ :toctree: <-- add this line
+ {% for item in functions %}
+ {{ item }}
+ {%- endfor %}
+ {% endif %}
+ {% endblock %}
+
+ {% block classes %}
+ {% if classes %}
+ .. rubric:: {{ _('Classes') }}
+
+ .. autosummary::
+ :toctree: <-- add this line
+ :template: custom-class-template.rst <-- add this line
+ {% for item in classes %}
+ {{ item }}
+ {%- endfor %}
+ {% endif %}
+ {% endblock %}
+
+ {% block exceptions %}
+ {% if exceptions %}
+ .. rubric:: {{ _('Exceptions') }}
+
+ .. autosummary::
+ :toctree: <-- add this line
+ {% for item in exceptions %}
+ {{ item }}
+ {%- endfor %}
+ {% endif %}
+ {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+ :toctree:
+ :template: custom-module-template.rst <-- add this line
+ :recursive:
+{% for item in modules %}
+ {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

docs/apidocs/index.rst

@@ -0,0 +1,10 @@
+
+API Reference
+=============
+
+Here, you can find the details of functions, classes, and data structures provided by the `pymerlin` package.
+
+.. toctree::
+ :titlesonly:
+
+ pymerlin/pymerlin