From 126bfd72ed58bfe104450efbfbd6116567b2aa1f Mon Sep 17 00:00:00 2001
From: Gennady Pospelov <g.pospelov@fz-juelich.de>
Date: Wed, 5 Nov 2014 18:20:55 +0100
Subject: [PATCH] Sphinx: faq and troubleshooting section.
---
Doc/Sphinx/documentation/documentation.rst | 13 +++++-
Doc/Sphinx/documentation/faq/faq.rst | 28 ++++++++++++
.../installation/installation.rst | 2 +-
.../installation/installation_unix.rst | 2 +-
.../installation_unix_detailed.rst | 1 +
.../installation/installation_unix_gui.rst | 12 ++++-
.../installation/installation_unix_short.rst | 9 ++++
.../troubleshooting/troubleshooting.rst | 26 +++++++++++
.../troubleshooting_installation_unix.rst | 45 +++++++++++++++++++
.../working_with_bornagain/using_gui.rst | 2 +-
10 files changed, 133 insertions(+), 7 deletions(-)
create mode 100644 Doc/Sphinx/documentation/faq/faq.rst
create mode 100644 Doc/Sphinx/documentation/troubleshooting/troubleshooting.rst
create mode 100644 Doc/Sphinx/documentation/troubleshooting/troubleshooting_installation_unix.rst
diff --git a/Doc/Sphinx/documentation/documentation.rst b/Doc/Sphinx/documentation/documentation.rst
index 87e9255a0bd..88a192e54d7 100644
--- a/Doc/Sphinx/documentation/documentation.rst
+++ b/Doc/Sphinx/documentation/documentation.rst
@@ -1,6 +1,6 @@
Documentation
-=============================
+#############################
.. toctree::
@@ -11,5 +11,14 @@ Documentation
installation/installation.rst
working_with_bornagain/working_with_bornagain.rst
python_api/python_api.rst
+
+
+.. toctree::
+ :maxdepth: 1
+
+ troubleshooting/troubleshooting.rst
+
+.. toctree::
+ :maxdepth: 1
-
\ No newline at end of file
+ faq/faq.rst
diff --git a/Doc/Sphinx/documentation/faq/faq.rst b/Doc/Sphinx/documentation/faq/faq.rst
new file mode 100644
index 00000000000..0f07e563a3a
--- /dev/null
+++ b/Doc/Sphinx/documentation/faq/faq.rst
@@ -0,0 +1,28 @@
+
+Frequently Asked Questions
+################################
+
+
+.. contents::
+ :depth: 1
+ :local:
+ :backlinks: none
+
+
+How to request the new feature?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Create feature request using `BornAgain Bug and Issue Tracker <http://apps.jcns.fz-juelich.de/redmine/projects/bornagain/issues>`_
+
+
+How to use the bug and issue tracker?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Users of the software who encounter problems during the installation
+of the framework or during the run of a simulation can use the web-based issue tracking system
+at `link <http://apps.jcns.fz-juelich.de/redmine/projects/bornagain/issues>`_
+to report a bug. The same system can be used to request new features.
+This system is open for all users in read mode, while
+submitting bug reports and feature requests are possible only after a simple registration
+procedure.
+
+
diff --git a/Doc/Sphinx/documentation/installation/installation.rst b/Doc/Sphinx/documentation/installation/installation.rst
index ed4534dd933..46c0ec919ea 100644
--- a/Doc/Sphinx/documentation/installation/installation.rst
+++ b/Doc/Sphinx/documentation/installation/installation.rst
@@ -1,6 +1,6 @@
Installation instructions
-----------------------------------
+================================
BornAgain is supported under Windows, Mac OS X and Linux operating systems.
For Windows and MacOS we provide binary installer packages, for Unix flavor (MacOS included) we support build and installation from source.
diff --git a/Doc/Sphinx/documentation/installation/installation_unix.rst b/Doc/Sphinx/documentation/installation/installation_unix.rst
index 02b0802f01e..e890f07e8b4 100644
--- a/Doc/Sphinx/documentation/installation/installation_unix.rst
+++ b/Doc/Sphinx/documentation/installation/installation_unix.rst
@@ -19,6 +19,6 @@ This advanced section explains in details how to build BornAgain's Graphical Use
:maxdepth: 3
installation_unix_gui.rst
-
+
\ No newline at end of file
diff --git a/Doc/Sphinx/documentation/installation/installation_unix_detailed.rst b/Doc/Sphinx/documentation/installation/installation_unix_detailed.rst
index d3d7a643b5b..400452cdebe 100644
--- a/Doc/Sphinx/documentation/installation/installation_unix_detailed.rst
+++ b/Doc/Sphinx/documentation/installation/installation_unix_detailed.rst
@@ -236,3 +236,4 @@ Run your first example and enjoy the first BornAgain simulation plot.
:ref:`building_gui_label`
+ :ref:`troubleshooting_label`
diff --git a/Doc/Sphinx/documentation/installation/installation_unix_gui.rst b/Doc/Sphinx/documentation/installation/installation_unix_gui.rst
index c8dda7c88a1..b9c20414044 100644
--- a/Doc/Sphinx/documentation/installation/installation_unix_gui.rst
+++ b/Doc/Sphinx/documentation/installation/installation_unix_gui.rst
@@ -129,15 +129,23 @@ Finally, compile and install the graphical users interface
Run BornAgain GUI
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-After installation is complete, run BornAgain GUI from command line
+After installation is complete the new ``BornAgain`` executable will appear in ``<install_dir>/bin`` directory.
+Make sure that BornAgain core libraries are in your PATH by running
.. code-block:: bash
source <install_dir>/bin/thisbornagain.sh
+
+and launch GUI
+
+
+.. code-block:: bash
+
<install_dir>/bin/BornAgain
.. seealso::
- :ref:`building_gui_label`
+ :ref:`using_gui_label`
+ :ref:`troubleshooting_label`
diff --git a/Doc/Sphinx/documentation/installation/installation_unix_short.rst b/Doc/Sphinx/documentation/installation/installation_unix_short.rst
index c11168e48c4..f2aaa8743a0 100644
--- a/Doc/Sphinx/documentation/installation/installation_unix_short.rst
+++ b/Doc/Sphinx/documentation/installation/installation_unix_short.rst
@@ -1,6 +1,8 @@
Installation instruction (short version)
-----------------------
+This page shortly explains how to build and install BornAgain framework from source on Unix platforms.
+
Install the third party software
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -44,3 +46,10 @@ Build and install the framework
.. code-block:: bash
$ cmake -DBORNAGAIN_GUI=ON -DCMAKE_INSTALL_PREFIX=<install_dir> <source_dir>
+
+.. seealso::
+
+ :ref:`detailed_installation_instruction_label`
+
+
+
\ No newline at end of file
diff --git a/Doc/Sphinx/documentation/troubleshooting/troubleshooting.rst b/Doc/Sphinx/documentation/troubleshooting/troubleshooting.rst
new file mode 100644
index 00000000000..c7fa6802edf
--- /dev/null
+++ b/Doc/Sphinx/documentation/troubleshooting/troubleshooting.rst
@@ -0,0 +1,26 @@
+.. _troubleshooting_label:
+
+Troubleshooting
+==========================
+
+
+BornAgain was successfully tested on a variety of Windows, MacOS and Unix platforms.
+Nevertheless, problems can still occur.
+
+We welcome feedback and bug reports related to the
+installation and use of BornAgain framework via
+
+* bornagain.project@gmail.com
+
+* `BornAgain Bug and Issue Tracker <http://apps.jcns.fz-juelich.de/redmine/projects/bornagain/issues>`_
+
+
+Please send us e-mail or fill in bug report providing all relevant information which will help us to quickly spot the problem.
+
+
+Please refer to the following sections which might help to identify the source of the problem
+
+.. toctree::
+ :maxdepth: 1
+
+ troubleshooting_installation_unix.rst
diff --git a/Doc/Sphinx/documentation/troubleshooting/troubleshooting_installation_unix.rst b/Doc/Sphinx/documentation/troubleshooting/troubleshooting_installation_unix.rst
new file mode 100644
index 00000000000..5384ba1f825
--- /dev/null
+++ b/Doc/Sphinx/documentation/troubleshooting/troubleshooting_installation_unix.rst
@@ -0,0 +1,45 @@
+
+
+Installation problems on Unix platforms
+------------------------------------------
+
+.. contents::
+ :depth: 1
+ :local:
+ :backlinks: none
+
+
+
+CMake configuration fails
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+CMake might fail with the error message::
+
+ Configuring incomplete, errors occurred!
+
+or similar if some of the third party libraries are not installed on the system, or cmake is not able to find them.
+Please send us the log file ``my_cmake.log`` generated by running the following command in the empty ``<build_dir>``
+
+.. code-block:: bash
+
+ cmake -DCMAKE_INSTALL_PREFIX=<install_dir> <source_dir> >& my_cmake.log
+
+
+
+
+
+Compilation fails
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In the case of a complex system setup, with libraries of different versions
+scattered across multiple places ``cmake`` might make an error in identifying correct paths to the libraries or include directories.
+This might lead at some point to the compilation failure.
+This might happen, for example, during compilation of BornAgain graphical user interface if the system has both Qt4 and Qt5 libraries installed.
+Please send us the build log by running following make command
+
+.. code-block:: bash
+
+ make VERBOSE=1 >& my_build.log
+
+
+
diff --git a/Doc/Sphinx/documentation/working_with_bornagain/using_gui.rst b/Doc/Sphinx/documentation/working_with_bornagain/using_gui.rst
index 1c1b7df5d42..3c89b9435ac 100644
--- a/Doc/Sphinx/documentation/working_with_bornagain/using_gui.rst
+++ b/Doc/Sphinx/documentation/working_with_bornagain/using_gui.rst
@@ -228,7 +228,7 @@ reflecting the influence of this given parameter on the simulation results.
The jobs in Jobs View are completely isolated from the rest of the program. Any adjustments of sample parameters in Sample View or
instrument parameters in Instrument View
- won't have any influence on jobs already existing/running in Jobs View. Similarly, any parameter adjustments made in the parameter tree (3)
+ won't have any influence on jobs already completed or still running in Jobs View. Similarly, any parameter adjustments made in the parameter tree (3)
will not be propagated back into Sample or Instrument Views.
--
GitLab