From 37c17634ea54f0a0f3fd1d09ee6e620f3d13747e Mon Sep 17 00:00:00 2001
From: Martin Quinson <martin.quinson@loria.fr>
Date: Mon, 6 Aug 2018 18:56:22 +0200
Subject: [PATCH] doc: current state of the future generation documentation

and try to rebuild it on framagit
---
 .gitlab-ci.yml                                |   8 ++-
 docs/source/conf.py                           |  20 +++++-
 docs/source/images/extlink.png                | Bin 0 -> 416 bytes
 docs/source/images/extlink.svg                |  62 ++++++++++++++++++
 docs/source/index.rst                         |  18 ++++-
 .../s4u-app-masterworkers-fun.cpp             |   6 ++
 6 files changed, 109 insertions(+), 5 deletions(-)
 create mode 100644 docs/source/images/extlink.png
 create mode 100644 docs/source/images/extlink.svg

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 1a005826f7..0085c43ae7 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -3,7 +3,13 @@ image: debian:testing-slim
 .build: &build
   script:
   - apt-get update
-  - apt-get install -y python3-sphinx doxygen python3-breathe python3-sphinx-rtd-theme
+  - apt-get install -y python3-sphinx doxygen python3-breathe python3-sphinx-rtd-theme pip3
+  - apt-get install -y cmake doxygen libboost-all-dev libboost-dev
+  - pip3 install --no-deps exhale
+  - cmake -Denable_documentation=ON .
+  - make documentation
+  - mkdir docs/doxyoutput
+  - mv doc/xml docs/doxyoutput
   - cd docs
   - sphinx-build -M html source/ build/
   - mv build/html ../public
diff --git a/docs/source/conf.py b/docs/source/conf.py
index ddca903e1a..e5bcf6c9b0 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -43,11 +43,27 @@ extensions = [
     'sphinx.ext.mathjax',
 #    'sphinx.ext.ifconfig',
     'breathe',
+    'exhale',
 ]
 
-breathe_projects = { 'simgrid': '../doc/xml' }
+breathe_projects = { 'simgrid': '../../doc/xml' }
 breathe_default_project = "simgrid"
- 
+
+# Setup the exhale extension
+exhale_args = {
+    # These arguments are required
+    "containmentFolder":     "./api",
+    "rootFileName":          "library_root.rst",
+    "rootFileTitle":         "SimGrid Full API",
+    "doxygenStripFromPath":  "..",
+    # Suggested optional arguments
+    "createTreeView":        True,
+    # TIP: if using the sphinx-bootstrap-theme, you need
+    # "treeViewIsBootstrap": True,
+    "exhaleExecutesDoxygen": True,
+    "exhaleDoxygenStdin":    "INPUT = ../../include"
+}
+
 # Add any paths that contain templates here, relative to this directory.
 # templates_path = ['_templates']
 
diff --git a/docs/source/images/extlink.png b/docs/source/images/extlink.png
new file mode 100644
index 0000000000000000000000000000000000000000..5cb5fa93f9912ba6f34e49cd935ae9e95ff64309
GIT binary patch
literal 416
zcmeAS@N?(olHy`uVBq!ia0vp^d?3uh0wlLOK8*rWEa{HEjtmSN`?>!lvI6-E$sR$z
z3=CCj3=9n|3=F@3LJcn%7)lKo7+xhXFj&oCU=S~uvn$XBD8ZEE?e4<xzrFv=ejty%
z#M9T6{T@3%tCZ-~8OM`=LMuF7977~7w_ecAa|#q_d)PkzO2H(lT|z8er_}^b=rLYh
zFmdYvDGtX40R^JdHZk~2ZgLj(bAA8N$@77<v2p&snP)yYEZyyQ)r~>>Ra)Jf&o>r6
zR_VId!@Gy8@`^x>>Ws`gJ-pKvwN5VmdH-0#y3{3WU;n=L^SRWn2(E|)+pB-nIqohA
zUAVA$WpQC`XvoP#6GqYJEXKC;SGst*PrD>8KPx=HXWOs7c`wB|zZxsO^lz^Rx>>cv
zHKHUXu_V<hxhNG#F&G&bTId=8ky(g=u@w**nrRytSs56dYEkz=(U6;;l9^Ts(qN)%
hV6JOu3esR?W@Tgu(crecBOR!L!PC{xWt~$(697(ak6{1+

literal 0
HcmV?d00001

diff --git a/docs/source/images/extlink.svg b/docs/source/images/extlink.svg
new file mode 100644
index 0000000000..f882e193bd
--- /dev/null
+++ b/docs/source/images/extlink.svg
@@ -0,0 +1,62 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Font Awesome by Dave Gandy - https://fortawesome.github.com/Font-Awesome 
+     [CC BY-SA 3.0 (https://creativecommons.org/licenses/by-sa/3.0)],
+     via Wikimedia Commons -->
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   viewBox="0 -256 1850 1850"
+   id="svg3025"
+   version="1.1"
+   inkscape:version="0.48.3.1 r9886"
+   width="100%"
+   height="100%"
+   sodipodi:docname="external_link_font_awesome.svg">
+  <metadata
+     id="metadata3035">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <defs
+     id="defs3033" />
+  <sodipodi:namedview
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1"
+     objecttolerance="10"
+     gridtolerance="10"
+     guidetolerance="10"
+     inkscape:pageopacity="0"
+     inkscape:pageshadow="2"
+     inkscape:window-width="640"
+     inkscape:window-height="480"
+     id="namedview3031"
+     showgrid="false"
+     inkscape:zoom="0.13169643"
+     inkscape:cx="896"
+     inkscape:cy="896"
+     inkscape:window-x="0"
+     inkscape:window-y="25"
+     inkscape:window-maximized="0"
+     inkscape:current-layer="svg3025" />
+  <g
+     transform="matrix(1,0,0,-1,30.372881,1426.9492)"
+     id="g3027">
+    <path
+       d="M 1408,608 V 288 Q 1408,169 1323.5,84.5 1239,0 1120,0 H 288 Q 169,0 84.5,84.5 0,169 0,288 v 832 Q 0,1239 84.5,1323.5 169,1408 288,1408 h 704 q 14,0 23,-9 9,-9 9,-23 v -64 q 0,-14 -9,-23 -9,-9 -23,-9 H 288 q -66,0 -113,-47 -47,-47 -47,-113 V 288 q 0,-66 47,-113 47,-47 113,-47 h 832 q 66,0 113,47 47,47 47,113 v 320 q 0,14 9,23 9,9 23,9 h 64 q 14,0 23,-9 9,-9 9,-23 z m 384,864 V 960 q 0,-26 -19,-45 -19,-19 -45,-19 -26,0 -45,19 L 1507,1091 855,439 q -10,-10 -23,-10 -13,0 -23,10 L 695,553 q -10,10 -10,23 0,13 10,23 l 652,652 -176,176 q -19,19 -19,45 0,26 19,45 19,19 45,19 h 512 q 26,0 45,-19 19,-19 19,-45 z"
+       id="path3029"
+       inkscape:connector-curvature="0"
+       style="fill:currentColor" />
+  </g>
+</svg>
diff --git a/docs/source/index.rst b/docs/source/index.rst
index f20d9aefee..9b50a14aeb 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -4,13 +4,27 @@ Welcome to SimGrid's documentation!
 ===================================
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+   :maxdepth: 1
+   :caption: Basic Use Cases:
+
+	Simulating Algorithms <usecase_algorithms.rst>
+	Simulating MPI Apps <usecase_mpi.rst>
+   
+.. toctree::
+   :maxdepth: 1
+   :caption: Getting Started:
 
 	What is SimGrid <main_concepts.rst>
 	Installing SimGrid <installation.rst>
 	Start your Own Project <install_yours.rst>
 
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: API Reference:
+
+	     API <api/library_root.rst>
+	     S4U <api/s4u.rst>
 
 Indices and tables
 ==================
diff --git a/examples/s4u/app-masterworkers/s4u-app-masterworkers-fun.cpp b/examples/s4u/app-masterworkers/s4u-app-masterworkers-fun.cpp
index c90c96557a..0cfae30d86 100644
--- a/examples/s4u/app-masterworkers/s4u-app-masterworkers-fun.cpp
+++ b/examples/s4u/app-masterworkers/s4u-app-masterworkers-fun.cpp
@@ -7,6 +7,7 @@
 
 XBT_LOG_NEW_DEFAULT_CATEGORY(s4u_app_masterworker, "Messages specific for this example");
 
+// master-begin
 static void master(std::vector<std::string> args)
 {
   xbt_assert(args.size() == 5, "The master function expects 4 arguments");
@@ -38,7 +39,9 @@ static void master(std::vector<std::string> args)
     mailbox->put(new double(-1.0), 0);
   }
 }
+// master-end
 
+// worker-begin
 static void worker(std::vector<std::string> args)
 {
   xbt_assert(args.size() == 2, "The worker expects a single argument");
@@ -60,7 +63,9 @@ static void worker(std::vector<std::string> args)
 
   XBT_INFO("Exiting now.");
 }
+// worker-end
 
+// main-begin
 int main(int argc, char* argv[])
 {
   simgrid::s4u::Engine e(&argc, argv);
@@ -81,3 +86,4 @@ int main(int argc, char* argv[])
 
   return 0;
 }
+// main-end
-- 
2.20.1