Documentation Migration Meeting 3

Europe/Zurich
CERN

CERN

Description
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
    • 17:00 17:10
      Introduction/Overview 10m
      Speaker: Alexander Howard (Eidgenoessische Technische Hochschule Zuerich (CH))

      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