diff --git a/docs/conf.py b/docs/conf.py
index dac883e5e8011a6214df2f6bc77a02a3029261f7..81b419017705526af140b55870ffe7d776f1da7b 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -68,7 +68,7 @@ master_doc = 'index'
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
diff --git a/docs/howto/full_simulation.rst b/docs/howto/full_simulation.rst
index a2ede96ee56a44562f73b5569b48b6bd58a6ff14..9ee7b340501a764a1377dd7529ab7592010372e3 100644
--- a/docs/howto/full_simulation.rst
+++ b/docs/howto/full_simulation.rst
@@ -1,13 +1,73 @@
-Full simulation
-===============
+Full simulation and reco
+========================
-Tutorials
----------
-Tutorials are available on a dedicated websites:
+Quick tutorials
+---------------
+
+This is quick tutorial with the steps of how to run sim&recon from scratch.
+This work both on BNL and JLab farms as well as personal PCs.
+
+
+0. Install eic-shell
+~~~~~~~~~~~~~~~~~~~~~
+
+.. code:: bash
+
+ > curl https://eicweb.phy.anl.gov/containers/eic_container/-/raw/master/install.sh | bash
+
+ # to run eic environment in singularity container
+ > ./eic-shell
+
+More on installing and using singularity here: `Use singularity <use_singularity.html>`_
+
+
+1. Convert MCEG to HepMC
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The input format should be in HepMC format. If the conversion is needed:
+`Convert MCEG <mceg.html>`__
+
+
+2. Run DD4HEP simulation
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Select a detector
+
+.. code:: bash
+
+ # Detectors live in
+ # /opt/detectors
+ # one can select particular configuration as
+ # source /opt/detector/athena-deathvalley-1.5T/setup.sh
+ #
+ # or one can set the latest detector
+ source /opt/detector/setup.sh
+
+ # Run simulation
+ npsim --compactFile=$DETECTOR_PATH/athena.xml --runType=run -N=2 --outputFile=sim_output.edm4hep.root --inputFiles mceg.hepmc
+
+
+3. Run Juggler/Gaudi reconstruction
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code:: bash
+
+ #set the same detector as in the simulations
+ source /opt/detector/setup.sh
+
+ export JUGGLER_SIM_FILE=sim_output.edm4hep.root JUGGLER_REC_FILE=rec_output.edm4hep.root JUGGLER_N_EVENTS=10
+ gaudirun.py /opt/benchmarks/physics_benchmarks/options/reconstruction.py
+
+
+
+Full Tutorials
+--------------
+
+More detailed tutorials are available on a dedicated websites:
Detector simulation
-^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~
- `Full simulation tutorials <https://eic.phy.anl.gov/tutorials/eic_tutorial/getting-started/quickstart>`_
- `Quick start guide <https://eic.phy.anl.gov/tutorials/eic_tutorial/getting-started/quickstart>`_
@@ -18,20 +78,22 @@ Detector simulation
`Perticipate in feedback! <https://docs.google.com/forms/d/e/1FAIpQLSclPBXv13pVtawt35XeaCDMOcmdo8fhKTapdmjFO_6gPTV-8w/viewform?usp=sf_link>`_
Tracking
-^^^^^^^^
+~~~~~~~~
- `(in development) ACTS tracking repo <https://eicweb.phy.anl.gov/EIC/documentation/guide_to_tracking>`_
+Full simulation tips
+--------------------
Particle gun
-------------
+~~~~~~~~~~~~
There are at least 2 ways of running a particle gun out of the box:
- using npsim command line
-- using geant macro file and invoke GPS (General Particle Source)
+- using geant macro file and invoke gps
Using npsim (wrapper around ddsim) command line:
@@ -45,21 +107,24 @@ Using npsim (wrapper around ddsim) command line:
# uniform spread inside an angle:
npsim --compactFile=athena.xml -N=2 --random.seed 1 --enableGun --gun.energy 2*GeV --gun.thetaMin 0*deg --gun.thetaMax 90*deg --gun.distribution uniform --outputFile test.root
-
Using GPS
`General Particle Source tutorial <https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/GettingStarted/generalParticleSource.html>`__
-Add the next content (or save as a separate .mac file):
+GPS is configured in Geant4 macro files.
+An example of such file `may be found here <https://eicweb.phy.anl.gov/EIC/detectors/athena/-/blob/master/macro/gps.mac>`__
+
+To run npsim with GPS you have to add `--enableG4GPS` flag and specify Geant4 macro file:
.. code:: bash
-
-
+ npsim --runType run --compactFile athena.xml --enableG4GPS --macro macro/gps.mac --outputFile gps_example.root
+
+
Geometry visualization
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~
There are many ways to see the geometry and tracks:
@@ -68,10 +133,7 @@ There are many ways to see the geometry and tracks:
3. ddeve (root EVE based event display...)
4. dd_web_display (using browser and jsroot library)
-Geant4 event display
-~~~~~~~~~~~~~~~~~~~~
-
-Example command:
+To run Geant4 event display:
.. code:: bash
@@ -79,7 +141,6 @@ Example command:
npsim --runType vis --compactFile athena.xml --macro macro/vis.mac --outputFile test.root --enableG4GPS --enableQtUI
-
Geometry conversion
-------------------
@@ -106,8 +167,8 @@ One can use dd_web_display to actually just save root geometry
dd_web_display --export athena.xml # will create a .root file with the geometry
-FAQ
----
+How XML is invoked from C++ in DD4Hep
+-------------------------------------
> How does the XML file in the compact directory know which c++ file to load when we include the respective XML file in the main athena.xml file?
diff --git a/docs/howto/mceg.rst b/docs/howto/mceg.rst
index fa7b91aa5870156b3abb22038deb6cc33dd03afb..e896d6d6911af9c0fd8d64a7953c76ab0a5add13 100644
--- a/docs/howto/mceg.rst
+++ b/docs/howto/mceg.rst
@@ -28,6 +28,8 @@ MCEG software (see the next picture).
- **Converters** allow to convert other formats to HepMC
- **Afterburner** applies crossing angle and beam effects
+.. _convert_mceg:
+
Convert MCEG
------------
@@ -41,6 +43,28 @@ Currently there are 2 packages that allow to convert different MCEG to HepMC
to use for users and also has convenient python API. mcconv correctly works with GEMC LUND (Clas12) format.
+Example converting CLAS12 file to HepMC
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code:: bash
+
+ # install mcconv
+ pip3 install --upgrade mcconv
+
+ # if there is a sertificate problems
+ python3 -m pip install --trusted-host pypi.python.org --trusted-host files.pythonhosted.org --trusted-host pypi.org --user -U mcconv
+
+ # Add home bin directory to the PATH environment variable
+ export PATH=~/.local/bin:$PATH
+
+ # convert lund gemc
+ mcconv input.txt -i lund_gemc -b 10x100 -v
+
+ # File from example
+ mcconv /work/eic/mc/meson_MC/OUTPUTS/0mrad_IR0/nov_2021/pi_n_10.0on100.0_x0.0010-1.0000_q1.0-100.0_lund.dat -v -p 1000
+
+
+
Crossing angle and beam effects
-------------------------------