Commit 3c22c3de authored by yoogx's avatar yoogx

* New format for documentation, now using Sphinx

parent ca52a974
# 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
......
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
.. _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.
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
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
# -*- coding: utf-8 -*-
#
# Ocarina documentation build configuration file, created by
# sphinx-quickstart on Mon Mar 3 22:24:45 2014.
#
# This file is execfile()d with the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import sys, os
import sphinx_bootstrap_theme
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
# -- General configuration -----------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'Ocarina'
copyright = u'2003-2009 Telecom ParisTech, 2009-2014 ISAE, ESA'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '2.0w'
# The full version, including alpha/beta/rc tags.
release = '2.0w'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['_build']
# The reST default role (used for this markup: `text`) to use for all documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# -- Options for HTML output ---------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'bootstrap'
html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
html_theme_options = {
# Navigation bar title. (Default: ``project`` value)
# 'navbar_title': "Demo",
# Tab name for entire site. (Default: "Site")
'navbar_site_name': "Ocarina User's Guide",
# A list of tuples containing pages or urls to link to.
# Valid tuples should be in the following forms:
# (name, page) # a link to a page
# (name, "/aa/bb", 1) # a link to an arbitrary relative url
# (name, "http://example.com", True) # arbitrary absolute url
# Note the "1" or "True" value above as the third argument to indicate
# an arbitrary url.
# 'navbar_links': [
# ("Examples", "examples"),
# ("Link", "http://example.com", True),
# ],
# Render the next and previous page links in navbar. (Default: true)
'navbar_sidebarrel': True,
# Render the current pages TOC in the navbar. (Default: true)
'navbar_pagenav': True,
# Global TOC depth for "site" navbar tab. (Default: 1)
# Switching to -1 shows all levels.
'globaltoc_depth': 2,
# Include hidden TOCs in Site navbar?
#
# Note: If this is "false", you cannot have mixed ``:hidden:`` and
# non-hidden ``toctree`` directives in the same page, or else the build
# will break.
#
# Values: "true" (default) or "false"
'globaltoc_includehidden': "true",
# HTML navbar class (Default: "navbar") to attach to <div> element.
# For black navbar, do "navbar navbar-inverse"
'navbar_class': "navbar navbar-inverse",
# Fix navigation bar to top of page?
# Values: "true" (default) or "false"
'navbar_fixed_top': "true",
# Location of link to source.
# Options are "nav" (default), "footer" or anything else to exclude.
'source_link_position': "",
# Bootswatch (http://bootswatch.com/) theme.
#
# Options are nothing with "" (default) or the name of a valid theme
# such as "amelia" or "cosmo".
'bootswatch_theme': "spacelab",
# Choose Bootstrap version.
# Values: "3" (default) or "2" (in quotes)
'bootstrap_version': "3",
}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
#html_sidebars = {'**': ['localtoc.html', 'sourcelink.html', 'searchbox.html']}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
html_show_sphinx = False
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'Ocarinadoc'