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
- 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.
- 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.
- 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
- 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!!
Alex, 24/7/17
