Documentation Migration Meeting 3
Monday Jul 24, 2017, 5:00 PM
Meeting to discuss the migration of the Geant4 documentation away from docbook (and potentially latex) to something like read-the-docs/markdown and to try to produce a time-line for the effort
Eidgenoessische Technische Hochschule Zuerich (CH)
Documentation Meeting 3, 24th July 2017
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
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"
For a documentation release a branch will be made and the documents copied to a public web server "afs"-like
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.
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.
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:
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)
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.
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!!