From 88f1f82230f0caf9383a57ad3ad8d34bae83625d Mon Sep 17 00:00:00 2001 From: Anthony Scemama Date: Sat, 6 Mar 2021 14:46:01 +0100 Subject: [PATCH] Updated doc generation --- src/Makefile | 4 ---- src/README.org | 21 ++++++++++----------- src/create_doc.sh | 42 +++++++++++++++++++++++++++++++++++------- src/create_makefile.sh | 2 ++ src/merge_org.sh | 4 +++- 5 files changed, 50 insertions(+), 23 deletions(-) diff --git a/src/Makefile b/src/Makefile index f067945..7ec36ea 100644 --- a/src/Makefile +++ b/src/Makefile @@ -51,16 +51,12 @@ test: Makefile.generated doc: $(ORG_SOURCE_FILES) - ./merge_org.sh ./create_doc.sh $(MERGED_ORG) - rm $(MERGED_ORG) clean: rm -f qmckl.h test_qmckl_* test_qmckl.c test_qmckl qmckl_*.f90 qmckl_*.c qmckl_*.o qmckl_*.h Makefile.generated libqmckl.so *.html *.fh *.mod Makefile.generated: Makefile create_makefile.sh $(ORG_SOURCE_FILES) - ./merge_org.sh ./create_makefile.sh $(MERGED_ORG) - rm $(MERGED_ORG) diff --git a/src/README.org b/src/README.org index 0b47577..0bed5e0 100644 --- a/src/README.org +++ b/src/README.org @@ -4,9 +4,9 @@ #+SETUPFILE: https://fniessen.github.io/org-html-themes/org/theme-readtheorg.setup - bibliography:../docs/references.bib * Introduction + The ultimate goal of the QMCkl library is to provide a high-performance implementation of the main kernels of QMC. In this particular @@ -24,7 +24,7 @@ the prorgam is usually written in a separate directory, and is often outdated compared to the code. - Literate programming cite:knuth_1992 is a different approach to programming, + Literate programming is a different approach to programming, where the program is considered as a publishable-quality document. Most of the lines of the source files are text, mathematical formulas, tables, figures, /etc/, and the lines of code are just the translation in a computer @@ -43,13 +43,13 @@ be tested. We have chosen to write the source files in [[https://karl-voit.at/2017/09/23/orgmode-as-markup-only/][org-mode]] format, - cite:schulte_2012 as any text editor can be used to edit org-mode files. To + as any text editor can be used to edit org-mode files. To produce the documentation, there exists multiple possibilities to convert org-mode files into different formats such as HTML or PDF. The source code is easily extracted from the org-mode files invoking the Emacs text editor from the command-line in the =Makefile=, and then the produced files are compiled. Moreover, within the Emacs text editor the source code blocks can be executed - interactively, in the same spirit as Jupyter notebooks. cite:Kluyver_2016 + interactively, in the same spirit as Jupyter notebooks. ** Source code editing @@ -59,8 +59,7 @@ Any text editor can be used to edit org-mode files. For a better user experience Emacs is recommended. For users hating Emacs, it is good to know that Emacs can behave like Vim when switched into - ``Evil'' mode. There also exists [[https://www.spacemacs.org][Spacemacs]] which helps the - transition for Vim users. + ``Evil'' mode. In the =tools/init.el= file, we provide a minimal Emacs configuration file for vim users. This file should be copied into =.emacs.d/init.el=. @@ -78,10 +77,10 @@ Most of the codes of the TREX CoE are written in Fortran with some scripts in Bash and Python. Outside of the CoE, Fortran is also important (Casino, Amolqc), and other important languages used by the community are C and C++ (QMCPack, - QWalk), and Julia is gaining in popularity. cite:poole_2020 The library we - design should be compatible with all of these languages. The QMCkl API has to - be compatible with the C language since libraries with a C-compatible API can be - used in every other language. + QWalk), and Julia is gaining in popularity. The library we design should be + compatible with all of these languages. The QMCkl API has to be compatible + with the C language since libraries with a C-compatible API can be used in + every other language. High-performance versions of the QMCkl, with the same API, will be rewritten by the experts in HPC. These optimized libraries will be tuned for specific @@ -100,7 +99,7 @@ internal functions related to system programming, the C language is more natural than Fortran. - The <<>> source files should provide a C interface using the + The Fortran source files should provide a C interface using the ~iso_c_binding~ module. The name of the Fortran source files should end with =_f.f90= to be properly handled by the =Makefile=. The names of the functions defined in Fortran should be the same as those exposed in the API suffixed by diff --git a/src/create_doc.sh b/src/create_doc.sh index 39327c8..c5b092b 100755 --- a/src/create_doc.sh +++ b/src/create_doc.sh @@ -1,13 +1,41 @@ -#!/bin/bash -INPUT=$1 +#!/bin/bash -if [[ -f ../docs/htmlize.el ]] +INPUT=$1 +SRC=$PWD + + +# Install htmlize if needed +[[ -f ../docs/htmlize.el ]] || ( + cd ../docs/ + git clone https://github.com/hniksic/emacs-htmlize + cp emacs-htmlize/htmlize.el . + rm -rf emacs-htmlize + cd - +) + +[[ -f ../docs/htmlize.el ]] || exit 1 + + +# Switch to TMPDIR for easy cleanup +TMPDIR=$(mktemp -d) +./merge_org.sh $TMPDIR/$INPUT +cd $TMPDIR + + +# Create documentation +emacs --batch \ + --load ${SRC}/../docs/htmlize.el \ + --load ${SRC}/../toold/init.el \ + $INPUT -f org-html-export-to-html + +if [[ $? -eq 0 ]] then - emacs --batch --load ../docs/htmlize.el --load ../docs/config.el $INPUT -f org-html-export-to-html + rm -rf $TMPDIR + exit 0 else - emacs --batch --load ../docs/config.el $INPUT -f org-html-export-to-html + mv index.html ${SRC}/../docs/ + rm -rf $TMPDIR + exit 2 fi -mv index.html ../docs - diff --git a/src/create_makefile.sh b/src/create_makefile.sh index ee8168f..20a1ec7 100755 --- a/src/create_makefile.sh +++ b/src/create_makefile.sh @@ -1,6 +1,8 @@ #!/bin/bash INPUT=$1 +./merge_org.sh $INPUT + OUTPUT=Makefile.generated # Tangle org files diff --git a/src/merge_org.sh b/src/merge_org.sh index 41f8a41..61d182f 100755 --- a/src/merge_org.sh +++ b/src/merge_org.sh @@ -1,5 +1,7 @@ #!/bin/bash +OUTPUT=$1 + for i in README.org \ qmckl.org \ qmckl_context.org \ @@ -11,5 +13,5 @@ for i in README.org \ qmckl_footer.org \ test_qmckl.org do - cat $i >> merged_qmckl.org + cat $i >> $1 done