mirror of
https://github.com/TREX-CoE/qmckl.git
synced 2024-08-17 02:41:43 +02:00
Updated doc generation
This commit is contained in:
parent
fd4a50ddee
commit
88f1f82230
@ -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)
|
||||
|
||||
|
@ -4,10 +4,10 @@
|
||||
|
||||
#+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
|
||||
implementation of the library, we focus on the definition of the API and the tests, and
|
||||
@ -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 <<<Fortran>>> 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
|
||||
|
@ -1,13 +1,41 @@
|
||||
#!/bin/bash
|
||||
INPUT=$1
|
||||
|
||||
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
|
||||
|
||||
|
||||
|
@ -1,6 +1,8 @@
|
||||
#!/bin/bash
|
||||
|
||||
INPUT=$1
|
||||
./merge_org.sh $INPUT
|
||||
|
||||
OUTPUT=Makefile.generated
|
||||
|
||||
# Tangle org files
|
||||
|
@ -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
|
||||
|
Loading…
Reference in New Issue
Block a user