python: improve the documentation

diff --git a/docs/Build.sh b/docs/Build.sh
index 492bce5..c7bfa41 100755 (executable)
--- a/docs/Build.sh
+++ b/docs/Build.sh
@@ -28,7 +28,7 @@ else
   echo "javasphinx relaunched"
 fi
 
   echo "javasphinx relaunched"
 fi
 

-sphinx-build -M html source build ${SPHINXOPTS}
+PYTHONPATH=../lib sphinx-build -M html source build ${SPHINXOPTS}

 
 set +x
 
 
 set +x
 

diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst
index 8edf721..f170e38 100644 (file)
--- a/docs/source/app_s4u.rst
+++ b/docs/source/app_s4u.rst
@@ -365,8 +365,8 @@ Here is a little example:
   
    } // The mutex gets automatically freed because the only existing reference gets out of scope
 
   
    } // The mutex gets automatically freed because the only existing reference gets out of scope
 

-API Reference
-*************
+API C++ Reference
+*****************

 
 .. _API_s4u_this_actor:
 
 
 .. _API_s4u_this_actor:
 


@@ -573,3 +573,38 @@ s4u::VirtualMachine
    :protected-members:
    :undoc-members:
 
    :protected-members:
    :undoc-members:
 

+
+Python API Reference
+********************
+
+The Python API is generated with pybind11. It closely mimicks the C++
+API, to which you should refer for more information.
+
+=========
+Functions
+=========
+
+.. automodule:: simgrid
+   :members:
+   :exclude-members: Actor, Host, Engine
+
+===========
+Class Actor
+===========
+
+.. autoclass:: simgrid.Actor
+   :members:
+
+============
+Class Engine
+============
+
+.. autoclass:: simgrid.Engine
+   :members:
+
+==========
+Class Host
+==========
+
+.. autoclass:: simgrid.Host
+   :members:

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 74a7928..06c756a 100644 (file)
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -37,7 +37,7 @@ author = u'The SimGrid Team'
 # The short X.Y version
 version = u'alpha 3.22'
 # The full version, including alpha/beta/rc tags
 # The short X.Y version
 version = u'alpha 3.22'
 # The full version, including alpha/beta/rc tags

-release = u'3.21'
+release = u'alpha 3.22'

 
 
 # -- General configuration ---------------------------------------------------
 
 
 # -- General configuration ---------------------------------------------------


@@ -53,6 +53,10 @@ extensions = [
     'sphinx.ext.todo',
     'breathe',
 #    'exhale',
     'sphinx.ext.todo',
     'breathe',
 #    'exhale',

+    'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+#    'sphinx.ext.napoleon',
+    'sphinx.ext.autosummary',

     'hidden_code_block',
     'javasphinx',
 ]
     'hidden_code_block',
     'javasphinx',
 ]

diff --git a/examples/python/exec-basic/exec-basic.py b/examples/python/exec-basic/exec-basic.py
index 0d60965..c5719c6 100644 (file)
--- a/examples/python/exec-basic/exec-basic.py
+++ b/examples/python/exec-basic/exec-basic.py
@@ -29,11 +29,13 @@ def privileged():
     # After this point, the unprivileged one gets 100% of the CPU and finishes
     # quite quickly.
 
     # After this point, the unprivileged one gets 100% of the CPU and finishes
     # quite quickly.
 

-i = sys.argv.index("--")
+i = 0
+if "--" in sys.argv:
+    i = sys.argv.index("--")

 e = sg.Engine(sys.argv[0:i])
 e.load_platform(sys.argv[i+1])
 
 e = sg.Engine(sys.argv[0:i])
 e.load_platform(sys.argv[i+1])
 

-sg.create_actor("executor", sg.Host.by_name("Tremblay"), executor)
-sg.create_actor("privileged", sg.Host.by_name("Tremblay"), privileged)
+sg.Actor.create("executor", sg.Host.by_name("Tremblay"), executor)
+sg.Actor.create("privileged", sg.Host.by_name("Tremblay"), privileged)

 
 e.run()
\ No newline at end of file
 
 e.run()
\ No newline at end of file

diff --git a/examples/python/exec-basic/exec-basic.tesh b/examples/python/exec-basic/exec-basic.tesh
index 07e77b9..ce25f09 100644 (file)
--- a/examples/python/exec-basic/exec-basic.tesh
+++ b/examples/python/exec-basic/exec-basic.tesh
@@ -1,6 +1,6 @@
 #!/usr/bin/env tesh
 
 p Start remote processes 
 #!/usr/bin/env tesh
 
 p Start remote processes 

-$ python3 ${srcdir}/exec-basic.py -- ${platfdir}/small_platform.xml 
+$ python3 ${srcdir}/exec-basic.py ${platfdir}/small_platform.xml 

 > [Tremblay:privileged:(2) 0.001500] [python/INFO] Done.
 > [Tremblay:executor:(1) 0.002000] [python/INFO] Done.
 > [Tremblay:privileged:(2) 0.001500] [python/INFO] Done.
 > [Tremblay:executor:(1) 0.002000] [python/INFO] Done.

diff --git a/include/simgrid/s4u/Actor.hpp b/include/simgrid/s4u/Actor.hpp
index 3167cfd..2be0ba3 100644 (file)
--- a/include/simgrid/s4u/Actor.hpp
+++ b/include/simgrid/s4u/Actor.hpp
@@ -403,10 +403,10 @@ template <class Duration> inline void sleep_until(const SimulationTimePoint<Dura
   this_actor::sleep_until(timeout_native.time_since_epoch().count());
 }
 
   this_actor::sleep_until(timeout_native.time_since_epoch().count());
 }
 

-/** Block the actor, computing the given amount of flops */
+/** Block the current actor, computing the given amount of flops */

 XBT_PUBLIC void execute(double flop);
 
 XBT_PUBLIC void execute(double flop);
 

-/** Block the actor, computing the given amount of flops at the given priority.
+/** Block the current actor, computing the given amount of flops at the given priority.

  *  An execution of priority 2 computes twice as fast as an execution at priority 1. */
 XBT_PUBLIC void execute(double flop, double priority);
 
  *  An execution of priority 2 computes twice as fast as an execution at priority 1. */
 XBT_PUBLIC void execute(double flop, double priority);
 

diff --git a/src/bindings/python/simgrid_python.cpp b/src/bindings/python/simgrid_python.cpp
index b7ddd8f..52387a6 100644 (file)
--- a/src/bindings/python/simgrid_python.cpp
+++ b/src/bindings/python/simgrid_python.cpp
@@ -51,13 +51,13 @@ PYBIND11_MODULE(simgrid, m)
 
   /* this_actor namespace */
   m.def("execute", py::overload_cast<double>(&simgrid::s4u::this_actor::execute),
 
   /* this_actor namespace */
   m.def("execute", py::overload_cast<double>(&simgrid::s4u::this_actor::execute),

-        "Block the actor, computing the given amount of flops");
+        "Block the current actor, computing the given amount of flops, see :cpp:func:`void simgrid::s4u::this_actor::execute(double)`");

   m.def("execute", py::overload_cast<double, double>(&simgrid::s4u::this_actor::execute),
   m.def("execute", py::overload_cast<double, double>(&simgrid::s4u::this_actor::execute),

-        "Block the actor, computing the given amount of flops at the given priority");
-  m.def("yield_", &simgrid::s4u::this_actor::yield, "Yield the actor");
+        "Block the current actor, computing the given amount of flops at the given priority, see :cpp:func:`void simgrid::s4u::this_actor::execute(double, double)`");
+  m.def("yield_", &simgrid::s4u::this_actor::yield, "Yield the actor, see :cpp:func:`void simgrid::s4u::this_actor::yield()`");

 
   /* Class Engine */
 
   /* Class Engine */

-  py::class_<Engine>(m, "Engine")
+  py::class_<Engine>(m, "Engine", "Simulation Engine, see :ref:`class s4u::Engine <API_s4u_Engine>`")

       .def(py::init([](std::vector<std::string> args) -> simgrid::s4u::Engine* {
         static char noarg[] = {'\0'};
         int argc            = args.size();
       .def(py::init([](std::vector<std::string> args) -> simgrid::s4u::Engine* {
         static char noarg[] = {'\0'};
         int argc            = args.size();


@@ -68,29 +68,34 @@ PYBIND11_MODULE(simgrid, m)
         // Currently this can be dangling, we should wrap this somehow.
         return new simgrid::s4u::Engine(&argc, argv.get());
       }))
         // Currently this can be dangling, we should wrap this somehow.
         return new simgrid::s4u::Engine(&argc, argv.get());
       }))

-      .def("load_platform", &Engine::load_platform, "Load a platform file describing the environment")
-      .def("load_deployment", &Engine::load_deployment, "Load a deployment file and launch the actors that it contains")
+      .def("load_platform", &Engine::load_platform,
+          "Load a platform file describing the environment, see :cpp:func:`simgrid::s4u::Engine::load_platform()`")
+      .def("load_deployment", &Engine::load_deployment,
+          "Load a deployment file and launch the actors that it contains, see :cpp:func:`simgrid::s4u::Engine::load_deployment()`")

       .def("run", &Engine::run, "Run the simulation")
       .def("register_function", [](Engine*, std::string name, std::function<void(std::vector<std::string>)> f) {
         simgrid::simix::register_function(name,
             [f](std::vector<std::string> args) -> simgrid::simix::ActorCode {
           return [args, f]() { f(args); };
         });
       .def("run", &Engine::run, "Run the simulation")
       .def("register_function", [](Engine*, std::string name, std::function<void(std::vector<std::string>)> f) {
         simgrid::simix::register_function(name,
             [f](std::vector<std::string> args) -> simgrid::simix::ActorCode {
           return [args, f]() { f(args); };
         });

-      }, "Registers the main function of an actor that will be launched from the deployment file");
+      }, "Registers the main function of an actor that will be launched from the deployment file, , see :cpp:func:`simgrid::s4u::Engine::register_function()`");

 
 

-  // Currently, Host lead to segfault:
-  py::class_<simgrid::s4u::Host, std::unique_ptr<Host, py::nodelete>>(m, "Host").def(
+  /* Class Host */
+  py::class_<simgrid::s4u::Host, std::unique_ptr<Host, py::nodelete>>(m, "Host", "Simulation Engine, see :ref:`class s4u::Host <API_s4u_Host>`").def(

       "by_name", &Host::by_name, "Retrieve a host from its name, or die");
 
       "by_name", &Host::by_name, "Retrieve a host from its name, or die");
 

-  py::class_<simgrid::s4u::Actor, ActorPtr>(m, "Actor", "An actor is an independent stream of execution in your distributed application");
-
+  /* Class Actor */

   // Select the right template instantiation
   simgrid::s4u::ActorPtr (*create_actor)(std::string, Host*, std::function<void()>) = &Actor::create;
 
   // Select the right template instantiation
   simgrid::s4u::ActorPtr (*create_actor)(std::string, Host*, std::function<void()>) = &Actor::create;
 

-  m.def("create_actor", create_actor, "Create an actor");
-  m.def("create_actor", [](std::string name, Host* host) -> std::function<ActorPtr(std::function<void()>)> {
-    return [name, host](std::function<void()> f) -> ActorPtr {
-      return simgrid::s4u::Actor::create(name, host, std::move(f));
-    };
-  }, "Create an actor");
+  py::class_<simgrid::s4u::Actor, ActorPtr>(m, "Actor", ""
+      "An actor is an independent stream of execution in your distributed application, see :ref:`class s4u::Actor <API_s4u_Actor>`")
+    .def("create", create_actor, "Create an actor from a function, see :cpp:func:`simgrid::s4u::Actor::create()`")
+    .def("create", [](std::string name, Host* host) -> std::function<ActorPtr(std::function<void()>)> {
+      return [name, host](std::function<void()> f) -> ActorPtr {
+        return simgrid::s4u::Actor::create(name, host, std::move(f));
+      };
+    }, "Create an actor from a functor");
+
+

 }
 }