From 0b7bfec32e71e80517fa1b106d3217da7f5d07cf Mon Sep 17 00:00:00 2001 From: Olivier Parcollet Date: Sun, 3 Nov 2013 18:56:55 +0100 Subject: [PATCH] Work on doc. --- cmake/Doxyfile.in | 10 +++--- doc/conf.py.in | 17 +++++----- doc/installation/osx_lion.rst | 13 ++++++-- doc/installation/requirements.rst | 43 ++++++++++++------------- doc/reference/c++/arrays/CMakeLists.txt | 1 + doc/reference/c++/arrays/H5.rst | 10 ++++-- doc/reference/c++/arrays/h5_stack.rst | 11 ++++++- doc/reference/c++/mctools/reference.rst | 14 ++++---- 8 files changed, 72 insertions(+), 47 deletions(-) diff --git a/cmake/Doxyfile.in b/cmake/Doxyfile.in index 7dc83a2d..e69e928f 100644 --- a/cmake/Doxyfile.in +++ b/cmake/Doxyfile.in @@ -98,7 +98,7 @@ ALWAYS_DETAILED_SEC = NO # members were ordinary class members. Constructors, destructors and assignment # operators of the base classes will not be shown. -INLINE_INHERITED_MEMB = NO +INLINE_INHERITED_MEMB = YES # If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full # path before files name in the file list and in the header files. If set @@ -521,7 +521,7 @@ EXCLUDE_PATTERNS = # The symbol name can be a fully qualified name, a word, or if the wildcard * is used, # a substring. Examples: ANamespace, AClass, AClass::ANamespace, ANamespace::*Test -EXCLUDE_SYMBOLS = *::*details::*, *impl* +EXCLUDE_SYMBOLS = *::*details::* # The EXAMPLE_PATH tag can be used to specify one or more files or # directories that contain example code fragments that are included (see @@ -1049,7 +1049,7 @@ INCLUDE_FILE_PATTERNS = # undefined via #undef or recursively expanded use the := operator # instead of the = operator. -PREDEFINED = +PREDEFINED = TRIQS_DOXYGEN # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then # this tag can be used to specify a list of macro names that should be expanded. @@ -1121,7 +1121,7 @@ PERL_PATH = /usr/bin/perl # fallback. It is recommended to install and use dot, since it yields more # powerful graphs. -CLASS_DIAGRAMS = YES +CLASS_DIAGRAMS = NO # You can define message sequence charts within doxygen comments using the \msc # command. Doxygen will then run the mscgen tool (see http://www.mcternan.me.uk/mscgen/) to @@ -1149,7 +1149,7 @@ HAVE_DOT = NO # indirect inheritance relations. Setting this tag to YES will force the # the CLASS_DIAGRAMS tag to NO. -CLASS_GRAPH = YES +CLASS_GRAPH = NO # If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen # will generate a graph for each documented class showing the direct and diff --git a/doc/conf.py.in b/doc/conf.py.in index 59e6b126..d8644264 100644 --- a/doc/conf.py.in +++ b/doc/conf.py.in @@ -21,14 +21,15 @@ import sys, os # General configuration # --------------------- -sys.path +=["@CMAKE_BINARY_DIR@/doc/breathe", +sys.path +=[ #"@CMAKE_BINARY_DIR@/doc/breathe", "@CMAKE_BINARY_DIR@/doc/mpl","@CMAKE_BINARY_DIR@/doc/autocompile", "@CMAKE_BINARY_DIR@/doc/sandbox","@CMAKE_BINARY_DIR@/doc"] # 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.pngmath'] -extensions = ['sphinx.ext.autodoc','sphinx.ext.@SPHINX_MATH_GENERATOR@','breathe','doxylink'] +#extensions = ['sphinx.ext.autodoc','sphinx.ext.@SPHINX_MATH_GENERATOR@','breathe','sphinxcontrib.doxylink'] +extensions = ['sphinx.ext.autodoc','sphinx.ext.@SPHINX_MATH_GENERATOR@','sphinxcontrib.doxylink'] # adding support for matplotlib plots extensions += [ @@ -121,12 +122,12 @@ pygments_style = 'sphinx' # Options for breathe extension # ----------------------------- -breathe_projects = { - "mc_tools":"@CMAKE_CURRENT_BINARY_DIR@/xml/", - "arrays":"@CMAKE_CURRENT_BINARY_DIR@/xml/", - } - -breathe_default_project = "mc_tools" +#breathe_projects = { +# "mc_tools":"@CMAKE_CURRENT_BINARY_DIR@/xml/", +# "arrays":"@CMAKE_CURRENT_BINARY_DIR@/xml/", +# "doxy":"@CMAKE_CURRENT_BINARY_DIR@/xml/", +# } +#breathe_default_project = "mc_tools" # Options for doxylink extension # ----------------------------- diff --git a/doc/installation/osx_lion.rst b/doc/installation/osx_lion.rst index 0befc0b4..04755a23 100644 --- a/doc/installation/osx_lion.rst +++ b/doc/installation/osx_lion.rst @@ -7,15 +7,22 @@ Installing required libraries on Mac OS X ========================================= -This installation guide has been tried on Mountain Lion. It may work for older +This is an installation guide for Os X Mountain Lion. +It may work for older versions of Mac OS X but previous versions of Mac OS X are not supported. NB: The installation of TRIQS under previous versions of OS X requires installing clang (via Xcode). -(On Mountain Lion, clang (llvm) replaces gcc 4.2 as the default C++ compiler). +(On Mountain Lion, clang (llvm) replaces gcc as the default C++ compiler). We strongly recommend the following installation procedure, which provides a clean way to set up all dependencies, so that all of them are compatible with each other. Only the installation via homebrew is supported for the Mac. +.. warning:: + + Because brew evolve with time, there is no notion of distribution on Mac, like e.g. Ubuntu. + So, while the procedure worked at some point, there can be no guarantee that it still does. + + Installation of the dependencies -------------------------------- @@ -50,6 +57,8 @@ Installation of the dependencies pip install scipy pip install mpi4py pip install matplotlib + pip install breathe + pip install sphinxcontrib-doxylink pip install tornado pip install pyzmq pip install jinja2 diff --git a/doc/installation/requirements.rst b/doc/installation/requirements.rst index d2eddcea..c1beb455 100644 --- a/doc/installation/requirements.rst +++ b/doc/installation/requirements.rst @@ -42,26 +42,25 @@ A recent compiler is therefore mandatory. Libraries --------- -================== ================ ================================================================================ -Library/tool Version Comment -================== ================ ================================================================================ -mpi openmpi Parallelism. - Since standard linux distributions (and macports on OS X) - now provides openmpi, even on laptops, we avoid the unnecessary complication - of maintaining a non-parallel version of TRIQS -fftw >= 3.2 Fourier transforms -boost >= 1.49 C++ librairies -hdf5 >= 1.8.0 File storage system. Important: the *serial* version must be installed -python >= 2.6.5 The Python interpreter -scipy Python mathematical library -numpy Python scientific library -h5py Python interface to hdf5 library -mpi4py Python MPI -sphinx >= 1.0.1 Python documentation tools (to compile documentation) -cmake >= 2.8.7 CMake is used to control the software compilation process -pyparsing Tool for sphinx (to compile documentation) -matplotlib >= 0.99 Python 2D plotting library -cython >=0.17 A language that allows to write C extensions for the Python language -================== ================ ================================================================================ - ++------------------------+----------+------------------------------------------------------------------------+ +| Library/tool | Version | Comment | ++========================+==========+========================================================================+ +| mpi | openmpi | Parallelism (1). | +| fftw | >= 3.2 | Fourier transforms | +| boost | >= 1.49 | C++ librairies | +| hdf5 | >= 1.8.0 | File storage system. Important: the *serial* version must be installed | +| python | >= 2.6.5 | The Python interpreter | +| scipy | >= ? | Python mathematical library | +| numpy | >= ? | Python scientific library | +| h5py | >= ? | Python interface to hdf5 library | +| mpi4py | >= ? | Python MPI | +| sphinx | >= 1.0.1 | Python documentation tools (to compile documentation) | +| cmake | >= 2.8.7 | CMake is used to control the software compilation process | +| pyparsing | >= ? | Tool for sphinx (to compile documentation) | +| sphinxcontrib-doxylink | >= ? | Tool for sphinx (to compile documentation) | +| matplotlib | >= 0.99 | Python 2D plotting library | +| cython | >=0.17 | A language that allows to write C extensions for the Python language | ++------------------------+----------+------------------------------------------------------------------------+ +(1) Since standard linux distributions (and macports on OS X) now provides openmpi, even on laptops, we avoid the unnecessary complication of maintaining a non-parallel version of TRIQS + diff --git a/doc/reference/c++/arrays/CMakeLists.txt b/doc/reference/c++/arrays/CMakeLists.txt index 41ea718d..fc43772c 100644 --- a/doc/reference/c++/arrays/CMakeLists.txt +++ b/doc/reference/c++/arrays/CMakeLists.txt @@ -2,6 +2,7 @@ set_property(GLOBAL APPEND PROPERTY DOXYGEN_SOURCES ${TRIQS_SOURCE_DIR}/triqs/arrays/h5/simple_read_write.hpp ${TRIQS_SOURCE_DIR}/triqs/arrays/h5/array_stack.hpp + ${TRIQS_SOURCE_DIR}/triqs/h5/group.hpp ${TRIQS_SOURCE_DIR}/triqs/arrays/array.hpp ${TRIQS_SOURCE_DIR}/triqs/arrays/matrix.hpp ${TRIQS_SOURCE_DIR}/triqs/arrays/vector.hpp diff --git a/doc/reference/c++/arrays/H5.rst b/doc/reference/c++/arrays/H5.rst index 22ba3b40..aeb88ae3 100644 --- a/doc/reference/c++/arrays/H5.rst +++ b/doc/reference/c++/arrays/H5.rst @@ -18,10 +18,16 @@ Reference h5_rw h5_stack - h5_proxy h5_complex -You can also get the :doxy:`full C++ documentation` for these classes and functions. +You can also get the :doxy:`full C++ documentation` for these classes and functions. +.. : + Breathe Documentation + ********************* + .. doxygenclass:: triqs::h5::group + :project: doxy + :members: + diff --git a/doc/reference/c++/arrays/h5_stack.rst b/doc/reference/c++/arrays/h5_stack.rst index 950f8e90..a6481ec2 100644 --- a/doc/reference/c++/arrays/h5_stack.rst +++ b/doc/reference/c++/arrays/h5_stack.rst @@ -24,8 +24,17 @@ It is typically used to store a Monte-Carlo data series for later analysis. Reference ------------ -Here is the :doxy:`full C++ documentation` for this class. +Here is the :doxy:`full C++ documentation` for this class. +.. : + Breathe Documentation + -------------------------- + + .. doxygenclass:: triqs::arrays::array_stack + :project: arrays + :members: + + Tutorial ----------- diff --git a/doc/reference/c++/mctools/reference.rst b/doc/reference/c++/mctools/reference.rst index 9f3b1d85..952162b9 100644 --- a/doc/reference/c++/mctools/reference.rst +++ b/doc/reference/c++/mctools/reference.rst @@ -73,10 +73,10 @@ Doxygen documentation The :doxy:`full C++ documentation` is available here. -.. : - Breathe Documentation - ********************* - .. doxygenclass:: triqs::mc_tools::mc_generic - :project: doxy - :members: - + +Breathe Documentation +********************* +.. doxygenclass:: triqs::mc_tools::mc_generic + :project: mc_tools + :members: +