From ac7f10a514b4dd21e9a4330e819876dd105d2690 Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Fri, 28 Dec 2018 01:32:10 +0100 Subject: [PATCH] python: improve the documentation --- docs/Build.sh | 2 +- docs/source/app_s4u.rst | 39 ++++++++++++++++++++-- docs/source/conf.py | 6 +++- examples/python/exec-basic/exec-basic.py | 8 +++-- examples/python/exec-basic/exec-basic.tesh | 2 +- include/simgrid/s4u/Actor.hpp | 4 +-- src/bindings/python/simgrid_python.cpp | 39 ++++++++++++---------- 7 files changed, 73 insertions(+), 27 deletions(-) diff --git a/docs/Build.sh b/docs/Build.sh index 492bce5877..c7bfa41158 100755 --- a/docs/Build.sh +++ b/docs/Build.sh @@ -28,7 +28,7 @@ else echo "javasphinx relaunched" fi -sphinx-build -M html source build ${SPHINXOPTS} +PYTHONPATH=../lib sphinx-build -M html source build ${SPHINXOPTS} set +x diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst index 8edf721888..f170e383e2 100644 --- 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 -API Reference -************* +API C++ Reference +***************** .. _API_s4u_this_actor: @@ -573,3 +573,38 @@ s4u::VirtualMachine :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 74a792865d..06c756a6a8 100644 --- 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 -release = u'3.21' +release = u'alpha 3.22' # -- General configuration --------------------------------------------------- @@ -53,6 +53,10 @@ extensions = [ 'sphinx.ext.todo', 'breathe', # 'exhale', + 'sphinx.ext.autodoc', + 'sphinx.ext.intersphinx', +# 'sphinx.ext.napoleon', + 'sphinx.ext.autosummary', 'hidden_code_block', 'javasphinx', ] diff --git a/examples/python/exec-basic/exec-basic.py b/examples/python/exec-basic/exec-basic.py index 0d609653d3..c5719c6cbf 100644 --- 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. -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]) -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 diff --git a/examples/python/exec-basic/exec-basic.tesh b/examples/python/exec-basic/exec-basic.tesh index 07e77b9633..ce25f09b9d 100644 --- 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 -$ 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. diff --git a/include/simgrid/s4u/Actor.hpp b/include/simgrid/s4u/Actor.hpp index 3167cfd973..2be0ba3c31 100644 --- a/include/simgrid/s4u/Actor.hpp +++ b/include/simgrid/s4u/Actor.hpp @@ -403,10 +403,10 @@ template inline void sleep_until(const SimulationTimePoint(&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(&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 */ - py::class_(m, "Engine") + py::class_(m, "Engine", "Simulation Engine, see :ref:`class s4u::Engine `") .def(py::init([](std::vector 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()); })) - .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)> f) { simgrid::simix::register_function(name, [f](std::vector 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_>(m, "Host").def( + /* Class Host */ + py::class_>(m, "Host", "Simulation Engine, see :ref:`class s4u::Host `").def( "by_name", &Host::by_name, "Retrieve a host from its name, or die"); - py::class_(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) = &Actor::create; - m.def("create_actor", create_actor, "Create an actor"); - m.def("create_actor", [](std::string name, Host* host) -> std::function)> { - return [name, host](std::function f) -> ActorPtr { - return simgrid::s4u::Actor::create(name, host, std::move(f)); - }; - }, "Create an actor"); + py::class_(m, "Actor", "" + "An actor is an independent stream of execution in your distributed application, see :ref:`class 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)> { + return [name, host](std::function f) -> ActorPtr { + return simgrid::s4u::Actor::create(name, host, std::move(f)); + }; + }, "Create an actor from a functor"); + + } -- 2.20.1