doc: new documentation

powerapi-ng · Oct 5, 2020 · 87f2be1 · 87f2be1
1 parent 2e49f00
commit 87f2be1
Show file tree

Hide file tree

Showing 7 changed files with 66 additions and 259 deletions.
diff --git a/docs/API.rst b/docs/API.rst
diff --git a/docs/Device_API.rst b/docs/Device_API.rst
diff --git a/docs/Handler_API.rst b/docs/Handler_API.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -17,7 +17,7 @@
 
 # -- Project information -----------------------------------------------------
 
-project = 'pyRAPL'
+project = 'pyJoules'
 copyright = '2019, INRIA, University of Lille'
 author = 'INRIA, University of Lille'
 

diff --git a/docs/generate.sh b/docs/generate.sh
@@ -1,13 +1,13 @@
 #!/bin/bash
 rm -R _build
-virtualenv ../venv
-source ../venv/bin/activate
-pip install sphinx
-pip install sphinx-autodoc-typehints
-pip install sphinx-rtd-theme
-pip install pymongo
-pip install pandas
+# virtualenv ./venv
+source ./venv/bin/activate
+# pip install sphinx
+# pip install sphinx-autodoc-typehints
+# pip install sphinx-rtd-theme
+# pip install pymongo
+# pip install pandas
 sphinx-build ./ _build/
 make html
 deactivate
-rm -R ../venv
+# rm -R ../venv
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,4 +1,4 @@
-.. pyRAPL documentation master file, created by
+.. pyJoules documentation master file, created by
    sphinx-quickstart on Tue Oct  8 14:16:48 2019.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
@@ -8,15 +8,7 @@
 
 Welcome to pyJoules's documentation!
 ************************************
-
-.. toctree::
-   :maxdepth: 3
-
-   quickstart
-   API
-   Device_API
-   Handler_API
-
+
 About
 =====
 
@@ -33,22 +25,62 @@ Limitation
 
 CPU, RAM and integrated GPU
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
-**pyJoules** uses the Intel "*Running Average Power Limit*" (RAPL) technology that estimates power consumption of the CPU, ram and integrated GPU.
+**pyJoules** uses the Intel "*Running Average Power Limit*" (RAPL) technology that estimates energy consumption of the CPU, ram and integrated GPU.
 This technology is available on Intel CPU since the `Sandy Bridge generation`__ (2010).
 
 __ https://fr.wikipedia.org/wiki/Intel#Historique_des_microprocesseurs_produits
 
+For the moment, **pyJoules** use the linux kernel API to get energy values reported by RAPL technology. That's why CPU, RAM and integrated GPU energy monitoring is not available on windows or MacOS.
+
+As RAPL is not provided by a virtual machine, **pyJoules** can't use it anymore to monitor energy consumption inside a virtual machine.
+
 Nvidia GPU
 ^^^^^^^^^^
 **pyJoules** uses the nvidia "*Nvidia Management Library*" technology to measure energy consumption of nvidia devices. The energy measurement API is only available on nvidia GPU with `Volta architecture`__ (2018)
 
 __ https://en.wikipedia.org/wiki/Volta_(microarchitecture)
+
+Monitor only function energy consumption
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+**pyjoules** monitor device energy consumption. The reported energy consumption is not only the energy consumption of the code you are running. This includes the *global energy consumption* of all the process running on the machine during this period, thus including the operating system and other applications.
+
+That is why we recommend to eliminate any extra programs that may alter the energy consumption of the machine hosting experiments and to keep only the code under measurement (*i.e.*, no extra applications, such as graphical interface, background running task...). This will give the closest measure to the real energy consumption of the measured code.
+
+Quickstart
+==========
+
+Installation
+------------
+
+You can install **pyRAPL** with pip : ``pip install pyRAPL``
+
+Decorate a function to measure its energy consumption
+-----------------------------------------------------
+
+To measure the energy consumed by the machine during the execution of the
+function ``foo()`` run the following code::
+
+To measure the energy consumed by the machine during the execution of the function ``foo()`` run the following code with the :raw-role:`<a href="API.html#pyJoules.energy_meter.measureit">` ``measureit`` :raw-role:`</a>` decorator:
+
+.. code-block:: python
+
+   from pyJoules.energy_meter import measureit
+
+   @measureit
+   def foo():
+       # Instructions to be evaluated.
+
+   foo()
+
+
+This will print in the console the recorded energy consumption of all the monitorable devices during the execution of function ``foo``.
+
 
 
 Miscellaneous
 =============
 
-PyRAPL is an open-source project developed by the `Spirals research group`__ (University of Lille and Inria) that take part of the Powerapi_ initiative.
+PyJoules is an open-source project developed by the `Spirals research group`__ (University of Lille and Inria) that take part of the Powerapi_ initiative.
 
 .. _Powerapi: http://powerapi.org
 
@@ -67,3 +99,16 @@ Contributing
 If you would like to contribute code you can do so via GitHub by forking the repository and sending a pull request.
 
 When submitting code, please make every effort to follow existing coding conventions and style in order to keep the code as readable as possible.
+
+
+Table of contents
+=================
+
+.. toctree::
+   :maxdepth: 2
+
+   About <self>
+   usages/usage
+   handlers/handlers
+   devices/devices
+   API/API.rst
diff --git a/docs/quickstart.rst b/docs/quickstart.rst