Restructuring documentation.

A first general restructuration of the doc according to the pattern [tour|tutorial|reference].
In the reference part, objects are documented per topic.
In each topic, [definition|c++|python|hdf5] (not yet implemented)

doc/CMakeLists.txt

@@ -53,8 +53,9 @@ ENDFOREACH()
 endmacro()
 
 # Dive and find the doxygen sources
-add_subdirectory(reference/c++)
+add_subdirectory(reference/)
-add_subdirectory(tutorials/c++)
+add_subdirectory(tutorials/)
+add_subdirectory(tour/)
 
 # Build the doxygen 
 set(DOXYGEN_HTML_OUTPUT ./html/doxy_triqs)

doc/documentation.rst

@@ -6,22 +6,68 @@ Documentation
 A quick tour
 ------------
 
+A little tour of some aspects of TRIQS and its applications, at the Python level. 
+
 .. toctree::
    :maxdepth: 1
 
-   tutorials/python/contents
+   tour/getting_started/get_started
-   tutorials/c++/contents
+   tour/green
+   tour/tight_binding
+   tour/ctqmc
+   tour/dmft
+   tour/ipt
+
+
+Tutorials
+----------
+
+Learn how to use TRIQS step by step, both in Python and c++ !
+
+.. toctree::
+   :maxdepth: 1
+
+   tutorials/gfs_tutorial
+   tutorials/array_tutorial
+   tutorials/det_manip_tutorial
+
 
 Reference manual 
 -----------------
 
-This is the reference manual for the Python and the C++ libraries.
+.. toctree::
+   :maxdepth: 1
+
+   reference/using_the_lib/contents
+
+Code reference
+~~~~~~~~~~~~~~~~
+.. toctree::
+   :maxdepth: 1
+
+   reference/gfs/contents
+   reference/lattice_tools/contents
+   reference/plotting_protocols/contents
+   reference/montecarlo/contents
+   reference/operators/contents
+   reference/random_generator/contents
+   reference/arrays/contents
+   reference/clef/contents
+   reference/hdf5/contents
+   reference/determinant_manipulation/contents
+   reference/statistical_analysis/contents
+
+
+Developer tools
+~~~~~~~~~~~~~~~~~
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
-   reference/python/contents
+   reference/conventions
-   reference/c++/contents
+   reference/using_the_lib/profiling
+   reference/wrap_generator/contents
+   reference/utilities/contents
 
 Version compatibility
 ---------------------

doc/reference/CMakeLists.txt

@@ -1,4 +1 @@
-
 add_all_subdirectories_with_cmakelist()
-
-

doc/reference/c++/contents.rst

@@ -1,22 +0,0 @@
-
-C++
-=============
-
-.. warning::
-
-   This documentation is work in progress.
-
-.. toctree::
-   :maxdepth: 1
-
-   conventions
-   using_the_lib/contents
-   arrays/contents
-   gf/contents
-   clef/contents
-   mctools/intro
-   det_manip/contents
-   parameters/parameters
-   statistics/contents
-   utilities/contents
-   using_the_lib/profiling

doc/reference/c++/parameters/CMakeLists.txt

@@ -1,5 +0,0 @@
-# Doxygen sources
-set_property(GLOBAL APPEND PROPERTY DOXYGEN_SOURCES ${TRIQS_SOURCE_DIR}/triqs/parameters/parameters.hpp)
-
-all_tests()
-

doc/reference/c++/parameters/parameters.rst

@@ -1,141 +0,0 @@
-Parameters
-===============
-
-.. warning::
-
-   Library of beta quality.
-
-   Documentation : just intro/tutorial, reference doc in progress.
-
-
-Introduction
---------------
-
-The purpose of the class parameters is to handle program input parameters.
-It provides a convenient way to pass several parameters of different types to a program.
-
-Parameters can be stored in a parameters object and accessed in a manner which is reminiscent of a Python dict:
-
-.. code-block:: c
-   
-   parameters P;
-   P["x"] = 3.14;
-   y = P["x"];
-
-In Python the syntax is similar:
-
-.. code-block:: python
-
-   import parameters as params
-   
-   P = params.Parameters()
-   P['x'] = 3.14
-   y = P['x']
-   
-The class implements the following features:
-
-* storage of parameters of any type, including arrays
-* C-like cast operations, such as integral type to double conversion as well as lexical cast to arithmetic types
-* Python interface
-* type checking
-* hdf5 I/O operations
-* write contents to std::ostream
-* the class is boost-serializable
-
-parameter_defaults
------------------------------
-
-When parameters are used within a program, a number of them are usually optional, in
-the sense that they need not be provided by the user. This either means that the program 
-can run without them, or meaningful default values can be provided.
-
-Other parameters, on the other hand, may be required to be provided by the user.
-These typically are parameters for which one cannot provide meaningful default values.
-
-These cases can be handled in a consistent manner using the parameter_defaults class. 
-
-An object of this class allows to specify the name, type and documentation for all
-required and optional parameters. Default values are provided for optional parameters:
-
-.. code-block:: c
-   
-   parameter_defaults pdef;
-   pdef.required("Beta", double(), "Inverse temperature")
-       .optional("N_time", int(100), "Number of time points")
-       .optional("N_freq", int(200), "Number of frequencies")
-    ; 
-
-The default_parameters object serves two main purposes: Firstly, the input parameters can
-be checked for completeness and correctness, i.e. they can be checked if all required parameters
-are provided and have correct type.
-
-Secondly, the optional parameters provided through the input parameters can be checked whether they
-have correct type. Those which are not provided can be added to the input parameter set with
-their respective default values.
-Both steps are performed through the update method of the parameter class:
-
-.. code-block:: c
-   
-   parameters P;
-   P["Beta"] = 3.14;
-   P.update(pdef);
-
-Given that the parameter_defaults are complete, the resulting parameter object contains all
-parameters that the program will eventually access.
-
-Finally, the information stored in the defaults can be used to generate the help of the program,
-by printing a list of its parameters:
-
-.. code-block:: c
-   
-   std::cout<<pdef<<std::endl;
-
-See below for more detailed working code examples.
-
-For detailed information on how to use the parameter and parameter_defaults classes within a program, refer to the **TRIQS solver coding guidelines**.
-
-Headers
---------------
-The parameter class and the parameter_defaults class are declared in the header
-
-  triqs/utility/parameters.hpp
-
-Doxygen documentation
--------------------------
-
-The :doxy:`full C++ parameter documentation<triqs::utility::parameters>` and
-the :doxy:`parameter_defaults documentation<triqs::utility::parameter_defaults>` are available here.
-
-Parameter example  
--------------
-
-.. triqs_example:: ./parameters_0.cpp
-Parameter default value example
--------------
-
-.. triqs_example:: ./parameters_1.cpp
-Python example
--------------
-
-.. code-block:: python
-   
-   import parameters as params
-
-   P = params.Parameters()
-   P['num'] = 2.3 
-   P['str'] = "hello world"
-   print P
-   
-   dct = { 'a' : 10, 'b' : "a string"}
-   P.update(dct) # update from a dictionary
-   print P
-   
-   import numpy as np
-   a = np.array([[1,2],[3,4]])
-   P['A'] = a # add an array
-   print P
-   
-   P.update2( c = 4, d= "u") # update from an initializer list
-   print P
-
-  

doc/reference/c++/parameters/parameters_0.cpp

@@ -1,28 +0,0 @@
-#include <triqs/parameters.hpp>
-using triqs::params::parameters;
-#include <triqs/arrays.hpp>
-
-int main() {
-
- parameters P;
-/*
- P["a"] = long(1);
- P["d"] = 2.7;
- P["a_string"] = std::string("-14.3");
- P["char_string"] = "-14.3";
-
- triqs::arrays::array<double, 2> A(2, 2);
- A() = 0;
- A(0, 0) = 1.3;
- A(1, 1) = -8.2;
- P["A"] = A;
- std::cout << "A:" << P["A"] << std::endl;
-
- long a = P["a"];
- double x = P["a"];        // cast to double from long
- double y = P["a_string"]; // lexical cast to double from string
- std::cout << y << std::endl;
-*/
- return 0;
-}
-

doc/reference/c++/parameters/parameters_1.cpp

@@ -1,19 +0,0 @@
-#include <triqs/parameters.hpp>
-using triqs::params::parameters;
-
-int main() {
-/*
- parameters P;
- P["Beta"] = 3.14;
-
- parameter_defaults pdef;
- pdef.required("Beta", double(), "Inverse temperature").optional("Alpha", int(1000), "An integer").optional("Gamma", double(0.9),
-                                                                                                            "A double");
-
- std::cout << pdef << std::endl; // print a comprehensive list of parameters:
- std::cout << P << std::endl;
- P.update(pdef); // check whether required parameters are present and update optional ones
- std::cout << P << std::endl;
-*/
-}
-