[Olena-patches] olena-2.0-378-g72aefb5 Improve look'n feel of general documentation.

* doc/Doxyfile.in: Improve documentation output. * doc/DoxygenLayout.xml: Update menu. * doc/Makefile.am: Rename .hh outputs to .dox. * doc/white-paper.tex: Fix URL. --- milena/ChangeLog | 12 ++++ milena/doc/Doxyfile.in | 130 ++++++++++++++++++++++++++++-------------- milena/doc/DoxygenLayout.xml | 7 +-- milena/doc/Makefile.am | 16 +---- milena/doc/white-paper.tex | 2 +- 5 files changed, 105 insertions(+), 62 deletions(-) diff --git a/milena/ChangeLog b/milena/ChangeLog index f7b58fa..144575e 100644 --- a/milena/ChangeLog +++ b/milena/ChangeLog @@ -1,3 +1,15 @@ +2013-03-08 Guillaume Lazzara &lt;z(a)lrde.epita.fr&gt; + + Improve look'n feel of general documentation. + + * doc/Doxyfile.in: Improve documentation output. + + * doc/DoxygenLayout.xml: Update menu. + + * doc/Makefile.am: Rename .hh outputs to .dox. + + * doc/white-paper.tex: Fix URL. + 2012-06-18 Guillaume Lazzara &lt;z(a)lrde.epita.fr&gt; * doc/tutorial.tex: Add section about multifile compilation. diff --git a/milena/doc/Doxyfile.in b/milena/doc/Doxyfile.in index 6ebdcf4..c629d2d 100644 --- a/milena/doc/Doxyfile.in +++ b/milena/doc/Doxyfile.in @@ -1,4 +1,4 @@ -# Doxyfile 1.8.0-20120409 +# Doxyfile 1.8.2-20120930 # This file describes the settings to be used by the documentation system # doxygen (www.doxygen.org) for a project. @@ -126,7 +126,9 @@ FULL_PATH_NAMES = NO # only done if one of the specified strings matches the left-hand part of # the path. The tag can be used to show relative paths in the file list. # If left blank the directory from which doxygen is run is used as the -# path to strip. +# path to strip. Note that you specify absolute paths here, but also +# relative paths, which will be relative from the directory where doxygen is +# started. STRIP_FROM_PATH = @top_srcdir@/milena @@ -137,13 +139,13 @@ STRIP_FROM_PATH = @top_srcdir@/milena # definition is used. Otherwise one should specify the include paths that # are normally passed to the compiler using the -I flag. -STRIP_FROM_INC_PATH = +STRIP_FROM_INC_PATH = @top_srcdir@/milena # If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter # (but less readable) file names. This can be useful if your file system # doesn't support long names like on DOS, Mac, or CD-ROM. -SHORT_NAMES = YES +SHORT_NAMES = NO # If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen # will interpret the first line (until the first dot) of a JavaDoc-style @@ -229,14 +231,15 @@ OPTIMIZE_FOR_FORTRAN = NO OPTIMIZE_OUTPUT_VHDL = NO # Doxygen selects the parser to use depending on the extension of the files it -# parses. With this tag you can assign which parser to use for a given extension. -# Doxygen has a built-in mapping, but you can override or extend it using this -# tag. The format is ext=language, where ext is a file extension, and language -# is one of the parsers supported by doxygen: IDL, Java, Javascript, CSharp, C, -# C++, D, PHP, Objective-C, Python, Fortran, VHDL, C, C++. For instance to make -# doxygen treat .inc files as Fortran files (default is PHP), and .f files as C -# (default is Fortran), use: inc=Fortran f=C. Note that for custom extensions -# you also need to set FILE_PATTERNS otherwise the files are not read by doxygen. +# parses. With this tag you can assign which parser to use for a given +# extension. Doxygen has a built-in mapping, but you can override or extend it +# using this tag. The format is ext=language, where ext is a file extension, +# and language is one of the parsers supported by doxygen: IDL, Java, +# Javascript, CSharp, C, C++, D, PHP, Objective-C, Python, Fortran, VHDL, C, +# C++. For instance to make doxygen treat .inc files as Fortran files (default +# is PHP), and .f files as C (default is Fortran), use: inc=Fortran f=C. Note +# that for custom extensions you also need to set FILE_PATTERNS otherwise the +# files are not read by doxygen. EXTENSION_MAPPING = @@ -249,6 +252,13 @@ EXTENSION_MAPPING = MARKDOWN_SUPPORT = YES +# When enabled doxygen tries to link words that correspond to documented classes, +# or namespaces to their corresponding documentation. Such a link can be +# prevented in individual cases by by putting a % sign in front of the word or +# globally by setting AUTOLINK_SUPPORT to NO. + +AUTOLINK_SUPPORT = YES + # If you use STL classes (i.e. std::string, std::vector, etc.) but do not want # to include (a tag file for) the STL sources as input, then you should # set this tag to YES in order to let doxygen match functions declarations and @@ -269,10 +279,10 @@ CPP_CLI_SUPPORT = NO SIP_SUPPORT = NO -# For Microsoft's IDL there are propget and propput attributes to indicate getter -# and setter methods for a property. Setting this option to YES (the default) -# will make doxygen replace the get and set methods by a property in the -# documentation. This will only work if the methods are indeed getting or +# For Microsoft's IDL there are propget and propput attributes to indicate +# getter and setter methods for a property. Setting this option to YES (the +# default) will make doxygen replace the get and set methods by a property in +# the documentation. This will only work if the methods are indeed getting or # setting a simple type. If this is not the case, or you want to show the # methods anyway, you should set this option to NO. @@ -362,7 +372,8 @@ EXTRACT_ALL = NO EXTRACT_PRIVATE = NO -# If the EXTRACT_PACKAGE tag is set to YES all members with package or internal scope will be included in the documentation. +# If the EXTRACT_PACKAGE tag is set to YES all members with package or internal +# scope will be included in the documentation. EXTRACT_PACKAGE = NO @@ -578,7 +589,7 @@ FILE_VERSION_FILTER = # The LAYOUT_FILE tag can be used to specify a layout file which will be parsed # by doxygen. The layout file controls the global structure of the generated -# output files in an output format independent way. The create the layout file +# output files in an output format independent way. To create the layout file # that represents doxygen's defaults, run doxygen with the -l option. # You can optionally specify a file name after the option, if omitted # DoxygenLayout.xml will be used as the name of the layout file. @@ -591,9 +602,11 @@ LAYOUT_FILE = @top_srcdir@/milena/doc/DoxygenLayout.xml # requires the bibtex tool to be installed. See also # http://en.wikipedia.org/wiki/BibTeX for more info. For LaTeX the style # of the bibliography can be controlled using LATEX_BIB_STYLE. To use this -# feature you need bibtex and perl available in the search path. +# feature you need bibtex and perl available in the search path. Do not use +# file names with spaces, bibtex cannot handle them. -CITE_BIB_FILES = @abs_top_srcdir@/doc/doc.bib +CITE_BIB_FILES = @abs_top_srcdir@/doc/doc.bib \ + @abs_top_srcdir@/doc/olena.bib #--------------------------------------------------------------------------- # configuration options related to warning and progress messages @@ -807,7 +820,7 @@ INLINE_SOURCES = NO # Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct # doxygen to hide any special comment blocks from generated source code -# fragments. Normal C and C++ comments will always remain visible. +# fragments. Normal C, C++ and Fortran comments will always remain visible. STRIP_CODE_COMMENTS = YES @@ -910,12 +923,22 @@ HTML_FOOTER = @top_srcdir@/doc/subdoc_footer.html # The HTML_STYLESHEET tag can be used to specify a user-defined cascading # style sheet that is used by each HTML page. It can be used to -# fine-tune the look of the HTML output. If the tag is left blank doxygen -# will generate a default style sheet. Note that doxygen will try to copy -# the style sheet file to the HTML output directory, so don't put your own -# style sheet in the HTML output directory as well, or it will be erased! +# fine-tune the look of the HTML output. If left blank doxygen will +# generate a default style sheet. Note that it is recommended to use +# HTML_EXTRA_STYLESHEET instead of this one, as it is more robust and this +# tag will in the future become obsolete. + +HTML_STYLESHEET = + +# The HTML_EXTRA_STYLESHEET tag can be used to specify an additional +# user-defined cascading style sheet that is included after the standard +# style sheets created by doxygen. Using this option one can overrule +# certain style aspects. This is preferred over using HTML_STYLESHEET +# since it does not replace the standard style sheet and is therefor more +# robust against future updates. Doxygen will copy the style sheet file to +# the output directory. -HTML_STYLESHEET = @top_srcdir@/doc/doxygen.css +HTML_EXTRA_STYLESHEET = @top_srcdir@/doc/doc.css # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or # other source files which should be copied to the HTML output directory. Note @@ -957,20 +980,23 @@ HTML_COLORSTYLE_GAMMA = 80 HTML_TIMESTAMP = YES -# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, -# files or namespaces will be aligned in HTML using tables. If set to -# NO a bullet list will be used. - -HTML_ALIGN_MEMBERS = YES - # If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML # documentation will contain sections that can be hidden and shown after the -# page has loaded. For this to work a browser that supports -# JavaScript and DHTML is required (for instance Mozilla 1.0+, Firefox -# Netscape 6.0+, Internet explorer 5.0+, Konqueror, or Safari). +# page has loaded. HTML_DYNAMIC_SECTIONS = NO +# With HTML_INDEX_NUM_ENTRIES one can control the preferred number of +# entries shown in the various tree structured indices initially; the user +# can expand and collapse entries dynamically later on. Doxygen will expand +# the tree to such a level that at most the specified number of entries are +# visible (unless a fully collapsed tree already exceeds this amount). +# So setting the number of entries 1 will produce a full collapsed tree by +# default. 0 is a special value representing an infinite number of entries +# and will result in a full expanded tree by default. + +HTML_INDEX_NUM_ENTRIES = 100 + # If the GENERATE_DOCSET tag is set to YES, additional index files # will be generated that can be used as input for Apple's Xcode 3 # integrated development environment, introduced with OSX 10.5 (Leopard). @@ -989,24 +1015,24 @@ GENERATE_DOCSET = NO # documentation sets from a single provider (such as a company or product suite) # can be grouped. -DOCSET_FEEDNAME = "Doxygen generated docs" +DOCSET_FEEDNAME = "Olena Platform Documentation" # When GENERATE_DOCSET tag is set to YES, this tag specifies a string that # should uniquely identify the documentation set bundle. This should be a # reverse domain-name style string, e.g. com.mycompany.MyDocSet. Doxygen # will append .docset to the name. -DOCSET_BUNDLE_ID = org.doxygen.Project +DOCSET_BUNDLE_ID = org.lrde.olena -# When GENERATE_PUBLISHER_ID tag specifies a string that should uniquely identify -# the documentation publisher. This should be a reverse domain-name style -# string, e.g. com.mycompany.MyDocSet.documentation. +# When GENERATE_PUBLISHER_ID tag specifies a string that should uniquely +# identify the documentation publisher. This should be a reverse domain-name +# style string, e.g. com.mycompany.MyDocSet.documentation. -DOCSET_PUBLISHER_ID = org.doxygen.Publisher +DOCSET_PUBLISHER_ID = org.lrde # The GENERATE_PUBLISHER_NAME tag identifies the documentation publisher. -DOCSET_PUBLISHER_NAME = Publisher +DOCSET_PUBLISHER_NAME = EPITA - LRDE # If the GENERATE_HTMLHELP tag is set to YES, additional index files # will be generated that can be used as input for tools like the @@ -1050,7 +1076,7 @@ BINARY_TOC = NO # The TOC_EXPAND flag can be set to YES to add extra items for group members # to the contents of the HTML help documentation and to the tree view. -TOC_EXPAND = NO +TOC_EXPAND = YES # If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and # QHP_VIRTUAL_FOLDER are set, an additional index file will be generated @@ -1494,7 +1520,7 @@ MACRO_EXPANSION = YES # then the macro expansion is limited to the macros specified with the # PREDEFINED and EXPAND_AS_DEFINED tags. -EXPAND_ONLY_PREDEF = YES +EXPAND_ONLY_PREDEF = NO # If the SEARCH_INCLUDES tag is set to YES (the default) the includes files # pointed to by INCLUDE_PATH will be searched when a #include is found. @@ -1528,6 +1554,7 @@ PREDEFINED = "for_all(x)=for(x.start(); x.is_valid(); x.next())" \ "for_all_remaining(x)=if (! x.is_valid()) {} else while (x.next(), x.is_valid())" \ "mlc_unqualif(T)=typename mln::metal::unqualif<T>::ret" \ "mlc_equal(T1,T2)=mln::metal::equal<T1,T2>" \ + "mlc_bool(B)=mln::metal::bool_<( B )>" \ "mln_piter(T)=typename T::piter" \ "mln_fwd_piter(T)=typename T::fwd_piter" \ "mln_bkd_piter(T)=typename T::bkd_piter" \ @@ -1629,8 +1656,23 @@ PREDEFINED = "for_all(x)=for(x.start(); x.is_valid(); x.next())" \ "mlc_is_a(T, M)=mln::metal::is_a<T, M>" \ "mlc_is_a__1comma(Tleft, Tright, M)=mln::metal::is_a<Tleft, Tright, M>" \ "mlc_is_not_a(T, M)=mln::metal::is_not_a< T, M >" \ + "mlc_is_not(T, U)=mln::metal::is_not< T, U >" \ "mlc_converts_to(T, U)=mln::metal::converts_to< T, U >" \ "mlc_not_equal(T1, T2)=mln::metal::not_equal< T1, T2 >" \ + "mlc_is(T, U)=mln::metal::is< T, U >" \ + "mlc_and(B1, B2)=mln::metal::and_< B1, B2 >" \ + "mln_trait_window_size(W)=typename mln::trait::window_< W >::size" \ + "mln_trait_window_support(W)=typename mln::trait::window_< W >::support" \ + "mln_trait_window_definition(W)=typename mln::trait::window_< W >::definition" \ + "mln_is_simple_window(W)=mln::metal::and_< mlc_is(mln_trait_window_size(W), \ + mln::trait::window::size::fixed), \ + mln::metal::and_< mlc_is(mln_trait_window_support(W), \ + mln::trait::window::support::regular), \ + mlc_is(mln_trait_window_definition(W), \ + mln::trait::window::definition::unique) > >" \ + "mln_is_fastest_IW(I, W)=mlc_and(mlc_is(mln_trait_image_speed(I), \ + trait::image::speed::fastest), \ + mln_is_simple_window(W))" \ "BOOST_PP_LOCAL_ITERATE()=<boost/preprocessor/iteration/detail/local.hpp>" # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then diff --git a/milena/doc/DoxygenLayout.xml b/milena/doc/DoxygenLayout.xml index 05f050a..1aeee52 100644 --- a/milena/doc/DoxygenLayout.xml +++ b/milena/doc/DoxygenLayout.xml @@ -1,12 +1,9 @@ <doxygenlayout version="1.0"> + <!-- Generated by doxygen 1.8.2-20120930 --> <!-- Navigation index tabs for HTML output --> <navindex> <tab type="mainpage" visible="yes" title="Milena"/> - <tab type="pages" visible="no" title="" intro=""/> - <tab type="usergroup" url="@ref mainpage" title="Getting started"> - <tab type="user" url="@ref quickref" title="Quick Reference Guide"/> - <tab type="user" url="@ref tutorial" title="Tutorial"/> - </tab> + <tab type="pages" visible="yes" title="Getting started" intro=""/> <tab type="modules" visible="yes" title="API Reference Manual" intro=""/> <tab type="namespaces" visible="no" title=""> <tab type="namespacelist" visible="no" title="" intro=""/> diff --git a/milena/doc/Makefile.am b/milena/doc/Makefile.am index 4c83006..55ce81e 100644 --- a/milena/doc/Makefile.am +++ b/milena/doc/Makefile.am @@ -185,8 +185,8 @@ regen-split-examples-mk: REFMAN_deps = \ $(PNG_FIGURES) \ - $(srcdir)/tutorial.hh \ - $(srcdir)/ref-guide.hh + $(srcdir)/tutorial.dox \ + $(srcdir)/ref-guide.dox # ----------------------- # # User Reference Manual. # @@ -441,11 +441,7 @@ $(srcdir)/$(TUTORIAL): $(srcdir)/$(TUTORIAL).stamp DATA_html_dirs += $(TUTORIAL) # Intermediate product for the (Doxygen) User Reference Manual. -# -# This is not a bug: TUTORIAL_HH is meant to have a `.hh' extension, -# since it is later parsed by Doxygen, which complains about `.html' -# files. -TUTORIAL_HH = $(srcdir)/tutorial.hh +TUTORIAL_HH = $(srcdir)/tutorial.dox $(TUTORIAL_HH): $(srcdir)/$(TUTORIAL).stamp $(srcdir)/tools/todoxygen.sh # The script `todoxygen.sh' may fail and still create a (partial and # invalid) file, thus preventing Make from trying to generate it @@ -558,11 +554,7 @@ $(srcdir)/$(REF_GUIDE): $(srcdir)/$(REF_GUIDE).stamp DATA_html_dirs += $(REF_GUIDE) # Intermediate product for the (Doxygen) User Reference Manual. -# -# This is not a bug: REF_GUIDE_HH is meant to have a `.hh' extension, -# since it is later parsed by Doxygen, which complains about `.html' -# files. -REF_GUIDE_HH = $(srcdir)/ref-guide.hh +REF_GUIDE_HH = $(srcdir)/ref-guide.dox $(REF_GUIDE_HH): $(srcdir)/$(REF_GUIDE).stamp $(srcdir)/tools/todoxygen.sh # The script `todoxygen.sh' may fail and still create a (partial and # invalid) file, thus preventing Make from trying to generate it diff --git a/milena/doc/white-paper.tex b/milena/doc/white-paper.tex index 0120ad6..a4e9157 100644 --- a/milena/doc/white-paper.tex +++ b/milena/doc/white-paper.tex @@ -171,7 +171,7 @@ Olena's \textbf{official website}: \url{http://olena.lrde.epita.fr} Olena's \textbf{Trac}: \url{http://trac.lrde.org/olena} Milena's \textbf{documentation}: -\url{http://www.lrde.epita.fr/dload/doc/milena/user-refman-html} +\url{http://www.lrde.epita.fr/dload/olena/latest/doc/milena/user-refman-html} % \medskip -- 1.7.2.5