Documentation Meeting 3, 24th July 2017

1. Installation guide has been migrated to Sphinx (Ben)  and git repo created
   • Issues with combining sub-files via Pandoc
     • solution was to use xmllint to merge the sub-docs, drawback: only creates one ReST document
     • Daren/Ben to investigate further if there's a neater solution, otherwise we will manually (once) merge and the de-merge the files
   • Need to cross-check that referenced documents are handled correctly when building with Sphinx (should be fine)
   • Few issues with version dependence of Sphinx - the README at the head of the repo will contain up-to-date comments about how to build with Sphinx
   • AI (Daren/Ben): check if multiple docbook files can be handled by Pandoc
   • AI (Ben): check if references are correctly handled by Sphinx
2. The git repository will be automatically built into a static directory (via Sphinx) which can then be accessed so that developers can see their commits to the documentation "live"
3. For a documentation release a branch will be made and the documents copied to a public web server "afs"-like
4. Migration schedule:
   • To migrate to sphinx in time for the release looks challenging
   • A partial migration should also be fine, provided we co-ordinate it properly and developers know where to put their changes/updates
   • The current status at the collaboration meeting will be decision point, however, a partial solution via co-ordination will be acceptable.
   • Most likely the Physics Reference Manual will remain in latex for release 10.4.
5. Physics lists:
   • Recognised that something should be done
   • Will cover Physics List and Validation, Basic and Extended Examples and Documentation working groups
   • Parallel session to handle novice documentation at the Collaboration Meeting
     • Problem with remote participation (most of us!): Alex, Ben, Vladimir, Daren, Andrea, Gunter, maybe Tatsumi. Present will be Denis and Ivana.
6. Style-files/Formatting:
   • Should be straight forward to adjust with both Sphinx and Drupal
   • Will be raised at Collaboration Meeting so that working groups can also be in the same style
   • A first common style will be chosen and then we'll see if it's silently accepted
   • A link to the current web-page drupal migration is here:
     http://new-geant4-dev.web.cern.ch
7. Collaboration Meeting Plenary:
   • Common style file - will be presented, hopefully accepted - should be straight
   • Also for working groups
   • Should clarify that Sphinx and ReST is acceptable to everybody (Alex thought so from the last collaboration meeting)
8. Collaboration Meeting Parallel:
   • The idea of creating Physics List documentation sounds good
   • Session might have to be revised given the level of remote participation (Alex, Ben, Vladimir, Daren, Andrea, Tatsumi) and only Dennis, Ivana, Gunter and Gabriele present.
9. git vs. svn:
   • git will be used exclusively for the new documentation format
   • any updates prior to the migration should be within svn, however, we need to synchronise so that we don't have to migrate twice!
   • Please contact Alex or discuss by the mailing list prior to making updates/commits to svn!!

Alex, 24/7/17