Documentation Requirements

Inputs:
 * html output
 * pdf output
 * Easy to write/format
 * Ability to handle (inline) or translate latex
 * Ability to handle figures, bibliography, formulae
   * mathjax looks nice (https://www.mathjax.org/)
 * Cross-referencing
   * within a document
   * between documents
 * Avoid duplication of information in multiple places
 * Keep document coherent/structured
   * so one person can harmonise a whole document
 * Relate/locate document to code
   * works for physics lists
   * doesn't work for physics models
 * Solution needs to be long-term and elegant
   * is sphinx and reST used by enough people to make it last?
   * how about markdown?
 * Edition of source in protected git repository
   * branch per release
   * possibility to edit per category and possibility to see results of edition for a sub-chapter - this is a bit contrudictory to cross references


What is documentation?
Currently 5 core documents (introduction, installation, application developers guide, toolkit developers guide, physics reference manual), what about others:

 * whole Geant4 web?
 * working group wiki pages?
 * reference physics lists?


Outputs:
 * decide on final format: reST or markdown or something else?
 * decide on tool: sphinx?
 * decide on conversion tool: pandoc?

Personal thoughts (Andrea):
 * It is clear we are converging towards RST or Markdown. The two are pretty similar, as far as I can understand. It looks like Markdown has more momentum, due to the fact that github is using it and allows people to add documentation easily to projects via MD. This webpage shows some differences: http://www.unexpected-vortices.com/doc-notes/markdown-and-rest-compared.html
 * From what I read online (e.g. https://github.com/robinandeer/cookiecutter-pyvanguard/issues/2) it seems that shpinx is preferred for larger documentation projects
 * In anycase this is a minor issue. Because in the worst case we can use pandoc to convert from RST to MD and viceversa. Clearly we should avoid this, but we can do this for small tests
 * Indipendently from the format we decide there is then the issue of creating web-pages out of the files. I see two other possibilities here in addition to readthedocs:
   * pandoc can generate HTML that we can copy to G4 website
   * in the same style, but more "advanced" (support for templates), there is jekyll. It accepts Markdown by default and again is tightly integrated with github. I am aware of an ATLAS project to use this as the documentation engine for some sw related stuff: https://atlassoftwaredocs.web.cern.ch/ 

Personal notes/thoughts (Ben)
 * Will look at generating PDF etc from sphinx for next meeting
   * Can be done with rst2pdf
 * Create test project on readthedocs.org:
   * Can link to a VCS repository, and can be set up to build on each commit.
   * Can host multiple versions of the documentation
   * Can creates PDF and other formats automatically.
   * See for example the Geant4 app TOPAS:
     * http://topas.readthedocs.io/en/latest/
   * GitHub (and I think CERN's GitLab) allow rst/MD files to be edited and viewed in a web browser, including some helpers for formatting, and previews of rendering (at least to check formatting errors). Might help to make docs easier/faster to edit.
 * Example project created on gitlab:
   * https://gitlab.cern.ch/bmorgan/sphinxrtd-example
 * Hosted on readthedocs:
   * http://sphinxrtd-example.readthedocs.io/en/latest/index.html
 * Have tried to add examples of structure, MathJax, Markdown and PDF generation (see bottom left corner)
 * Readthedocs is doing "Continuous" builds, so any new push to the repo builds, tests and deplyos the docs.
 * They can also be built offlline (see the frontpage)
 * Don't have to host of readthedocs, could also use Gitlab/CERN CI pipelines to do this and deploy to own website. 

Personal thoughts (Daren)
 * on rST vs markdown: the readthedocs website https://docs.readthedocs.io/en/latest/getting_started.html says:
 * Note: Markdown doesn’t support a lot of the features of Sphinx, like inline markup and directives. However, it works for basic prose content. reStructuredText is the preferred format for technical documentation, please read this blog post for motivation.
 * where "this blog post" is http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/
 * point 1 is lack of a markdown standard. Pandoc accepts 6 versions of markdown. At a minimum we will have to choose a version of markdown
 * 
Again Andrea (after reading Ben's and Daren's comments): it looks like RST is much more suited for our needs, rith?

Notes - Gunter
 * The announce of gitlab 8.17 states there is a trend for websites away from CMS (a la Grupal) to static pages, and that gitlab supprts this. Andrea mentioned jekyll, gitlab lists many more in addition to jekyll. Does anyone know more about this? Should we look into this?