Sphinx: faq and troubleshooting section.

Doc/Sphinx/documentation/documentation.rst

 
 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

Doc/Sphinx/documentation/faq/faq.rst

+
+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.
+
+

Doc/Sphinx/documentation/installation/installation.rst

 
 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.

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

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`

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`

Doc/Sphinx/documentation/installation/installation_unix_short.rst

 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

Doc/Sphinx/documentation/troubleshooting/troubleshooting.rst

+.. _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

Doc/Sphinx/documentation/troubleshooting/troubleshooting_installation_unix.rst

+
+
+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
+    
+    
+

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.