example_doc: tutorials

Makefile.am

@@ -77,6 +77,7 @@ include example/tetgen/Makefile.am
 include example/timings/Makefile.am
 include example/balance/Makefile.am
 include example/search/Makefile.am
+include example/tutorials/Makefile.am
 
 ## This was only used for our lint code, which needs to be replaced.
 ##

doc/Doxyfile.in

@@ -764,7 +764,7 @@ FILE_VERSION_FILTER    =
 # DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE
 # tag is left empty.
 
-LAYOUT_FILE            =
+LAYOUT_FILE            = @top_srcdir@/doc/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

doc/DoxygenLayout.xml

@@ -0,0 +1,208 @@
+<doxygenlayout version="1.0">
+  <!-- Generated by doxygen 1.8.13 -->
+  <!-- Navigation index tabs for HTML output -->
+  <navindex>
+    <tab type="mainpage" visible="yes" title="Home"/>
+    <tab type="usergroup" visible="yes" url="@ref wiki" title="Wiki" intro="">
+      <tab type="user" visible="yes" url="@ref installing_p4est" title="Installation" intro=""/>
+      <tab type="user" visible="yes" url="@ref example_simple" title="Examples" intro=""/>
+      <tab type="examples" visible="yes" title="Example Related Files" intro=""/>
+      <tab type="usergroup" visible="yes" url="@ref tutorials" title="Tutorials" intro="">
+        <tab type="user" visible="yes" url="@ref new_example" title="New Example" intro=""/>
+        <tab type="user" visible="yes" url="@ref connectivity" title="Connectivity" intro=""/>
+        <tab type="user" visible="yes" url="@ref forest" title="Forest" intro=""/>
+        <tab type="user" visible="yes" url="@ref io" title="I/O" intro=""/>
+        <tab type="user" visible="yes" url="@ref ghost" title="Ghost" intro=""/>
+        <tab type="user" visible="yes" url="@ref fe" title="FE" intro=""/>
+        <tab type="user" visible="yes" url="@ref fv" title="FV" intro=""/>
+        <tab type="user" visible="yes" url="@ref search" title="Search" intro=""/>
+        <tab type="user" visible="yes" url="@ref transfer" title="Transfer" intro=""/>
+      </tab>
+    </tab>
+    <tab type="modules" visible="yes" title="" intro=""/>
+    <tab type="namespaces" visible="yes" title="">
+      <tab type="namespacelist" visible="yes" title="" intro=""/>
+      <tab type="namespacemembers" visible="yes" title="" intro=""/>
+    </tab>
+    <tab type="classes" visible="yes" title="">
+      <tab type="classlist" visible="yes" title="" intro=""/>
+      <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
+      <tab type="hierarchy" visible="yes" title="" intro=""/>
+      <tab type="classmembers" visible="yes" title="" intro=""/>
+    </tab>
+    <tab type="files" visible="yes" title="">
+      <tab type="filelist" visible="yes" title="" intro=""/>
+      <tab type="globals" visible="yes" title="" intro=""/>
+    </tab>
+  </navindex>
+
+  <!-- Layout definition for a class page -->
+  <class>
+    <briefdescription visible="yes"/>
+    <includes visible="$SHOW_INCLUDE_FILES"/>
+    <inheritancegraph visible="$CLASS_GRAPH"/>
+    <collaborationgraph visible="$COLLABORATION_GRAPH"/>
+    <memberdecl>
+      <nestedclasses visible="yes" title=""/>
+      <publictypes title=""/>
+      <services title=""/>
+      <interfaces title=""/>
+      <publicslots title=""/>
+      <signals title=""/>
+      <publicmethods title=""/>
+      <publicstaticmethods title=""/>
+      <publicattributes title=""/>
+      <publicstaticattributes title=""/>
+      <protectedtypes title=""/>
+      <protectedslots title=""/>
+      <protectedmethods title=""/>
+      <protectedstaticmethods title=""/>
+      <protectedattributes title=""/>
+      <protectedstaticattributes title=""/>
+      <packagetypes title=""/>
+      <packagemethods title=""/>
+      <packagestaticmethods title=""/>
+      <packageattributes title=""/>
+      <packagestaticattributes title=""/>
+      <properties title=""/>
+      <events title=""/>
+      <privatetypes title=""/>
+      <privateslots title=""/>
+      <privatemethods title=""/>
+      <privatestaticmethods title=""/>
+      <privateattributes title=""/>
+      <privatestaticattributes title=""/>
+      <friends title=""/>
+      <related title="" subtitle=""/>
+      <membergroups visible="yes"/>
+    </memberdecl>
+    <detaileddescription title=""/>
+    <memberdef>
+      <inlineclasses title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <services title=""/>
+      <interfaces title=""/>
+      <constructors title=""/>
+      <functions title=""/>
+      <related title=""/>
+      <variables title=""/>
+      <properties title=""/>
+      <events title=""/>
+    </memberdef>
+    <allmemberslink visible="yes"/>
+    <usedfiles visible="$SHOW_USED_FILES"/>
+    <authorsection visible="yes"/>
+  </class>
+
+  <!-- Layout definition for a namespace page -->
+  <namespace>
+    <briefdescription visible="yes"/>
+    <memberdecl>
+      <nestednamespaces visible="yes" title=""/>
+      <constantgroups visible="yes" title=""/>
+      <classes visible="yes" title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <functions title=""/>
+      <variables title=""/>
+      <membergroups visible="yes"/>
+    </memberdecl>
+    <detaileddescription title=""/>
+    <memberdef>
+      <inlineclasses title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <functions title=""/>
+      <variables title=""/>
+    </memberdef>
+    <authorsection visible="yes"/>
+  </namespace>
+
+  <!-- Layout definition for a file page -->
+  <file>
+    <briefdescription visible="yes"/>
+    <includes visible="$SHOW_INCLUDE_FILES"/>
+    <includegraph visible="$INCLUDE_GRAPH"/>
+    <includedbygraph visible="$INCLUDED_BY_GRAPH"/>
+    <sourcelink visible="yes"/>
+    <memberdecl>
+      <classes visible="yes" title=""/>
+      <namespaces visible="yes" title=""/>
+      <constantgroups visible="yes" title=""/>
+      <defines title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <functions title=""/>
+      <variables title=""/>
+      <membergroups visible="yes"/>
+    </memberdecl>
+    <detaileddescription title=""/>
+    <memberdef>
+      <inlineclasses title=""/>
+      <defines title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <functions title=""/>
+      <variables title=""/>
+    </memberdef>
+    <authorsection/>
+  </file>
+
+  <!-- Layout definition for a group page -->
+  <group>
+    <briefdescription visible="yes"/>
+    <groupgraph visible="$GROUP_GRAPHS"/>
+    <memberdecl>
+      <nestedgroups visible="yes" title=""/>
+      <dirs visible="yes" title=""/>
+      <files visible="yes" title=""/>
+      <namespaces visible="yes" title=""/>
+      <classes visible="yes" title=""/>
+      <defines title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <enumvalues title=""/>
+      <functions title=""/>
+      <variables title=""/>
+      <signals title=""/>
+      <publicslots title=""/>
+      <protectedslots title=""/>
+      <privateslots title=""/>
+      <events title=""/>
+      <properties title=""/>
+      <friends title=""/>
+      <membergroups visible="yes"/>
+    </memberdecl>
+    <detaileddescription title=""/>
+    <memberdef>
+      <pagedocs/>
+      <inlineclasses title=""/>
+      <defines title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <enumvalues title=""/>
+      <functions title=""/>
+      <variables title=""/>
+      <signals title=""/>
+      <publicslots title=""/>
+      <protectedslots title=""/>
+      <privateslots title=""/>
+      <events title=""/>
+      <properties title=""/>
+      <friends title=""/>
+    </memberdef>
+    <authorsection visible="yes"/>
+  </group>
+
+  <!-- Layout definition for a directory page -->
+  <directory>
+    <briefdescription visible="yes"/>
+    <directorygraph visible="yes"/>
+    <memberdecl>
+      <dirs visible="yes"/>
+      <files visible="yes"/>
+    </memberdecl>
+    <detaileddescription title=""/>
+  </directory>
+</doxygenlayout>

doc/doxygen/installation.dox

@@ -0,0 +1,143 @@
+/*
+  This file is part of p4est.
+  p4est is a C library to manage a collection (a forest) of multiple
+  connected adaptive quadtrees or octrees in parallel.
+
+  Copyright (C) 2010 The University of Texas System
+  Written by Carsten Burstedde, Lucas C. Wilcox, and Tobin Isaac
+
+  p4est is free software; you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as published by
+  the Free Software Foundation; either version 2 of the License, or
+  (at your option) any later version.
+
+  p4est is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with p4est; if not, write to the Free Software Foundation, Inc.,
+  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+*/
+
+/**
+ * \page installing_p4est Installation
+ *
+ * \tableofcontents \section  install Installing p4est on Linux Systems
+ *
+ * \subsection prerequisites Prerequisites
+ * - For the installation of \p p4est, autotools are imperative. Ensure you
+ *   have:
+ *   - \p automake
+ *   - \p autoconf
+ *   - \p libtool
+ *   - \p make
+ *
+ * \subsection optional Optional Components
+ * - For enhancing parallel processing, having \p MPI is advisable.
+ *
+ * \subsection steps Step-by-step Guide
+ *
+ * \subsubsection source_retrieval 1. Source Retrieval
+ *
+ * There are a few ways you can get the source of p4est:
+ *
+ * - **Debian Linux Distribution**: If you are working with a Debian Linux
+ *   distribution , you can install `libp4est-dev` using the Debian package
+ *   manager. This provides a frozen and stable version of the code with minimal
+ *   hassle. However, contributions back to the software aren't possible in this
+ *   manner.
+ *
+ * - **Tarball**: You can obtain the latest tarball online. After unpacking it,
+ *   run `configure` and `make`. Specify an installation prefix to `configure`,
+ *   followed by `make install` to see libraries and example programs placed in
+ *   the right directories. This method provides a static, stable version of the
+ *   code.
+ *
+ * - **GitHub Repository**: For a more hands-on approach, consider cloning the
+ *   p4est GitHub repository. You'll need familiarity with the revision control
+ *   tool `git` or its GUI frontends. The branch `prev3-develop` is recommended
+ *   as it has minimized dependencies and houses the latest algorithms. To
+ *   generate the configure script, call the `./bootstrap` script in the p4est
+ *   top-level source directory. This requires a working installation of GNU
+ *   autoconf, automake, and libtool.
+ *
+ * > `git clone https://github.com/cburstedde/p4est.git`
+ *
+ * \subsubsection bootstrap 2. Bootstrap Execution
+ *
+ * Navigate to the \p p4est directory and initiate the bootstrap script,
+ * especially if you've cloned it from GitHub:
+ *
+ * > `cd p4est` `./bootstrap`
+ *
+ * \subsubsection setup 3. Setting up p4est
+ *
+ * Decide on a compilation directory. For this guide, `~/p4est_build` is used,
+ * presuming the source is in `~/p4est`:
+ *
+ * > `mkdir ~/p4est_build`
+ *
+ * > `cd ~/p4est_build`
+ *
+ * > `../p4est/configure [OPTIONS]`
+ *
+ * The \p configure script is quite versatile and has multiple options, among
+ * them:
+ * - `--enable-debug`: Activates debugging mode, increasing verbosity and turns
+ *   on `P4EST_ASSERT` for checks.
+ * - `--enable-mpi`: This integrates the mpi.h header and triggers MPI compiler
+ *   wrappers. Without this option, MPI routine wrappers are employed for serial
+ *   compilation.
+ * - `--disable-mpiio`: This avoids using `MPI_File` based calls.
+ *
+ * Additionally, the command:
+ *
+ * > `../p4est/configure --help`
+ *
+ * prints a list of currently available options to configure.
+ *
+ * A common developer-oriented configuration might resemble:
+ * > relative/path/to/configure CFLAGS="-Wall -Wuninitialized -O0 -g"
+ * > --enable-mpi --enable-debug
+ *
+ * While a production-oriented configuration could be:
+ * > relative/path/to/configure CFLAGS="-Wall -Wno-unused-but-set-variable -O2"
+ * > --enable-mpi
+ *
+ * \subsubsection compile 4. Compiling p4est After configuration, the next step
+ * is the compilation of \p p4est:
+ *
+ * > `make -j`
+ *
+ * > `make install -j`
+ *
+ * \subsubsection verification 5. Verification Step It's recommended to execute
+ * the \p p4est test programs post-installation to ensure everything is in
+ * order:
+ * > `make check`
+ *
+ * \subsubsection api_docs 6. Autogenerated API Documentation
+ *
+ * The Doxygen output for p4est and libsc can be recreated with the following
+ * command after the configuration process:
+ *
+ * > `make doxygen`
+ *
+ * \subsubsection integration 7. Integrating with p4est For projects aiming to
+ * incorporate \p p4est as an external library:
+ * > `export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/p4est_install/lib` Append to
+ * the compile command: `-I$HOME/p4est_install/include -L$HOME/p4est_install/lib
+ * -lp4est -lm`
+ *
+ * \section further Further information You may also find a detailed
+ * documentation for installation on both
+ * [Linux](https://github.com/cburstedde/p4est/blob/prev3-develop/INSTALL) and
+ * [Windows](https://github.com/cburstedde/p4est/blob/prev3-develop/INSTALL_WINDOWS)
+ * in the source folder.
+ *
+ * For users with Windows 10 version 2004 and higher, you may also try
+ * [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) as p4est works
+ * well in the subsystem.
+ */