From 54aaefb7aa8fc6bfbdac47dfda2047989fb9b9f5 Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Sat, 2 Nov 2019 10:40:02 +0100 Subject: [PATCH] Cosmetics on how we present examples in C++ and python This both makes room for the upcoming C examples and paves the road for a better multilingual API documentation. The implementation is really crude, with the name of files repeated 4 times, but I fail to script sphinx so far. More to come, I guess. --- docs/Build.sh | 18 ++-- docs/requirements.txt | 2 + docs/source/conf.py | 4 +- examples/s4u/README.rst | 179 ++++++++++++++++++++++++++++++++-------- 4 files changed, 160 insertions(+), 43 deletions(-) diff --git a/docs/Build.sh b/docs/Build.sh index 7e1e60c201..3029454b8a 100755 --- a/docs/Build.sh +++ b/docs/Build.sh @@ -41,18 +41,18 @@ perl -pe 's/(xlink:href="(?:http|.*\.html))/target="_top" $1/' \ echo "List of missing references:" for f in $( (grep '' build/xml/msg_8h.xml; \ grep '' build/xml/namespacesimgrid_1_1s4u.xml; \ - grep '' build/xml/actor_8h.xml ; \ - grep '' build/xml/barrier_8h.xml ; \ +# grep '' build/xml/actor_8h.xml ; \ +# grep '' build/xml/barrier_8h.xml ; \ grep '' build/xml/cond_8h.xml ; \ grep '' build/xml/engine_8h.xml ; \ - grep '' build/xml/host_8h.xml ; \ - grep '' build/xml/link_8h.xml ; \ - grep '' build/xml/mailbox_8h.xml ; \ +# grep '' build/xml/host_8h.xml ; \ +# grep '' build/xml/link_8h.xml ; \ +# grep '' build/xml/mailbox_8h.xml ; \ grep '' build/xml/msg_8h.xml ; \ - grep '' build/xml/mutex_8h.xml ; \ - grep '' build/xml/semaphore_8h.xml ; \ - grep '' build/xml/vm_8h.xml ; \ - grep '' build/xml/zone_8h.xml ; \ +# grep '' build/xml/mutex_8h.xml ; \ +# grep '' build/xml/semaphore_8h.xml ; \ +# grep '' build/xml/vm_8h.xml ; \ +# grep '' build/xml/zone_8h.xml ; \ grep ']*>//g' | sort ) do diff --git a/docs/requirements.txt b/docs/requirements.txt index 0e101800fd..ecb036b906 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,4 +1,6 @@ breathe sphinx>=1.8.0 sphinx_rtd_theme +sphinx_tabs +sphinxcontrib.contentui javasphinx diff --git a/docs/source/conf.py b/docs/source/conf.py index a3cf0007be..2e977590cb 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -55,8 +55,10 @@ extensions = [ 'sphinx.ext.intersphinx', # 'sphinx.ext.napoleon', 'sphinx.ext.autosummary', - 'hidden_code_block', + 'sphinx_tabs.tabs', + 'sphinxcontrib.contentui', 'javasphinx', + #'showfile', ] todo_include_todos = True diff --git a/examples/s4u/README.rst b/examples/s4u/README.rst index e8bd8555df..c1ea3fe2e3 100644 --- a/examples/s4u/README.rst +++ b/examples/s4u/README.rst @@ -1,10 +1,5 @@ -.. S4U (Simgrid for you) is the next interface of SimGrid, expected to be released with SimGrid 4.0. +.. S4U (Simgrid for you) is the modern interface of SimGrid, which new project should use. .. -.. Even if it is not completely rock stable yet, it may well already fit -.. your needs. You are welcome to try it and report any interface -.. glitches that you see. Be however warned that the interface may change -.. until the final release. You will have to adapt your code on the way. -.. .. This file follows the ReStructured syntax to be included in the .. documentation, but it should remain readable directly. @@ -37,47 +32,165 @@ Starting and Stoping Actors --------------------------- - **Creating actors:** - Most actors are started from the deployment XML file, but there is other methods. - This example show them all. - `examples/python/actor-create/actor-create_d.xml `_ + Most actors are started from the deployment XML file, because this + is a :ref:`better scientific habbit `, but you can + also create them directly from your code. + + .. tabs:: + + .. group-tab:: C++ + + You create actors either: + + - Directly with :cpp:func:`simgrid::s4u::Actor::create` + - From XML with :cpp:func:`simgrid::s4u::Engine::register_actor` (if your actor is a class) + or :cpp:func:`simgrid::s4u::Engine::register_function` (if your actor is a function) + and then :cpp:func:`simgrid::s4u::Engine::load_deployment` + + .. toggle-header:: + :header: View examples/s4u/actor-create/s4u-actor-create.cpp + + `Download s4u-actor-create.cpp `_ + + .. literalinclude:: ../../examples/s4u/actor-create/s4u-actor-create.cpp + :language: cpp + + .. group-tab:: Python + + You create actors either: + + - Directly with :py:func:`simgrid.Actor.create()` + - From XML with :py:func:`simgrid.Engine.register_actor()` and then :py:func:`simgrid.Engine.load_deployment()` + + .. toggle-header:: + :header: View examples/python/actor-create/actor-create.py + + `Download actor-create.py `_ + + .. literalinclude:: ../../examples/python/actor-create/actor-create.py + + .. group-tab:: XML + + The following file is used in both C++ and Python. + + .. toggle-header:: + :header: View examples/python/actor-create/actor-create_d.xml + + `Download actor-create_d.xml `_ + + .. literalinclude:: ../../examples/python/actor-create/actor-create_d.xml + :language: xml + + - **React to the end of actors:** You can attach callbacks to the end of + actors. There is several ways of doing so, depending on whether you want to + attach your callback to a given actor and on how you define the end of a + given actor. User code probably want to react to the termination of an actor + while some plugins want to react to the destruction (memory collection) of + actors. + + .. tabs:: - - |cpp| `examples/s4u/actor-create/s4u-actor-create.cpp `_ - - |py| `examples/python/actor-create/actor-create.py `_ + .. group-tab:: C++ - - **React to the end of actors:** - You can attach a callback to the end of actors. There is two ways - of doing so, depending of whether you want your callback to be - executed when a specific actor ends (with ```this_actor::on_exit()```) - or whether it should be executed when any actor ends (with - ```Actor::on_termination()```) or when it gets destroyed (with - ```Actor::on_destruction()```) + This example shows how to attach a callback to: - - |cpp| `examples/s4u/actor-exiting/s4u-actor-exiting.cpp `_ + - the end of a specific actor: :cpp:func:`simgrid::s4u::this_actor::on_exit()` + - the end of any actor: :cpp:member:`simgrid::s4u::Actor::on_termination()` + - the destruction of any actor: :cpp:member:`simgrid::s4u::Actor::on_destruction()` + + .. toggle-header:: + :header: View examples/s4u/actor-exiting/s4u-actor-exiting.cpp + + `Download s4u-actor-exiting.cpp `_ + + .. literalinclude:: ../../examples/s4u/actor-exiting/s4u-actor-exiting.cpp + :language: cpp - **Kill actors:** Actors can forcefully stop other actors. - - |cpp| `examples/s4u/actor-kill/s4u-actor-kill.cpp `_ - :cpp:func:`void simgrid::s4u::Actor::kill(void)`, - :cpp:func:`void simgrid::s4u::Actor::kill_all()`, - :cpp:func:`simgrid::s4u::this_actor::exit`. - - |py| `examples/python/actor-kill/actor-kill.py `_ - :py:func:`simgrid.Actor.kill`, - :py:func:`simgrid.Actor.kill_all`, - :py:func:`simgrid.this_actor.exit`. + .. tabs:: + + .. group-tab:: C++ + + See also :cpp:func:`void simgrid::s4u::Actor::kill(void)`, :cpp:func:`void simgrid::s4u::Actor::kill_all()`, :cpp:func:`simgrid::s4u::this_actor::exit`. + + .. toggle-header:: + :header: View examples/s4u/actor-kill/s4u-actor-kill.cpp + + `Download s4u-actor-kill.cpp `_ + + .. literalinclude:: ../../examples/s4u/actor-kill/s4u-actor-kill.cpp + :language: cpp + + .. group-tab:: Python + + See also :py:func:`simgrid.Actor.kill`, :py:func:`simgrid.Actor.kill_all`, :py:func:`simgrid.this_actor.exit`. + + .. toggle-header:: + :header: View examples/python/actor-kill/actor-kill.py + + `Download actor-kill.py `_ + + .. literalinclude:: ../../examples/python/actor-kill/actor-kill.py - **Controling the actor life cycle from the XML:** - You can specify a start time and a kill time in the deployment - file. - |br| `examples/s4u/actor-lifetime/s4u-actor-lifetime.cpp `_ - |br| `examples/s4u/actor-lifetime/s4u-actor-lifetime_d.xml `_ + You can specify a start time and a kill time in the deployment file. + + .. tabs:: + + .. group-tab:: C++ + + This file is not really interesting: the important matter is in the XML file. + + .. toggle-header:: + :header: View examples/s4u/actor-lifetime/s4u-actor-lifetime.cpp + + `Download s4u-actor-lifetime.cpp `_ + + .. literalinclude:: ../../examples/s4u/actor-lifetime/s4u-actor-lifetime.cpp + :language: cpp + + .. group-tab:: XML + + This demonstrates the ``start_time`` and ``kill_time`` attribute of the :ref:`pf_tag_actor` tag. + + .. toggle-header:: + :header: View examples/s4u/actor-lifetime/s4u-actor-lifetime_d.xml + + `Download s4u-actor-lifetime_d.xml `_ + + .. literalinclude:: ../../examples/s4u/actor-lifetime/s4u-actor-lifetime_d.xml + :language: xml - **Daemonize actors:** Some actors may be intended to simulate daemons that run in background. This example show how to transform a regular actor into a daemon that will be automatically killed once the simulation is over. - - |cpp| `examples/s4u/actor-daemon/s4u-actor-daemon.cpp `_ - - |py| `examples/python/actor-daemon/actor-daemon.py `_ + .. tabs:: + + .. group-tab:: C++ + + See also :cpp:func:`simgrid::s4u::Actor::daemonize()` and :cpp:func:`simgrid::s4u::Actor::is_daemon()`. + + .. toggle-header:: + :header: View examples/s4u/actor-daemon/s4u-actor-daemon.cpp + + `Download s4u-actor-daemon.cpp `_ + + .. literalinclude:: ../../examples/s4u/actor-daemon/s4u-actor-daemon.cpp + :language: cpp + + .. group-tab:: Python + + See also :py:func:`simgrid.Actor.daemonize()` and :py:func:`simgrid.Actor.is_daemon()`. + + .. toggle-header:: + :header: View examples/python/actor-daemon/actor-daemon.py + + `Download actor-daemon.py `_ + + .. literalinclude:: ../../examples/python/actor-daemon/actor-daemon.py Inter-Actors Interactions ------------------------- -- 2.20.1