Improve documentation not to suggest cloning the repo

[giordano]

The documentation shouldn't recommend cloning the repository, since the package is already available anyway. If this was only meant to run the examples, one can do something like this:

julia> using Geant4, Pkg

julia> Pkg.activate(joinpath(pkgdir(Geant4), "examples"))
  Activating project at `~/.julia/packages/Geant4/CEYN0/examples`

julia> Pkg.instantiate()
[...]

julia> include(joinpath(pkgdir(Geant4), "examples", "basic", "B1", "B1.jl"))
<<< Reference Physics List QBBC 

**************************************************************
 Geant4 version Name: geant4-11-01-patch-01 [MT]   (10-February-2023)
                       Copyright : Geant4 Collaboration
                      References : NIM A 506 (2003), 250-303
                                 : IEEE-TNS 53 (2006), 270-278
                                 : NIM A 835 (2016), 186-225
                             WWW : http://geant4.org/
**************************************************************

Checking overlaps for volume Envelope:0 (G4Box) ... OK! 
Checking overlaps for volume Shape1:0 (G4Cons) ... OK! 
Checking overlaps for volume Shape2:0 (G4Trd) ... OK! 
### HadronInelasticQBBC Construct Process:
    Emin(FTFP)= 3 GeV; Emax(FTFP)= 100000 GeV
    Emin(BERT)= 1 GeV; Emax(BERT)= 6 GeV; Emax(BERTpions)= 12 GeV;
    Emin(BIC) = 0 GeV; Emax(BIC)= 1.5 GeV.
=======================================================================
======                 Electromagnetic Physics Parameters      ========
=======================================================================
LPM effect enabled                                 1
Enable creation and use of sampling tables         0
Apply cuts on all EM processes                     0
Use combined TransportationWithMsc                 Disabled
Use general process                                1
Enable linear polarisation for gamma               0
Enable photoeffect sampling below K-shell          1
Enable sampling of quantum entanglement            0
X-section factor for integral approach             0.8
Min kinetic energy for tables                      100 eV 
Max kinetic energy for tables                      100 TeV
Number of bins per decade of a table               7
Verbose level                                      1
Verbose level for worker thread                    0
Bremsstrahlung energy threshold above which 
  primary e+- is added to the list of secondary    100 TeV
Bremsstrahlung energy threshold above which primary
  muon/hadron is added to the list of secondary    100 TeV
Lowest triplet kinetic energy                      1 MeV
Enable sampling of gamma linear polarisation       0
5D gamma conversion model type                     0
5D gamma conversion model on isolated ion          0
Livermore data directory                           epics_2017
[...]

[peremato]

Thanks for the suggestion. I do I agree that is not very nice and can bring even inconsistencies/incompatibilities. I was thinking to have a separate repository for the examples. Keeping the core package small and with less dependencies. In this way people can clone them to run and eventually use them as starting point for their application. The problem is that as part of the CI I run the examples as regression tests and this now will be in a different repositories that I would need to synch. Do you have any suggestion for this? Perhaps I can include the examples repository as a git submodule for the tests.

[Moelf]

I think having the example folder in the same repo is fine! you can just have a function something like:

Geant4.example_path() = joinpath(dirname(@__DIR__), "examples")

(@__DIR__ will be src/, so dirname() should bring us to the root directory of the repo

[peremato]

@giodano I moved all the examples to a new package G4Examples and added it as a git submodule. The development is still nice and convenient, and I can run the CI tests and generate the documentation that uses these examples. But, when registering the package to Julia I get the error:

     Cloning [559df036-b7a0-42fd-85df-7d5dd9d70f44] Geant4 from https://github.com/JuliaHEP/Geant4.jl.git
ERROR: GitError(Code:ERROR, Class:Submodule, cannot get submodules without a working tree)

According to https://github.com/JuliaLang/Pkg.jl/issues/708 I cannot use submodules and I must remove them, but then the CI will fail. Do you know a solution to this dilemma?

[Moelf]

I think you can use Pkg.develop() for CI

[giordano]

Can you do it without having the examples dir as a submodule? How are you using it?

[peremato]

I am using sub-module because of the convenience during development (with VScode I can modify the code and the examples coherently). For the CI, to run the tests and produce the docs, I just need to do:

      - uses: actions/checkout@v2
        with:
          submodules: recursive

and it works. I guess I would need to remove the submodule and do an explicit checkout on the CI to please the Julia registration process

[peremato]

This is now done. The CI checkout explicitly the examples repository with:

      - name: Checkout
        uses: actions/checkout@v2
      - name: Checkout G4Examples
        uses: actions/checkout@v2
        with:
          repository: JuliaHEP/G4Examples.jl
          path: examples

The README and docs does not suggest to clone this repository, instead to clone the G4Examples. Closing the issue.