From 599c5671721e2fd0b8f729f60d2852353f6bd5f3 Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Mon, 1 Oct 2018 08:16:08 +0200 Subject: [PATCH 1/1] include the full Java API doc in sphinx --- .gitignore | 1 + docs/Build.sh | 15 +++++++++-- docs/requirements.txt | 2 +- docs/source/Doxyfile | 1 - docs/source/app_java.rst | 54 ++++++++++++++++++++++++++++++++-------- docs/source/app_s4u.rst | 5 ++-- docs/source/conf.py | 2 +- docs/source/index.rst | 10 ++++++++ 8 files changed, 71 insertions(+), 19 deletions(-) diff --git a/.gitignore b/.gitignore index 29b9a4e178..5032bee886 100644 --- a/.gitignore +++ b/.gitignore @@ -66,6 +66,7 @@ build/ *.bpr *.bpf ### Documentation +docs/source/java docs/source/_ext/__pycache__/ doc/allclasses-frame.html doc/allclasses-noframe.html diff --git a/docs/Build.sh b/docs/Build.sh index 9bc5a2610f..acdcd0a2e5 100755 --- a/docs/Build.sh +++ b/docs/Build.sh @@ -5,12 +5,22 @@ 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 +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/' \ @@ -21,7 +31,8 @@ cat source/img/graphical-toc.svg \ echo "List of missing references:" for f in `(grep '' build/xml/msg_8h.xml; \ grep '' build/xml/namespacesimgrid_1_1s4u.xml; \ - grep ']*>//g'|sort` + grep ']*>//g'|sort` do if grep $f source/*rst | grep -q '.. doxygen[^::]*:: '"$f"'$' || diff --git a/docs/requirements.txt b/docs/requirements.txt index 7a99a0275d..2c64af2bfb 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,5 +1,5 @@ breathe -exhale +javasphinx sphinx>=1.8.0 sphinx_rtd_theme diff --git a/docs/source/Doxyfile b/docs/source/Doxyfile index d8a862e310..664bf64487 100644 --- a/docs/source/Doxyfile +++ b/docs/source/Doxyfile @@ -1,7 +1,6 @@ # 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 diff --git a/docs/source/app_java.rst b/docs/source/app_java.rst index 067726db60..828c5f4620 100644 --- a/docs/source/app_java.rst +++ b/docs/source/app_java.rst @@ -1,8 +1,7 @@ .. _Java_doc: -================= The Java Bindings -================= +################# .. raw:: html @@ -19,22 +18,22 @@ The Java Bindings This section describes jMSG, the Java API to Simgrid. This API mimicks :ref:`MSG `, which is a simple yet somehow realistic interface. -The full [javadoc](javadoc/index.html) is available. +The full reference documentation is provided at the end of this page. Most of the documentation of the :ref:`MSG API ` 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 `, but some people may prefer to :ref:`compile it from the sources `. -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: @@ -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 ---------------- +*************** 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 -................................ +================================ 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 -..................... +===================== 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: @@ -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. +API Reference +************* + +Package org.simgrid.msg +======================= + +.. java:package:: org.simgrid.msg + +.. toctree:: + :maxdepth: 1 + + Class org.simgrid.msg.As + Class org.simgrid.msg.Comm + Class org.simgrid.msg.File + Class org.simgrid.msg.Host + Class org.simgrid.msg.HostFailureException + Class org.simgrid.msg.HostNotFoundException + Class org.simgrid.msg.JniException + Class org.simgrid.msg.Msg + Class org.simgrid.msg.MsgException + Class org.simgrid.msg.Mutex + Class org.simgrid.msg.Process + Class org.simgrid.msg.ProcessKilledError + Class org.simgrid.msg.ProcessNotFoundException + Class org.simgrid.msg.RngStream + Class org.simgrid.msg.Semaphore + Class org.simgrid.msg.Storage + Class org.simgrid.msg.StorageNotFoundException + Class org.simgrid.msg.Task + Class org.simgrid.msg.TaskCancelledException + Class org.simgrid.msg.TimeoutException + Class org.simgrid.msg.TransferFailureException + Class org.simgrid.msg.VM diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst index 71da01bb93..2ada588dc5 100644 --- 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. -The :ref:`simgrid::s4u::this_actor -` namespace provides many helper -functions to simplify the code of actors. +The :ref:`simgrid::s4u::this_actor ` namespace +provides many helper functions to simplify the code of actors. - **Global Classes** diff --git a/docs/source/conf.py b/docs/source/conf.py index 350b49c27f..b56aeca01c 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -52,7 +52,7 @@ extensions = [ 'breathe', # 'exhale', 'hidden_code_block', -# 'snooze', # must come after exhale + 'javasphinx', ] todo_include_todos = True diff --git a/docs/source/index.rst b/docs/source/index.rst index c5f5185586..3418071c97 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -38,3 +38,13 @@ Welcome to SimGrid's documentation! The SimGrid Community Frequently Asked Questions + + +.. Cheat Sheet on the sublevels +.. +.. # with overline, for parts +.. * with overline, for chapters +.. =, for sections +.. -, for subsections +.. ^, for subsubsections +.. ", for paragraphs -- 2.20.1