* New format for documentation, now using Sphinx

doc/Makefile.am

-# For now, do not build real documentation, it requires LaTeX files
-# that may not be installed. However, its source is included in the
-# packaging.
-DIST_SUBDIRS = real
-
-ADAFILES=  $(srcdir)/sources/parse_and_print_aadl.adb
-
-AADLFILES= $(srcdir)/sources/scenario_ada.aadl			\
-	$(srcdir)/sources/scenario_c.aadl			\
-	$(srcdir)/sources/scenario_common.aadl			\
-	$(srcdir)/sources/example_pn.aadl			\
-	$(top_srcdir)/resources/AADLv1/aadl_project.aadl	\
-	$(top_srcdir)/resources/AADLv1/aadl_properties.aadl	\
-	$(top_srcdir)/resources/deployment.aadl			\
-	$(top_srcdir)/resources/ocarina_config.aadl
-
-APIFILES=								      \
-$(top_srcdir)/src/core/tree/ocarina-me_aadl-aadl_tree-entities.ads	      \
-$(top_srcdir)/src/core/tree/ocarina-me_aadl-aadl_tree-entities-properties.ads \
-$(top_srcdir)/src/core/model/ocarina-builder.ads			      \
-$(top_srcdir)/src/core/model/ocarina-builder-aadl.ads                         \
-$(top_srcdir)/src/core/model/ocarina-builder-aadl-annexes.ads		      \
-$(top_srcdir)/src/core/model/ocarina-builder-aadl-components.ads	      \
-$(top_srcdir)/src/core/model/ocarina-builder-aadl-components-connections.ads  \
-$(top_srcdir)/src/core/model/ocarina-builder-aadl-components-features.ads     \
-$(top_srcdir)/src/core/model/ocarina-builder-aadl-components-flows.ads	      \
-$(top_srcdir)/src/core/model/ocarina-builder-aadl-components-modes.ads	      \
-$(top_srcdir)/src/core/model/ocarina-builder-aadl-components-subcomponents.ads\
-$(top_srcdir)/src/core/model/ocarina-builder-aadl-components-subprogram_calls.ads  \
-$(top_srcdir)/src/core/model/ocarina-builder-aadl-namespaces.ads              \
-$(top_srcdir)/src/core/model/ocarina-builder-aadl-properties.ads	      \
-$(top_srcdir)/src/core/model/ocarina-analyzer-aadl-finder.ads		      \
-$(top_srcdir)/src/core/model/ocarina-analyzer-aadl-queries.ads
-
-GEN_TEXIFILES= ${notdir $(ADAFILES:=.texi) $(AADLFILES:=.texi) $(APIFILES:=.texi)}
-
-IMAGE_NAMES=\
-	$(srcdir)/images/component\
-	$(srcdir)/images/connection\
-	$(srcdir)/images/feature\
-	$(srcdir)/images/mubroker_complet\
-	$(srcdir)/images/spg_connection\
-	$(srcdir)/images/subprogram
-
-ALL_IMAGES= $(IMAGE_NAMES:=.eps) $(IMAGE_NAMES:=.png) $(IMAGE_NAMES:=.pdf)
-
-KW_FILES = \
-	$(srcdir)/aadl.kw\
-	$(srcdir)/ada.kw
-
-SED_FILES = ${notdir $(KW_FILES:.kw=.sed)}
-
 GUIDE=ocarina
 
-GUIDE_TEXIFILES =\
-	$(srcdir)/$(GUIDE).texi\
-	$(GEN_TEXIFILES) \
-	gfdl.texi
-
-info_TEXINFOS = ocarina.texi
-ocarina_TEXINFOS=$(GUIDE_TEXIFILES)
-
 man_MANS = ocarina-config.1 ocarina.1
 
+GUIDE_RSTFILES = $(srcdir)/about.rst $(srcdir)/gfdl.rst			\
+	$(srcdir)/introduction.rst $(srcdir)/annexes.rst index.rst	\
+	$(srcdir)/python.rst $(srcdir)/editors.rst			\
+	$(srcdir)/installation.rst $(srcdir)/usage.rst
+
 EXTRA_DIST= $(srcdir)/CODING_GUIDELINES $(srcdir)/CONTRIBUTING		\
 	$(srcdir)/PROBLEM-REPORT-FORM $(GUIDE_TEXIFILES) $(ALL_IMAGES)	\
-	$(ADAFILES) $(AADLFILES) $(KW_FILES) $(srcdir)/ocarina.css	\
 	$(man_MANS) $(srcdir)/ocarina-config.html			\
 	$(srcdir)/ocarina_man.html
 
 all-local: $(GUIDE).html $(GUIDE).pdf
 
-$(GUIDE).html: $(IMAGES) $(GUIDE_TEXIFILES)
-	-$(MAKEINFO) --css-include=$(srcdir)/ocarina.css --force --html --ifhtml --number-sections $(srcdir)/$(GUIDE).texi -o $(GUIDE).html
-	rm -rf $(GUIDE).html/images
-	mkdir -p $(GUIDE).html/images
-	cp -p $(srcdir)/images/*.png $(GUIDE).html/images/
-	INDEX_FILE="$(GUIDE).html/index.html";\
-	TMP_FILE="$$INDEX_FILE.tmp"; \
-	cat "$$INDEX_FILE" | sed 's/$$LastChangedDate: \([^$$]*\) \$$/Last Modified: \1/g' > "$$TMP_FILE"; \
-	mv -f "$$TMP_FILE" "$$INDEX_FILE"
+$(GUIDE).html: $(GUIDE_RSTFILES)
+	make  html
 
-$(GUIDE).pdf: $(IMAGES) $(GUIDE_TEXIFILES)
-	-$(TEXI2PDF) $(srcdir)/$(GUIDE).texi
+$(GUIDE).pdf: $(IMAGES) $(GUIDE_RSTFILES)
+	make  latexpdf
 
 clean-local:
-	rm -f *.aux *.log *.dvi *.info *.tmp
-	rm -f *.cp *.pg *.toc *.vr *.fn *.ky *.tp *~
+	rm -f *~
+	-rm -rf $(BUILDDIR)/*
 
 distclean-local:
 	rm -f $(GEN_TEXIFILES)
@@ -112,71 +49,52 @@ dist-hook: all
 
 install-data-local: all
 	$(INSTALL) -d $(DESTDIR)$(datadir)/doc/ocarina
-	if [ -r $(GUIDE).pdf ]; then \
-	  $(INSTALL_DATA) $(GUIDE).pdf $(DESTDIR)$(datadir)/doc/ocarina; \
+	if [ -r $(builddir)/_build/latex/$(GUIDE).pdf ]; then \
+	  $(INSTALL_DATA) $(builddir)/_build/latex/$(GUIDE).pdf $(DESTDIR)$(datadir)/doc/ocarina; \
 	  $(INSTALL) -d $(DESTDIR)$(datadir)/doc/ocarina/$(GUIDE).html; \
-	  for f in $(GUIDE).html/*.html; do \
-            $(INSTALL_DATA) $$f $(DESTDIR)$(datadir)/doc/ocarina/$(GUIDE).html; \
-          done; \
-	  $(INSTALL) -d $(DESTDIR)$(datadir)/doc/ocarina/$(GUIDE).html/images; \
-	  for f in $(GUIDE).html/images/*.png; do \
-            $(INSTALL_DATA) $$f $(DESTDIR)$(datadir)/doc/ocarina/$(GUIDE).html/images; \
-          done; \
-	else \
-	  $(INSTALL_DATA) $(srcdir)/$(GUIDE).pdf $(DESTDIR)$(datadir)/doc/ocarina; \
-	  $(INSTALL) -d $(DESTDIR)$(datadir)/doc/ocarina/$(GUIDE).html; \
-	  for f in $(srcdir)/$(GUIDE).html/*.html; do \
-            $(INSTALL_DATA) $$f $(DESTDIR)$(datadir)/doc/ocarina/$(GUIDE).html; \
-          done; \
-	  $(INSTALL) -d $(DESTDIR)$(datadir)/doc/ocarina/$(GUIDE).html/images; \
-	  for f in $(srcdir)/$(GUIDE).html/images/*.png; do \
-            $(INSTALL_DATA) $$f $(DESTDIR)$(datadir)/doc/ocarina/$(GUIDE).html/images; \
-          done; \
+	  $(CP) -r $(builddir)/_build/html/* $(DESTDIR)$(datadir)/doc/ocarina/$(GUIDE).html; \
 	fi
 	$(INSTALL_DATA)	$(srcdir)/CONTRIBUTING $(DESTDIR)$(datadir)/doc/ocarina
 	$(INSTALL_DATA)	$(srcdir)/PROBLEM-REPORT-FORM $(DESTDIR)$(datadir)/doc/ocarina
-	$(INSTALL_DATA)	$(builddir)/ocarina-config.html $(DESTDIR)$(datadir)/doc/ocarina
-	$(INSTALL_DATA)	$(builddir)/ocarina_man.html $(DESTDIR)$(datadir)/doc/ocarina
+	$(INSTALL_DATA)	$(srcdir)/ocarina-config.html $(DESTDIR)$(datadir)/doc/ocarina
+	$(INSTALL_DATA)	$(srcdir)/ocarina_man.html $(DESTDIR)$(datadir)/doc/ocarina
 	$(INSTALL_DATA)	$(srcdir)/ocarina.css $(DESTDIR)$(datadir)/doc/ocarina
 
 uninstall-local:
 	rm -rf $(DESTDIR)$(datadir)/doc/ocarina
 
-$(GUIDE_TEXIFILES): ada-stamp adb-stamp ads-stamp aadl-stamp
-
-ada-stamp: $(top_srcdir)/tools/gentexifile $(ADAFILES) sed-stamp
-	for f in ${filter %.ada, $(ADAFILES)}; do \
-	  $(SHELL) $(top_srcdir)/tools/gentexifile $$f; \
-	done
-	touch ada-stamp
-
-adb-stamp: $(top_srcdir)/tools/gentexifile $(ADAFILES) sed-stamp
-	for f in ${filter %.adb, $(ADAFILES)}; do \
-	  $(SHELL) $(top_srcdir)/tools/gentexifile $$f; \
-	done
-	touch adb-stamp
-
-ads-stamp: $(top_srcdir)/tools/gen_api_doc $(APIFILES)
-	ABS_TOP_SRCDIR="@abs_top_srcdir@" \
-	ABS_TOP_BUILDDIR="@abs_top_builddir@" \
-	  $(SHELL) $(top_srcdir)/tools/gen_api_doc
-	touch ads-stamp
-
-aadl-stamp: $(top_srcdir)/tools/gentexifile $(AADLFILES) sed-stamp
-	for f in $(AADLFILES); do \
-	  $(SHELL) $(top_srcdir)/tools/gentexifile $$f; \
-	done
-	touch aadl-stamp
-
-sed-stamp: $(top_srcdir)/tools/gensedfile $(KW_FILES)
-	for f in $(KW_FILES); do \
-	  $(SHELL) $(top_srcdir)/tools/gensedfile $$f; \
-	done
-	touch sed-stamp
 
 ###############################################################################
-# Building manpages
+# SPHINX rules
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = $(builddir)/_build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -c $(srcdir) -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(srcdir)
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
 
+###############################################################################
+# Building manpages
 
 build_man: $(top_srcdir)/ocarina-config.in
 	chmod 755 $(top_builddir)/ocarina-config

doc/aadl.kw

-aadlboolean
-aadlinteger
-aadlreal
-aadlstring
-access
-all
-and
-annex
-applies
-binding
-bus
-calls
-classifier
-connections
-constant
-data
-delta
-device
-end
-enumeration
-event
-extends
-false
-features
-flow
-flows
-group
-implementation
-in
-inherit
-initial
-inverse
-is
-list
-memory
-mode
-modes
-none
-not
-of
-or
-out
-package
-parameter
-path
-port
-private
-process
-processor
-properties
-property
-provides
-public
-range
-reference
-refined
-refines
-requires
-server
-set
-sink
-source
-subcomponents
-subprogram
-system
-thread
-to
-true
-type
-units
-value

doc/about.rst

+
+
+.. _about:
+
+================
+About This Guide
+================
+
+About this Guide
+################
+
+This guide describes the use of Ocarina, a compiler for the AADL.
+
+It presents the features of the compiler, related APIs and tools; and
+details how to use them to build and exploit AADL models.
+
+It also details model transformations of AADL models onto Petri Net models
+
+Companion documents describe other add-ons for Ocarina:
+
+* PolyORB-HI/Ada, a High-Integrity AADL runtime and its code generator
+  built on top of Ocarina that targets Ada targets: Native or bare
+  board runtimes;
+
+* PolyORB-HI/C, a High-Integrity AADL runtime and its code generator
+  built on top of Ocarina that targets C targets: POSIX and RT-POSIX
+  systems, RTEMS.
+
+Document Conventions
+####################
+
+This document uses the following conventions:
+
+.. note:: This is just a note, for your information.
+
+.. warning:: This is a warning, something you should take care of.
+
+A filename or a path to a filename is displayed like this:
+:file:`/path/to/filename.ext`
+
+A command to type in the shell is displayed like this:
+:command:`command --arguments`
+
+A sample of code is illustrated like this:
+
+::
+
+    First Line of Code
+    Second Line of Code
+    ...
+
+.. _copyright:
+
+Copyright Information
+#####################
+
+
+    Permission is granted to copy, distribute and/or modify this
+    document under the terms of the GNU Free Documentation
+    License, Version 1.1 or any later version published by the
+    Free Software Foundation; with no Invariant Sections, no
+    Front-Cover Texts, and with no Back-Cover Texts. A copy of
+    the license is included in :ref:`gfdl`.
+
+If you have any questions regarding this document, its
+copyright, or publishing this document in non-electronic form,
+please contact us.
+

doc/ada.kw

-with
-while
-when
-use
-until
-type
-then
-terminate
-task
-tagged
-subtype
-separate
-select
-reverse
-reverse
-return
-requeue
-renames
-rem
-record
-range
-raise
-protected
-procedure
-private
-pragma
-package
-out
-others
-or
-of
-null
-not
-new
-mod
-loop
-limited
-is
-in
-if
-goto
-generic
-function
-for
-exit
-exception
-entry
-end
-elsif
-else
-do
-digits
-delta
-delay
-declare
-constant
-configuration
-case
-body
-begin
-array
-and
-all
-aliased
-access
-accept
-abstract
-abs
-abort

doc/annexes.rst

+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

doc/editors.rst

+
+
+.. _editors:
+
+==============
+Editor support
+==============
+
+The AADL modes for Emacs and vim provide syntax coloration and
+automatic indentation features when editing AADL files.
+
+Emacs
+=====
+
+To load the AADL mode for Emacs, you need to add the following line to
+your emacs configuration file (usually located in :file:`~/.emacs`) ::
+
+      (load "/path/to/this/file.el")
+
+For more details on this mode, please refer to the emacs contextual help.
+
+.. figure:: aadl-mode.png
+   :align: center
+
+   AADL mode for Emacs
+
+vim
+===
+
+The AADL mode for vim is made of two files aadl.vim: one for syntactic
+coloration, and the other for indentation. The file for indentation
+must be placed into ~/.vim/indent/ while the one for syntactic
+coloration must be placed into :file:`~/.vim/syntax/`
+
+To load the AADL mode whenever you edit AADL files, create a file
+named :file:`~/.vim/filetype.vim`, in which you write::
+
+     augroup filetypedetect
+             au BufNewFile,BufRead *.aadl    setf aadl
+     augroup END
+
+For more details, please read the documentation of vim.
+
+
+.. figure:: aadl-mode_vim.png
+   :align: center
+
+   AADL mode for vim
+

doc/index.rst

+.. Ocarina documentation master file, created by
+   sphinx-quickstart on Mon Mar  3 22:24:45 2014.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Ocarina User's Guide
+====================
+
+.. toctree::
+   :maxdepth: 2
+
+   about
+   introduction
+   installation
+   usage
+   osate-ocarina
+   python
+   editors
+   gfdl
+   annexes
+

doc/installation.rst

+
+.. _installation:
+
+============
+Installation
+============
+
+Supported platforms
+###################
+
+Ocarina has been compiled and successfully tested on the following platforms:
+
+* GNU/Linux
+* Mac OS X
+* Windows
+
+.. note:: Ocarina should compile and run on every target for which GNAT is available.
+
+
+Build requirements
+##################
+
+An Ada compiler:
+
+* GNAT Pro, GNAT GPL or FSF/GCC with Ada back-end
+
+.. note:: per construction, the macro configure used to find your GNAT
+   compiler looks first to the executable gnatgcc, then adagcc and
+   finally to gcc to find out which Ada compiler to use. You should be
+   very careful with your path and binaries if you have multiple GNAT
+   versions installed. See below explanations on the ADA environment
+   variable if you need to override the default guess.
+
+Optional components:
+
+* GNATColl for the Ocarina Python bindings
+* Sphinx and the sphinx-bootstrap-theme to build the documentation,
+  and a full valid LaTeX installation
+* Bound-T for the WCET analysis (:code:`bound_t` backend)
+* Cheddar for scheduling analysis (:code:`cheddar` backend)
+* MAST for scheduling analysis (:code:`mast` backend)
+* RTOS supported by one of the Ocarina runtimes
+
+Build instructions
+##################
+
+To compile and install Ocarina, execute in a shell::
+
+       % ./configure [some options]
+       % make              (or gmake if your make is not GNU make)
+       % make install      (ditto)
+
+This will install files in standard locations. If you want to choose
+another prefix than `/usr/local`, give configure use `--prefix` argument
+
+.. note:: you MUST use GNU make to compile this software.
+
+.. note:: If you modify source files, build Ocarina after a checkout
+   or make distclean, or the directory hierarchy of the source files,
+   you should re-generate autoconf and automake files (configure,
+   Makefile.in...); to do this, from the main directory, run::
+
+   ./support/reconfig
+
+Build options
+#############
+
+Available options for the configure script include:
+
+* `--enable-doc`: to build the documentation
+
+.. note:: You must first install Sphinx and the sphinx-bootstrap-theme
+
+* `--enable-shared`: to build shared libraries
+
+* `--enable-debug`: enable debugging information generation and
+  supplementary runtime checks. Note that this option has a
+  significant space and time cost, and is not recommended for
+  production use.
+
+* `--enable-python`: to build the Python bindings.
+
+.. note:: This option requires GNATColl to be installed, and Ocarina
+  built with shared libraries support.
+
+* `--with-ocarina-runtimes=x`: enable building Ocarina along with the
+  requested runtimes. x is a set of valid runtimes located in the
+  resources/runtimes directory. x is case insensitive. Examples of
+  use:
+
+* `--with-ocarina-runtimes=all`: compile Ocarina along with all the
+  runtimes. All the Ocarina runtimes MUST be located in the
+  resources/runtimes directory.
+
+* `--with-ocarina-runtimes="polyorb-hi-c PolyORB-HI-Ada"`: compile
+  Ocarina along with the PolyORB-HI-Ada and the PolyORB-HI-C
+  runtimes.
+
+.. note:: The runtime directories (e.g. :file:`polyorb-hi-ada` or
+  :file:`polyorb-hi-c` MUST exist in the resources/runtimes directory.
+
+No option: compile Ocarina along with all the runtimes found in the
+resources/runtimes directory.
+
+For more details on available options, one may use the `--help` flag.
+
+The following environment variables can be used to override
+configure's guess at what compilers to use:
+
+* `CC`: the C compiler
+* `ADA`: the Ada 95 compiler (e.g. gcc, gnatgcc or adagcc)
+
+For example, if you have two versions of GNAT installed and available
+in your PATH, and configure picks the wrong one, you can indicate what
+compiler should be used with the following syntax::
+
+       % ADA=/path/to/good/compiler/gcc ./configure [options]
+
+Ocarina will be compiled with GNAT build host's configuration,
+including run-time library. You may override this setting using
+`ADA_INCLUDE_PATH` and `ADA_OBJECTS_PATH` environment variables. See GNAT
+User's Guide for more details.
+
+.. note:: Developers building Ocarina from the version control
+   repository who need to rebuild the configure and Makefile.in files
+   should use the script support/reconfig for this purpose. This
+   should be done after each update from the repository. In addition
+   to the requirements above, they will need autoconf 2.57 or newer,
+   automake 1.6.3 or newer.
\ No newline at end of file

doc/introduction.rst

+
+.. _introduction:
+
+============
+Introduction
+============
+
+About Ocarina
+#############
+
+.. index:: Ocarina (introduction)
+
+Ocarina is an application that can be used to analyze and build
+applications from AADL descriptions. Because of its modular
+architecture, Ocarina can also be used to add AADL functions to
+existing applications. Ocarina supports the AADL 1.0 and AADLv2
+standards and proposes the following features :
+
+* Parsing and pretty printing of AADL models
+* Semantics checks
+* Code generation, with the following code generators
+
+  * PolyORB-HI/Ada, a High-Integrity AADL runtime and its code
+    generator built on top of Ocarina that targets Ada targets: Native
+    or bare board runtimes;
+  * PolyORB-HI/C, a High-Integrity AADL runtime and its code generator
+    built on top of Ocarina that targets C targets: POSIX systems,
+    RTEMS;
+  * POK, a partioned operating system compliant with the ARINC653 standard.
+
+* Model checking using Petri nets;
+* Computation of Worst-Case Execution Time using the Bound-T tool from Tidorum Ltd.;
+* REAL, Requirement Enforcement and Analysis Language, an AADLv2 annex
+  language to evaluate properties and metrics of AADLv2 architectural
+  models;
+* Scheduling analysis of AADL models, with a gateway to the Cheddar
+  scheduling analysis tool from the Université de Bretagne
+  Occidentale, and MAST from the University of Cantabria
+
+About AADL
+##########
+
+.. index:: AADL