Added make doc

src/.gitignore

@@ -2,6 +2,7 @@
 *.c
 *.f90
 *.h
+*.html
 *~
 *.so
 Makefile.generated

src/Makefile

@@ -21,6 +21,9 @@ libqmckl.so: Makefile.generated
 test: Makefile.generated
 	$(MAKE) -f Makefile.generated test
 
+doc:$(ORG_SOURCE_FILES)
+	./create_doc.sh $(ORG_SOURCE_FILES)
+
 clean:
 	rm -f qmckl.h test_qmckl_* qmckl_*.f90 qmckl_*.c qmckl_*.o qmckl_*.h Makefile.generated libqmckl.so 
 

src/README.org

@@ -1,6 +1,13 @@
-* QMCkl source code
+#+TITLE: QMCkl source code documentation
 
-** Introduction
+#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="http://www.pirilampo.org/styles/readtheorg/css/htmlize.css"/>
+#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="http://www.pirilampo.org/styles/readtheorg/css/readtheorg.css"/>
+#+HTML_HEAD: <script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
+#+HTML_HEAD: <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/js/bootstrap.min.js"></script>
+#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/lib/js/jquery.stickytableheaders.js"></script>
+#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/readtheorg/js/readtheorg.js"></script>
+
+* Introduction
 
   The ultimate goal of QMCkl is to provide a high-performance
   implementation of the main kernels of QMC. In this particular
@@ -10,7 +17,7 @@
   optimized libraries.
 
   Literate programming is particularly adapted in this context.
-   Source files are written in [[ottps://karl-voit.at/2017/09/23/orgmode-as-markup-only/][org-mode]] format, to provide useful
+  Source files are written in [[https://karl-voit.at/2017/09/23/orgmode-as-markup-only/][org-mode]] format, to provide useful
   comments and LaTex formulas close to the code. There exists multiple
   possibilities to convert org-mode files into different formats such as
   HTML or pdf.
@@ -20,7 +27,7 @@
   The code is extracted from the org files using Emacs as a command-line
   tool in the =Makefile=, and then the produced files are compiled.
 
-*** Language used
+** Language used
 
    Fortran is one of the most common languages used by the community,
    and is simple enough to make the algorithms readable. Hence we
@@ -36,7 +43,7 @@
    external libraries should be used /only/ if their used is strongly
    justified.
 
-*** Source code editing
+** Source code editing
 
    Any text editor can be used to edit org-mode files. For a better
    user experience Emacs is recommended.
@@ -62,13 +69,13 @@ rm ${nb}.md
 
    And pandoc can convert multiple markdown formats into org-mode.
 
-*** Writing in Fortran
+** Writing in Fortran
 
    The Fortran source files should provide a C interface using
    iso-c-binding. The name of the Fortran source files should end
    with =_f.f90= to be properly handled by the Makefile.
 
-*** Coding style
+** Coding style
    # TODO: decide on a coding style
 
    To improve readability, we maintain a consistent coding style in the library.
@@ -78,7 +85,7 @@ rm ${nb}.md
 
    Coding style can be automatically checked with [[https://clang.llvm.org/docs/ClangFormat.html][clang-format]].
 
-** Design of the library
+* Design of the library
 
   The proposed API should allow the library to:
   - deal with memory transfers between CPU and accelerators
@@ -87,7 +94,7 @@ rm ${nb}.md
   We chose a multi-layered design with low-level and high-level
   functions (see below).
 
-*** Naming conventions
+** Naming conventions
 
    Use =qmckl_= as a prefix for all exported functions and variables.
    All exported header files should have a filename with the prefix
@@ -97,7 +104,7 @@ rm ${nb}.md
    produced C files should be =xxx.c= and =xxx.h= and the name of the
    produced Fortran files should be =xxx.f90=
 
-*** Application programming interface
+** Application programming interface
 
    The application programming interface (API) is designed to be
    compatible with the C programming language (not C++), to ensure
@@ -116,7 +123,7 @@ rm ${nb}.md
 
    # TODO : Link to repositories for bindings
 
-*** Global state
+** Global state
 
    Global variables should be avoided in the library, because it is
    possible that one single program needs to use multiple instances of
@@ -137,7 +144,7 @@ rm ${nb}.md
    The context and its old versions can be destroyed with
  =qmckl_context_destroy=.
 
-*** Low-level functions
+** Low-level functions
 
    Low-level functions are very simple functions which are leaves of the
    function call tree (they don't call any other QMCkl function).
@@ -146,7 +153,7 @@ rm ${nb}.md
    not allowed to allocate/deallocate memory, and if they need
    temporary memory it should be provided in input.
 
-*** High-level functions
+** High-level functions
 
    High-level functions are at the top of the function call tree.
    They are able to choose which lower-level function to call
@@ -161,7 +168,7 @@ rm ${nb}.md
 
    # TODO : We need an identifier for impure functions
 
-*** Numerical precision
+** Numerical precision
 
    The number of bits of precision required for a function should be
    given as an input of low-level computational functions. This input will
@@ -170,7 +177,7 @@ rm ${nb}.md
    High-level functions will use the precision specified in the
  =context= variable.
 
-** Algorithms
+* Algorithms
 
   Reducing the scaling of an algorithm usually implies also reducing
   its arithmetic complexity (number of flops per byte). Therefore,
@@ -180,21 +187,21 @@ rm ${nb}.md
   be implemented adapted to different problem sizes.
 
    
-** Rules for the API
+* Rules for the API
    
   - =stdint= should be used for integers (=int32_t=, =int64_t=)
   - integers used for counting should always be =int64_t=
   - floats should be by default =double=, unless explicitly mentioned 
   - pointers are converted to =int64_t= to increase portability
 
-** Documentation
+* Documentation
 
-- [[qmckl.org][Main QMCkl header file]]
+  - [[./qmckl.org][Main QMCkl header file]]
-- [[qmckl_memory.org][Memory management]]
+  - [[./qmckl_memory.org][Memory management]]
-- [[qmckl_context.org][Context]]
+  - [[./qmckl_context.org][Context]]
-- [[qmckl_distance.org][Distance]]
+  - [[./qmckl_distance.org][Distance]]
 
-** Acknowledgments
+* Acknowledgments
 
-[[https://trex-coe.eu/sites/default/files/inline-images/euflag.jpg]]
+  [[https://trex-coe.eu/sites/default/files/inline-images/euflag.jpg]]
-[[https://trex-coe.eu][TREX: Targeting Real Chemical Accuracy at the Exascale]] project has received funding from the European Union’s Horizon 2020 - Research and Innovation program - under grant agreement no. 952165. The content of this document does not represent the opinion of the European Union, and the European Union is not responsible for any use that might be made of such content.
+  [[https://trex-coe.eu][TREX: Targeting Real Chemical Accuracy at the Exascale]] project has received funding from the European Union’s Horizon 2020 - Research and Innovation program - under grant agreement no. 952165. The content of this document does not represent the opinion of the European Union, and the European Union is not responsible for any use that might be made of such content.

src/create_doc.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+
+# Tangle org files
+
+emacsclient -a "" \
+            --socket-name=org_to_code \
+            --eval "(require 'org)"
+
+for INPUT in $@ ; do
+    echo $INPUT
+    emacsclient \
+	--no-wait \
+	--socket-name=org_to_code \
+     	--eval "(find-file \"$INPUT\")" \
+     	--eval "(org-html-export-to-html)"
+done
+
+emacsclient \
+    --no-wait \
+    --socket-name=org_to_code \
+    --eval '(kill-emacs)'
+

src/qmckl.org

@@ -2,6 +2,13 @@
 # vim: syntax=c
 #+TITLE: QMCkl C header
 
+#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="http://www.pirilampo.org/styles/readtheorg/css/htmlize.css"/>
+#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="http://www.pirilampo.org/styles/readtheorg/css/readtheorg.css"/>
+#+HTML_HEAD: <script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
+#+HTML_HEAD: <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/js/bootstrap.min.js"></script>
+#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/lib/js/jquery.stickytableheaders.js"></script>
+#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/readtheorg/js/readtheorg.js"></script>
+
 This file produces the =qmckl.h= header file, which is included in all
 other C header files. It is the main entry point to the library.
 

src/qmckl_context.org

@@ -2,6 +2,14 @@
 # vim: syntax=c
 #+TITLE: Context
 
+#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="http://www.pirilampo.org/styles/readtheorg/css/htmlize.css"/>
+#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="http://www.pirilampo.org/styles/readtheorg/css/readtheorg.css"/>
+#+HTML_HEAD: <script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
+#+HTML_HEAD: <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/js/bootstrap.min.js"></script>
+#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/lib/js/jquery.stickytableheaders.js"></script>
+#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/readtheorg/js/readtheorg.js"></script>
+
+
 This file is written in C because it is more natural to express the context in
 C than in Fortran.
 
@@ -36,7 +44,7 @@ MunitResult test_qmckl_context() {
   outside of the library. To simplify compatibility with other
   languages, the pointer to the internal data structure is converted
   into a 64-bit signed integer, defined in the =qmckl_context= type.
-  A value of 0 for the context is equivalent to a NULL pointer.
+  A value of 0 for the context is equivalent to a =NULL= pointer.
 
 *** Source
     #+BEGIN_SRC C :comments link :tangle qmckl_context.c

src/qmckl_distance.org

@@ -2,6 +2,13 @@
 # vim: syntax=c
 #+TITLE: Computation of distances
 
+#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="http://www.pirilampo.org/styles/readtheorg/css/htmlize.css"/>
+#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="http://www.pirilampo.org/styles/readtheorg/css/readtheorg.css"/>
+#+HTML_HEAD: <script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
+#+HTML_HEAD: <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/js/bootstrap.min.js"></script>
+#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/lib/js/jquery.stickytableheaders.js"></script>
+#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/readtheorg/js/readtheorg.js"></script>
+
 Function for the computation of distances between particles.
 
 3 files are produced:
@@ -65,7 +72,7 @@ MunitResult test_qmckl_distance() {
    Computes the matrix of the squared distances between all pairs of
    points in two sets, one point within each set:
    \[
-   C_{ij^2} = \sum_{k=1}^3 (A_{i,k}-B_{j,k})^2
+   C_{ij} = \sum_{k=1}^3 (A_{i,k}-B_{j,k})^2
    \]
 
 *** Arguments

src/qmckl_memory.org

@@ -2,6 +2,14 @@
 # vim: syntax=c
 #+TITLE: Memory management
 
+#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="http://www.pirilampo.org/styles/readtheorg/css/htmlize.css"/>
+#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="http://www.pirilampo.org/styles/readtheorg/css/readtheorg.css"/>
+#+HTML_HEAD: <script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
+#+HTML_HEAD: <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/js/bootstrap.min.js"></script>
+#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/lib/js/jquery.stickytableheaders.js"></script>
+#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/readtheorg/js/readtheorg.js"></script>
+
+
 We override the allocation functions to enable the possibility of
 optimized libraries to fine-tune the memory allocation.
 
@@ -10,34 +18,34 @@ optimized libraries to fine-tune the memory allocation.
 - a source file : =qmckl_memory.c=
 - a test   file : =test_qmckl_memory.c=
 
-*** Header 
+** Header
    #+BEGIN_SRC C :comments link  :tangle qmckl_memory.h
 #ifndef QMCKL_MEMORY_H
 #define QMCKL_MEMORY_H
 #include "qmckl.h"
    #+END_SRC
 
-*** Source
+** Source
    #+BEGIN_SRC C :comments link :tangle qmckl_memory.c
 #include <stdlib.h>
 #include "qmckl_memory.h"
    #+END_SRC
 
-*** Test
+** Test
    #+BEGIN_SRC C :comments link :tangle test_qmckl_memory.c
 #include "qmckl.h"
 #include "munit.h"
 MunitResult test_qmckl_memory() {
    #+END_SRC
 
-** =qmckl_malloc=
+* =qmckl_malloc=
  Analogous of =malloc, but passing a context and a signed 64-bit integers as argument.=
-*** Header
+** Header
    #+BEGIN_SRC C :comments link :tangle qmckl_memory.h
 void* qmckl_malloc(const qmckl_context ctx, const size_t size);
    #+END_SRC
 
-*** Source
+** Source
    #+BEGIN_SRC C :comments link :tangle qmckl_memory.c
 void* qmckl_malloc(const qmckl_context ctx, const size_t size) {
   if (ctx == (qmckl_context) 0) {
@@ -49,7 +57,7 @@ void* qmckl_malloc(const qmckl_context ctx, const size_t size) {
 
    #+END_SRC
 
-*** Test
+** Test
    #+BEGIN_SRC C :comments link :tangle test_qmckl_memory.c
   int *a;
   a = (int*) qmckl_malloc( (qmckl_context) 1, 3*sizeof(int));
@@ -61,33 +69,33 @@ void* qmckl_malloc(const qmckl_context ctx, const size_t size) {
   munit_assert_int(a[2], ==, 3);
    #+END_SRC
 
-** =qmckl_free=
+* =qmckl_free=
 
-*** Header
+** Header
    #+BEGIN_SRC C :comments link :tangle qmckl_memory.h
 void qmckl_free(void *ptr);
    #+END_SRC
 
-*** Source
+** Source
    #+BEGIN_SRC C :comments link :tangle qmckl_memory.c
 void qmckl_free(void *ptr) {
   free(ptr);
 }
    #+END_SRC
 
-*** Test
+** Test
    #+BEGIN_SRC C :comments link :tangle test_qmckl_memory.c
   qmckl_free(a);
    #+END_SRC
 
 * End of files
 
-*** Header
+** Header
  #+BEGIN_SRC C :comments link :tangle qmckl_memory.h
 #endif
  #+END_SRC
 
-*** Test
+** Test
  #+BEGIN_SRC C :comments link :tangle test_qmckl_memory.c
   return MUNIT_OK;
 }

src/test_qmckl.org

@@ -1,5 +1,12 @@
 #+TITLE: QMCkl test
 
+#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="http://www.pirilampo.org/styles/readtheorg/css/htmlize.css"/>
+#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="http://www.pirilampo.org/styles/readtheorg/css/readtheorg.css"/>
+#+HTML_HEAD: <script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
+#+HTML_HEAD: <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/js/bootstrap.min.js"></script>
+#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/lib/js/jquery.stickytableheaders.js"></script>
+#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/readtheorg/js/readtheorg.js"></script>
+
 This file is the main program of the unit tests. The tests rely on the
 $\mu$unit framework, which is provided as a git submodule.