include the full Java API doc in sphinx

diff --git a/.gitignore b/.gitignore
index 29b9a4e..5032bee 100644 (file)
--- a/.gitignore
+++ b/.gitignore
@@ -66,6 +66,7 @@ build/
 *.bpr
 *.bpf
 ### Documentation
 *.bpr
 *.bpf
 ### Documentation

+docs/source/java

 docs/source/_ext/__pycache__/
 doc/allclasses-frame.html
 doc/allclasses-noframe.html
 docs/source/_ext/__pycache__/
 doc/allclasses-frame.html
 doc/allclasses-noframe.html

diff --git a/docs/Build.sh b/docs/Build.sh
index 9bc5a26..acdcd0a 100755 (executable)
--- a/docs/Build.sh
+++ b/docs/Build.sh
@@ -5,12 +5,22 @@
 set -e
 
 if [ "x$1" != 'xdoxy' -a -e build/xml ] ; then
 set -e
 
 if [ "x$1" != 'xdoxy' -a -e build/xml ] ; then

-  echo "(Doxygen not rerun)"
+  echo "Doxygen not rerun: 'doxy' was not provided as an argument"

 else
   rm -rf build/xml source/api/
   cd source; doxygen; cd ..
 fi
 
 else
   rm -rf build/xml source/api/
   cd source; doxygen; cd ..
 fi
 

+if [ "x$1" != 'xjava' -a -e source/java ] ; then
+  echo "javasphinx not rerun: 'java' was not provided as an argument"
+else
+  rm -rf source/java
+  javasphinx-apidoc --force -o source/java/ ../src/bindings/java/org/simgrid/msg
+  rm source/java/packages.rst # source/java/org/simgrid/msg/package-index.rst
+#  sed -i 's/^.. java:type:: public class /.. java:type:: public class org.simgrid.msg/' source/java/org/simgrid/msg/*
+  echo "javasphinx relaunched"
+fi
+

 sphinx-build -M html source build ${SPHINXOPTS}
 cat source/img/graphical-toc.svg \
  | perl -pe 's/(xlink:href="http)/target="_top" $1/' \
 sphinx-build -M html source build ${SPHINXOPTS}
 cat source/img/graphical-toc.svg \
  | perl -pe 's/(xlink:href="http)/target="_top" $1/' \


@@ -21,7 +31,8 @@ cat source/img/graphical-toc.svg \
 echo "List of missing references:"
 for f in `(grep '<name>' build/xml/msg_8h.xml; \
            grep '<name>' build/xml/namespacesimgrid_1_1s4u.xml; \
 echo "List of missing references:"
 for f in `(grep '<name>' build/xml/msg_8h.xml; \
            grep '<name>' build/xml/namespacesimgrid_1_1s4u.xml; \

-          grep '<innerclass refid=' build/xml/namespacesimgrid_1_1s4u.xml) |sed 's/<[^>]*>//g'|sort` 
+          grep '<innerclass refid=' build/xml/namespacesimgrid_1_1s4u.xml ; \
+          ) |sed 's/<[^>]*>//g'|sort` 

 do
 
   if grep $f source/*rst | grep -q '.. doxygen[^::]*:: '"$f"'$' ||
 do
 
   if grep $f source/*rst | grep -q '.. doxygen[^::]*:: '"$f"'$' ||

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 7a99a02..2c64af2 100644 (file)
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,5 +1,5 @@
 breathe
 breathe

-exhale
+javasphinx

 sphinx>=1.8.0
 sphinx_rtd_theme
 
 sphinx>=1.8.0
 sphinx_rtd_theme
 

diff --git a/docs/source/Doxyfile b/docs/source/Doxyfile
index d8a862e..664bf64 100644 (file)
--- a/docs/source/Doxyfile
+++ b/docs/source/Doxyfile
@@ -1,7 +1,6 @@
 # What to read
 INPUT                  = ../../include/simgrid/forward.h
 INPUT                 += ../../include/simgrid/s4u
 # What to read
 INPUT                  = ../../include/simgrid/forward.h
 INPUT                 += ../../include/simgrid/s4u

-INPUT                 += ../../include/simgrid/xbt

 INPUT                 += ../../include/simgrid/msg.h
 INPUT                 += ../../src/msg/
 RECURSIVE              = YES
 INPUT                 += ../../include/simgrid/msg.h
 INPUT                 += ../../src/msg/
 RECURSIVE              = YES

diff --git a/docs/source/app_java.rst b/docs/source/app_java.rst
index 067726d..828c5f4 100644 (file)
--- a/docs/source/app_java.rst
+++ b/docs/source/app_java.rst
@@ -1,8 +1,7 @@
 .. _Java_doc:
 
 .. _Java_doc:
 

-=================

 The Java Bindings
 The Java Bindings

-=================
+#################

 
 .. raw:: html
 
 
 .. raw:: html
 


@@ -19,22 +18,22 @@ The Java Bindings
    
 This section describes jMSG, the Java API to Simgrid. This API mimicks 
 :ref:`MSG <MSG_doc>`, which is a simple yet somehow realistic interface.
    
 This section describes jMSG, the Java API to Simgrid. This API mimicks 
 :ref:`MSG <MSG_doc>`, which is a simple yet somehow realistic interface.

-<b>The full [javadoc](javadoc/index.html) is available.</b>
+<b>The full reference documentation is provided at the end of this page.</b>

 
 Most of the documentation of the :ref:`MSG API <MSG_doc>` in C applies
 directly to the Java bindings (any divergence is seen as a bug that we
 should fix). MSG structures are mapped to Java objects as expected,
 and the MSG functions are methods in these objects.
 
 
 Most of the documentation of the :ref:`MSG API <MSG_doc>` in C applies
 directly to the Java bindings (any divergence is seen as a bug that we
 should fix). MSG structures are mapped to Java objects as expected,
 and the MSG functions are methods in these objects.
 

-How to install the Java bindings
---------------------------------
+Installing the Java bindings
+****************************

 
 The easiest is to use a :ref:`precompiled jarfile <install_java_precompiled>`,
 but some people may prefer to :ref:`compile it from the sources <install_src>`.
 
 
 
 The easiest is to use a :ref:`precompiled jarfile <install_java_precompiled>`,
 but some people may prefer to :ref:`compile it from the sources <install_src>`.
 
 

-How to use the Java bindings
-----------------------------
+Using the Java bindings
+***********************

 
 In most cases, you can use the SimGrid bindings as if it was a Java
 library:
 
 In most cases, you can use the SimGrid bindings as if it was a Java
 library:


@@ -58,7 +57,7 @@ should declare these actors, plus a Main class in charge of deploying
 your actors on the platform. Please refer to the examples for details.
 
 Troubleshooting
 your actors on the platform. Please refer to the examples for details.
 
 Troubleshooting

----------------
+***************

 
 Actually, these bindings are not only implemented in Java. They do use
 the C implementation of SimGrid. This should be transparent as this
 
 Actually, these bindings are not only implemented in Java. They do use
 the C implementation of SimGrid. This should be transparent as this


@@ -66,7 +65,7 @@ library is directly included in the ``simgrid.jar`` file but things can
 still go wrong is several ways.
 
 Error: library simgrid not found
 still go wrong is several ways.
 
 Error: library simgrid not found

-................................
+================================

 
 This means that the JVM fails to load the native library. If you use a
 precompiled jarfile, please report this bug.
 
 This means that the JVM fails to load the native library. If you use a
 precompiled jarfile, please report this bug.


@@ -77,13 +76,13 @@ path to the native library into the ``LD_LIBRARY_PATH`` variable (or in
 the ``DYLD_LIBRARY_PATH`` on Mac OSX).
 
 pthread_create failed
 the ``DYLD_LIBRARY_PATH`` on Mac OSX).
 
 pthread_create failed

-.....................
+=====================

 
 You reached the amount of threads that can be run on your system. Try
 increasing the thread limits of your operating system.
 
 Other errors
 
 You reached the amount of threads that can be run on your system. Try
 increasing the thread limits of your operating system.
 
 Other errors

-............
+============

 
 When using jMSG, your program can crash for 3 main reasons:
 
 
 When using jMSG, your program can crash for 3 main reasons:
 


@@ -106,3 +105,36 @@ When using jMSG, your program can crash for 3 main reasons:
     the error should be uglier. In that case, you may submit a bug directly to
     SimGrid.
 
     the error should be uglier. In that case, you may submit a bug directly to
     SimGrid.
 

+API Reference
+*************
+
+Package org.simgrid.msg
+=======================
+
+.. java:package:: org.simgrid.msg
+
+.. toctree::
+   :maxdepth: 1
+
+   Class org.simgrid.msg.As <java/org/simgrid/msg/As>
+   Class org.simgrid.msg.Comm <java/org/simgrid/msg/Comm>
+   Class org.simgrid.msg.File <java/org/simgrid/msg/File>
+   Class org.simgrid.msg.Host <java/org/simgrid/msg/Host>
+   Class org.simgrid.msg.HostFailureException <java/org/simgrid/msg/HostFailureException>
+   Class org.simgrid.msg.HostNotFoundException <java/org/simgrid/msg/HostNotFoundException>
+   Class org.simgrid.msg.JniException <java/org/simgrid/msg/JniException>
+   Class org.simgrid.msg.Msg <java/org/simgrid/msg/Msg>
+   Class org.simgrid.msg.MsgException <java/org/simgrid/msg/MsgException>
+   Class org.simgrid.msg.Mutex <java/org/simgrid/msg/Mutex>
+   Class org.simgrid.msg.Process <java/org/simgrid/msg/Process>
+   Class org.simgrid.msg.ProcessKilledError <java/org/simgrid/msg/ProcessKilledError>
+   Class org.simgrid.msg.ProcessNotFoundException <java/org/simgrid/msg/ProcessNotFoundException>
+   Class org.simgrid.msg.RngStream <java/org/simgrid/msg/RngStream>
+   Class org.simgrid.msg.Semaphore <java/org/simgrid/msg/Semaphore>
+   Class org.simgrid.msg.Storage <java/org/simgrid/msg/Storage>
+   Class org.simgrid.msg.StorageNotFoundException <java/org/simgrid/msg/StorageNotFoundException>
+   Class org.simgrid.msg.Task <java/org/simgrid/msg/Task>
+   Class org.simgrid.msg.TaskCancelledException <java/org/simgrid/msg/TaskCancelledException>
+   Class org.simgrid.msg.TimeoutException <java/org/simgrid/msg/TimeoutException>
+   Class org.simgrid.msg.TransferFailureException <java/org/simgrid/msg/TransferFailureException>
+   Class org.simgrid.msg.VM <java/org/simgrid/msg/VM>

diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst
index 71da01b..2ada588 100644 (file)
--- a/docs/source/app_s4u.rst
+++ b/docs/source/app_s4u.rst
@@ -58,9 +58,8 @@ itself in a |NetZone|_, that knows the networking path between one
 resource to another. Each NetZone is included in another one, forming
 a tree of NetZones which root zone contains the whole platform.
 
 resource to another. Each NetZone is included in another one, forming
 a tree of NetZones which root zone contains the whole platform.
 

-The :ref:`simgrid::s4u::this_actor
-<namespace_simgrid__s4u__this_actor>` namespace provides many helper
-functions to simplify the code of actors.
+The :ref:`simgrid::s4u::this_actor <API_s4u_this_actor>` namespace
+provides many helper functions to simplify the code of actors.

 
 - **Global Classes**
 
 
 - **Global Classes**
 

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 350b49c..b56aeca 100644 (file)
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -52,7 +52,7 @@ extensions = [
     'breathe',
 #    'exhale',
     'hidden_code_block',
     'breathe',
 #    'exhale',
     'hidden_code_block',

-#    'snooze', # must come after exhale
+    'javasphinx',

 ]
 
 todo_include_todos = True
 ]
 
 todo_include_todos = True

diff --git a/docs/source/index.rst b/docs/source/index.rst
index c5f5185..3418071 100644 (file)
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -38,3 +38,13 @@ Welcome to SimGrid's documentation!
       The SimGrid Community <community.rst>
       Frequently Asked Questions <faq.rst>
 
       The SimGrid Community <community.rst>
       Frequently Asked Questions <faq.rst>
 

+
+
+.. Cheat Sheet on the sublevels
+..
+..   # with overline, for parts
+..   * with overline, for chapters
+..   =, for sections
+..   -, for subsections
+..   ^, for subsubsections
+..   ", for paragraphs