From: Martin Quinson Date: Sat, 2 Nov 2019 14:38:50 +0000 (+0100) Subject: better factorization of how examples are displayed in RST X-Git-Tag: v3.25~466 X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/7d486d1d3b2c9c2c5d286e1d49c27453a382ce9e better factorization of how examples are displayed in RST --- diff --git a/docs/source/_ext/showfile.py b/docs/source/_ext/showfile.py new file mode 100644 index 0000000000..a75fb17d7f --- /dev/null +++ b/docs/source/_ext/showfile.py @@ -0,0 +1,53 @@ +# -*- coding: utf-8 -*- + +import os +from docutils.parsers.rst import Directive, directives +from docutils import nodes +from docutils.statemachine import StringList +from sphinx.util.osutil import copyfile +from sphinx.util import logging + +class ShowFileDirective(Directive): + """ + Show a file or propose it to download. + """ + + has_content = False + optional_arguments = 1 + option_spec = { + 'language': directives.unchanged + } + + def run(self): +# self.assert_has_content() + + filename = self.arguments[0] + language = "python" + if 'language' in self.options: + language = self.options['language'] + + logger = logging.getLogger(__name__) +# logger.info('showfile {} in {}'.format(filename, language)) + + new_content = [ + '.. toggle-header::', + ' :header: View {}'.format(filename), + '', + ' `Download {} `_'.format(os.path.basename(filename), filename), + '', + ' .. literalinclude:: ../../{}'.format(filename), + ' :language: {}'.format(language), + '' + ] + + for idx, line in enumerate(new_content): +# logger.info('{} {}'.format(idx,line)) + self.content.data.insert(idx, line) + self.content.items.insert(idx, (None, idx)) + + node = nodes.container() + self.state.nested_parse(self.content, self.content_offset, node) + return node.children + +def setup(app): + app.add_directive('showfile', ShowFileDirective) diff --git a/docs/source/conf.py b/docs/source/conf.py index 2e977590cb..eb4687f619 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -58,7 +58,7 @@ extensions = [ 'sphinx_tabs.tabs', 'sphinxcontrib.contentui', 'javasphinx', - #'showfile', + 'showfile', ] todo_include_todos = True diff --git a/examples/s4u/README.rst b/examples/s4u/README.rst index c1ea3fe2e3..31f01a0f84 100644 --- a/examples/s4u/README.rst +++ b/examples/s4u/README.rst @@ -47,13 +47,8 @@ Starting and Stoping Actors 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 + .. showfile:: examples/s4u/actor-create/s4u-actor-create.cpp + :language: cpp .. group-tab:: Python @@ -62,24 +57,14 @@ Starting and Stoping Actors - 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 + .. showfile:: 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 + .. showfile:: 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 @@ -98,13 +83,8 @@ Starting and Stoping Actors - 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 + .. showfile:: examples/s4u/actor-exiting/s4u-actor-exiting.cpp + :language: cpp - **Kill actors:** Actors can forcefully stop other actors. @@ -115,24 +95,14 @@ Starting and Stoping Actors 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 + .. showfile:: 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 + .. showfile:: 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. @@ -143,25 +113,15 @@ Starting and Stoping Actors 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 + .. showfile:: 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 + .. showfile:: 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 @@ -173,24 +133,14 @@ Starting and Stoping Actors 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 + .. showfile:: 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 + .. showfile:: examples/python/actor-daemon/actor-daemon.py Inter-Actors Interactions ------------------------- @@ -201,7 +151,7 @@ synchronization objects `. - **Suspend and Resume actors:** Actors can be suspended and resumed during their executions. - + - |cpp| `examples/s4u/actor-suspend/s4u-actor-suspend.cpp `_ :cpp:func:`simgrid::s4u::this_actor::suspend()`, :cpp:func:`simgrid::s4u::Actor::suspend()`, :cpp:func:`simgrid::s4u::Actor::resume()`, :cpp:func:`simgrid::s4u::Actor::is_suspended()`. diff --git a/tools/cmake/DefinePackages.cmake b/tools/cmake/DefinePackages.cmake index c50a3de38a..12df120d75 100644 --- a/tools/cmake/DefinePackages.cmake +++ b/tools/cmake/DefinePackages.cmake @@ -874,6 +874,7 @@ set(DOC_SOURCES docs/source/conf.py docs/source/Doxyfile docs/source/_ext/hidden_code_block.py + docs/source/_ext/showfile.py docs/source/_templates/breadcrumbs.html docs/source/img/eclipseScreenShot.png