Commit 6e0cd8a5 authored by Ben Huber's avatar Ben Huber
Browse files

make the new jekyll documentation the default

parent fdf94b53
......@@ -13,6 +13,7 @@
!*.mk
!Makefile
!.gitignore
!*.sh
......@@ -24,6 +25,7 @@
!*.dox
!*.css
!*.js
!*.yml
# ...even if they are in subdirectories
!*/
......@@ -31,6 +33,5 @@
# However we really want to ignore
lapacke/*
build/*
doc/latex/*
doc/html/*
config.mk
......@@ -6,6 +6,7 @@ help:
\t\tshared \t\t -- Build xerus as a shared library.\n \
\t\tstatic \t\t -- Build xerus as a static library.\n \
\t\tpython \t\t -- Build the xerus python wrappers.\n \
\t\tdoc \t\t -- Build the html documentation for the xerus library.\n \
\t\tinstall \t -- Install the shared library and header files (may require root).\n \
\t\ttest \t\t -- Build and run the xerus unit tests.\n \
\t\tclean \t\t -- Remove all object, library and executable files.\n"
......@@ -186,7 +187,6 @@ ifdef DESTDIR
endif
ifdef INSTALL_LIB_PATH
ifdef INSTALL_HEADER_PATH
install: shared
......@@ -223,11 +223,17 @@ fullTest: $(TUTORIALS) $(TEST_NAME)
./$(TEST_NAME) all
.FORCE:
doc: .FORCE
make -C doc doc
clean:
rm -fr build
-rm -f $(TEST_NAME)
-rm -f include/xerus.h.gch
-rm -r doc/html
benchmark: $(MINIMAL_DEPS) $(LOCAL_HEADERS) benchmark.cxx $(LIB_NAME_STATIC)
......
# ------------------------------------------------------------------------------------------------------
# Default rule should be the help message
# ------------------------------------------------------------------------------------------------------
help:
@printf "Possible make targets are:\n \
\t\thelp \t\t -- Print this help.\n \
\t\tdoc \t\t -- Build the html documentation for the xerus library.\n \
\t\tserve \t\t -- Build the html documentation for the xerus library and offer it via 'jekyll serve'.\n \
\t\tclean \t\t -- Remove all documentation files.\n"
doc:
-mkdir html
doxygen doxygen/Doxyfile
jekyll build --source jekyll/ --destination html/
clean:
-rm -r html
serve:
-mkdir html
doxygen doxygen/Doxyfile
jekyll serve --source jekyll/ --destination html/
# Building Xerus
## Obtaining Xerus
You can get the source-code of the `xerus` library via [git](https://git.hemio.de/xerus/xerus/tree/master) or as an [archiv](https://git.hemio.de/xerus/xerus/repository/archive.tar.gz?ref=master).
For example to clone the repository with the latest stable version under linux simply type
~~~
git clone https://git.hemio.de/xerus/xerus.git
~~~
## Dependencies and Configuration
`Xerus` depends on several well established libraries, usually pre-installed or available through the standard package managers. In particular `lapacke`, `CXSparse`, `binutils`
and their dependencies. Also note that at at least version 4.8 of the `GCC` is required, as this is the first version to offer support for all `C++11` functionality used in `xerus`.
Make sure that all these are installed on your system before proceeding.
E.g. to install all dependencies on a fedora system execute
~~~
dnf install gcc-c++ openblas-devel suitesparse-devel lapack-devel binutils-devel
~~~
After downloading the source it is necessary to set a number of options that are somewhat individual to your system and needs. All following build steps assume that these
options are set in the `config.mk` file. Reasonable default values can be found in the `config.mk.default` file.
In particular the optimization level is interesting and the paths or standard flags for the required libraries need to be set. This way the `xerus` library can be compiled with any
`blas` compatible library for the matrix operations. For more details see the description in the `config.mk.default`
~~~
cp config.mk.default config.mk
nano config.mk
~~~
## Making Sure Everything Works as Intended
The sources include a number of unit tests that ensure that everything works as intended. To perform them simply input
~~~
make test -j4
~~~
(where `-j4` allows make to use up to 4 threads for the compilation). If all options were set correctly in the `config.mk` it should compile a test executable and launch it.
The output of this executable should then list a number of passed tests and end with
~~~
|
| total summary 132 of 132 passed
-------------------------------------------------------------------------------
|
| Total time elapsed: 10848.406 ms
-------------------------------------------------------------------------------
~~~
Note in particular, that all tests were passed. Should this not be the case please file a bug report with as many details as you
can in our [issuetracker](https://git.hemio.de/xerus/xerus/issues) or write us an [email](mailto:contact@libxerus.org).
## Building the Library
If all tests were passed you can build the library simply by calling make
~~~
make all -j4
~~~
this creates the shared library object `libxerus.so` as well as the static library object `libxerus.a`.
If you want to install `xerus` on your system to the path given in `config.mk` simply call (as root if necessary)
~~~
make install
~~~
## Compiling your own Applications Using Xerus
If `xerus` is properly installed on your system, compiling your own applications using `xerus` is as simple as using any other library. Just include `-lxerus` in your linker call and make sure to use
`-std=c++11` or `-std=c++14` in all compilation units that include `xerus.h` and everything should work.
If you want to use the static version of `xerus` you also have to include all libraries `xerus` depends on in your linker call. In particular these are lapacke (`-llapacke`),
lapack (`-llapack`), blas (`-lblas` or `-lopenblas` or similar), suitesparse (`-lumfpack -lspqr`), binutils (`-lbfd`). On some old system one has to manually include the dependencys of binutils (`-liberty -lz -ldl`).
You can test this by trying to compile the tutorial file (in this example without the installed `xerus` library)
~~~
g++ -std=c++11 tutorials/fulltensor.cpp libxerus.a -llapacke -llapack -lcblas -lblas -lcxsparse -lbfd -liberty -lz -ldl
~~~
......@@ -51,7 +51,7 @@ PROJECT_BRIEF = "a general purpose tensor library"
# pixels and the maximum width should not exceed 200 pixels. Doxygen will copy
# the logo to the output directory.
PROJECT_LOGO = xerus.svg
PROJECT_LOGO = doxygen/xerus.svg
# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path
# into which the generated documentation will be written. If a relative path is
......@@ -437,7 +437,7 @@ EXTRACT_PACKAGE = YES
# included in the documentation.
# The default value is: NO.
EXTRACT_STATIC = NO
EXTRACT_STATIC = YES
# If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined
# locally in source files will be included in the documentation. If set to NO,
......@@ -562,7 +562,7 @@ SORT_MEMBER_DOCS = YES
# this will also influence the order of the classes in the class list.
# The default value is: NO.
SORT_BRIEF_DOCS = NO
SORT_BRIEF_DOCS = YES
# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the
# (brief and detailed) documentation of class members so that constructors and
......@@ -574,7 +574,7 @@ SORT_BRIEF_DOCS = NO
# detailed member documentation.
# The default value is: NO.
SORT_MEMBERS_CTORS_1ST = NO
SORT_MEMBERS_CTORS_1ST = YES
# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy
# of group names into alphabetical order. If set to NO the group names will
......@@ -591,7 +591,7 @@ SORT_GROUP_NAMES = NO
# list.
# The default value is: NO.
SORT_BY_SCOPE_NAME = NO
SORT_BY_SCOPE_NAME = YES
# If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to do proper
# type resolution of all parameters of a function it will reject a match between
......@@ -687,7 +687,7 @@ FILE_VERSION_FILTER =
# DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE
# tag is left empty.
LAYOUT_FILE =
LAYOUT_FILE = doxygen/DoxygenLayout.xml
# The CITE_BIB_FILES tag can be used to specify one or more bib files containing
# the reference definitions. This must be a list of .bib files. The .bib
......@@ -708,7 +708,7 @@ CITE_BIB_FILES =
# messages are off.
# The default value is: NO.
QUIET = NO
QUIET = YES
# The WARNINGS tag can be used to turn on/off the warning messages that are
# generated to standard error (stderr) by doxygen. If WARNINGS is set to YES
......@@ -740,7 +740,7 @@ WARN_IF_DOC_ERROR = YES
# parameter documentation, but not about the absence of documentation.
# The default value is: NO.
WARN_NO_PARAMDOC = NO
WARN_NO_PARAMDOC = YES
# The WARN_FORMAT tag determines the format of the warning messages that doxygen
# can produce. The string should contain the $file, $line, and $text tags, which
......@@ -768,8 +768,7 @@ WARN_LOGFILE =
# spaces.
# Note: If this tag is empty the current directory is searched.
INPUT = . \
../tutorials/ \
INPUT = doxygen/ \
../include/ \
../include/xerus/ \
../include/xerus/algorithms/ \
......@@ -815,7 +814,7 @@ RECURSIVE = NO
# Note that relative paths are relative to the directory from which doxygen is
# run.
EXCLUDE = *.hxx
EXCLUDE = *.cxx
# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
# directories that are symbolic links (a Unix file system feature) are excluded
......@@ -848,14 +847,14 @@ EXCLUDE_SYMBOLS =
# that contain example code fragments that are included (see the \include
# command).
EXAMPLE_PATH = ../tutorials/
EXAMPLE_PATH =
# If the value of the EXAMPLE_PATH tag contains directories, you can use the
# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and
# *.h) to filter out the source-files in the directories. If left blank all
# files are included.
EXAMPLE_PATTERNS = *
EXAMPLE_PATTERNS =
# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be
# searched for input files to be used with the \include or \dontinclude commands
......@@ -916,7 +915,7 @@ FILTER_SOURCE_PATTERNS =
# (index.html). This can be useful if you have a project on for instance GitHub
# and want to reuse the introduction page also for the doxygen output.
USE_MDFILE_AS_MAINPAGE = mainpage.md
USE_MDFILE_AS_MAINPAGE = doxygen/mainpage.md
#---------------------------------------------------------------------------
# Configuration options related to source browsing
......@@ -1045,7 +1044,7 @@ GENERATE_HTML = YES
# The default directory is: html.
# This tag requires that the tag GENERATE_HTML is set to YES.
HTML_OUTPUT = html
HTML_OUTPUT = html/doxygen
# The HTML_FILE_EXTENSION tag can be used to specify the file extension for each
# generated HTML page (for example: .htm, .php, .asp).
......@@ -1072,7 +1071,7 @@ HTML_FILE_EXTENSION = .html
# of the possible markers and block names see the documentation.
# This tag requires that the tag GENERATE_HTML is set to YES.
HTML_HEADER = header.html
HTML_HEADER = doxygen/header.html
# The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each
# generated HTML page. If the tag is left blank doxygen will generate a standard
......@@ -1082,7 +1081,7 @@ HTML_HEADER = header.html
# that doxygen normally uses.
# This tag requires that the tag GENERATE_HTML is set to YES.
HTML_FOOTER = footer.html
HTML_FOOTER = doxygen/footer.html
# The HTML_STYLESHEET tag can be used to specify a user-defined cascading style
# sheet that is used by each HTML page. It can be used to fine-tune the look of
......@@ -1094,7 +1093,7 @@ HTML_FOOTER = footer.html
# obsolete.
# This tag requires that the tag GENERATE_HTML is set to YES.
HTML_STYLESHEET = stylesheet.css
HTML_STYLESHEET = doxygen/stylesheet.css
# The HTML_EXTRA_STYLESHEET tag can be used to specify additional user-defined
# cascading style sheets that are included after the standard style sheets
......@@ -1107,7 +1106,7 @@ HTML_STYLESHEET = stylesheet.css
# list). For an example see the documentation.
# This tag requires that the tag GENERATE_HTML is set to YES.
HTML_EXTRA_STYLESHEET = DoxygenLayout.xml
HTML_EXTRA_STYLESHEET = doxygen/DoxygenLayout.xml
# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
# other source files which should be copied to the HTML output directory. Note
......@@ -1580,7 +1579,7 @@ EXTRA_SEARCH_MAPPINGS =
# If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output.
# The default value is: YES.
GENERATE_LATEX = YES
GENERATE_LATEX = NO
# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. If a
# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
......
......@@ -2,7 +2,8 @@
<!-- Generated by doxygen 1.8.3 -->
<!-- Navigation index tabs for HTML output -->
<navindex>
<tab type="mainpage" visible="yes" title=""/>
<tab type="user" url="/" title="Mainpage"/>
<!-- <tab type="mainpage" visible="yes" title=""/> -->
<tab type="pages" visible="yes" title="" intro=""/>
<tab type="modules" visible="yes" title="" intro=""/>
<tab type="namespaces" visible="yes" title="">
......@@ -19,7 +20,8 @@
<tab type="filelist" visible="yes" title="" intro=""/>
<tab type="globals" visible="yes" title="" intro=""/>
</tab>
<tab type="examples" visible="yes" title="" intro=""/>
<tab type="user" url="/documentation.html" title="Documentation"/>
<tab type="user" url="/examples.html" title="Examples"/>
<tab type="user" url="https://git.hemio.de/xerus/xerus" title="Git"/>
<tab type="user" url="https://git.hemio.de/xerus/xerus/issues" title="Issue-Tracker"/>
</navindex>
......
# xerus - a general purpose tensor library {#mainpage}
## Doxygen Documentation
This is the (automatically generated) Doxygen documentation for the `xerus` library. It is the only complete documentation (ie.
mentioning all classes and functions with at least a one-line description) but far less accessible than the documents of the
[main documentation](/documentation.html) or even the [examples](/examples.html).
It is advisable to use a modern IDE when working with any c++ source code, but in particular when using the `xerus` library. In
which case all of the information of this documentation should also be available from within your IDE as mouse-over text or similar.
If your IDE does not provide this functionality consider switching to `kdevelop`, `clion` or a similarly advanced IDE.
# Indices and Equations
## Blockwise Construction of Tensors
......@@ -18,3 +18,4 @@ markdown: kramdown
# gems: ['TabsConverter']
# exclude: ['README.md', 'LICENSE']
keep_files: ['doxygen']
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment