mirror of
https://github.com/TREX-CoE/qmckl.git
synced 2024-07-17 16:33:59 +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)
|
doc: $(ORG_SOURCE_FILES)
|
||||||
./merge_org.sh
|
|
||||||
./create_doc.sh $(MERGED_ORG)
|
./create_doc.sh $(MERGED_ORG)
|
||||||
rm $(MERGED_ORG)
|
|
||||||
|
|
||||||
|
|
||||||
clean:
|
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
|
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)
|
Makefile.generated: Makefile create_makefile.sh $(ORG_SOURCE_FILES)
|
||||||
./merge_org.sh
|
|
||||||
./create_makefile.sh $(MERGED_ORG)
|
./create_makefile.sh $(MERGED_ORG)
|
||||||
rm $(MERGED_ORG)
|
|
||||||
|
|
||||||
|
@ -4,9 +4,9 @@
|
|||||||
|
|
||||||
#+SETUPFILE: https://fniessen.github.io/org-html-themes/org/theme-readtheorg.setup
|
#+SETUPFILE: https://fniessen.github.io/org-html-themes/org/theme-readtheorg.setup
|
||||||
|
|
||||||
bibliography:../docs/references.bib
|
|
||||||
|
|
||||||
* Introduction
|
* Introduction
|
||||||
|
|
||||||
|
|
||||||
The ultimate goal of the QMCkl library is to provide a high-performance
|
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 main kernels of QMC. In this particular
|
||||||
@ -24,7 +24,7 @@
|
|||||||
the prorgam is usually written in a separate directory, and is often outdated
|
the prorgam is usually written in a separate directory, and is often outdated
|
||||||
compared to the code.
|
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
|
where the program is considered as a publishable-quality document. Most of
|
||||||
the lines of the source files are text, mathematical formulas, tables,
|
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
|
figures, /etc/, and the lines of code are just the translation in a computer
|
||||||
@ -43,13 +43,13 @@
|
|||||||
be tested.
|
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,
|
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
|
produce the documentation, there exists multiple possibilities to convert
|
||||||
org-mode files into different formats such as HTML or PDF. The source code is
|
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
|
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.
|
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
|
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
|
** Source code editing
|
||||||
@ -59,8 +59,7 @@
|
|||||||
Any text editor can be used to edit org-mode files. For a better
|
Any text editor can be used to edit org-mode files. For a better
|
||||||
user experience Emacs is recommended. For users hating Emacs, it
|
user experience Emacs is recommended. For users hating Emacs, it
|
||||||
is good to know that Emacs can behave like Vim when switched into
|
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
|
``Evil'' mode.
|
||||||
transition for Vim users.
|
|
||||||
|
|
||||||
In the =tools/init.el= file, we provide a minimal Emacs configuration
|
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=.
|
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
|
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),
|
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,
|
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
|
QWalk), and Julia is gaining in popularity. The library we design should be
|
||||||
design should be compatible with all of these languages. The QMCkl API has to
|
compatible with all of these languages. The QMCkl API has to be compatible
|
||||||
be compatible with the C language since libraries with a C-compatible API can be
|
with the C language since libraries with a C-compatible API can be used in
|
||||||
used in every other language.
|
every other language.
|
||||||
|
|
||||||
High-performance versions of the QMCkl, with the same API, will be rewritten by
|
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
|
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
|
internal functions related to system programming, the C language is more natural
|
||||||
than Fortran.
|
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
|
~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
|
=_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
|
defined in Fortran should be the same as those exposed in the API suffixed by
|
||||||
|
@ -1,13 +1,41 @@
|
|||||||
#!/bin/bash
|
#!/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
|
then
|
||||||
emacs --batch --load ../docs/htmlize.el --load ../docs/config.el $INPUT -f org-html-export-to-html
|
rm -rf $TMPDIR
|
||||||
|
exit 0
|
||||||
else
|
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
|
fi
|
||||||
|
|
||||||
mv index.html ../docs
|
|
||||||
|
|
||||||
|
|
||||||
|
@ -1,6 +1,8 @@
|
|||||||
#!/bin/bash
|
#!/bin/bash
|
||||||
|
|
||||||
INPUT=$1
|
INPUT=$1
|
||||||
|
./merge_org.sh $INPUT
|
||||||
|
|
||||||
OUTPUT=Makefile.generated
|
OUTPUT=Makefile.generated
|
||||||
|
|
||||||
# Tangle org files
|
# Tangle org files
|
||||||
|
@ -1,5 +1,7 @@
|
|||||||
#!/bin/bash
|
#!/bin/bash
|
||||||
|
|
||||||
|
OUTPUT=$1
|
||||||
|
|
||||||
for i in README.org \
|
for i in README.org \
|
||||||
qmckl.org \
|
qmckl.org \
|
||||||
qmckl_context.org \
|
qmckl_context.org \
|
||||||
@ -11,5 +13,5 @@ for i in README.org \
|
|||||||
qmckl_footer.org \
|
qmckl_footer.org \
|
||||||
test_qmckl.org
|
test_qmckl.org
|
||||||
do
|
do
|
||||||
cat $i >> merged_qmckl.org
|
cat $i >> $1
|
||||||
done
|
done
|
||||||
|
Loading…
Reference in New Issue
Block a user