Overview

Date: 28.07.2022

Objective: Weekly space for deep dive topics

Participants: (kindly only add your own names, not those of other participants)

• Uwe Wahser

• Marco Kalin

• Dragos Dobre

• Eric Darchis

• Damian Borowiecki

• Alex Motoc

Topic Proposals:

• Documentation platforms

Presentations / Attachments

Minutes

• User documentation on http://docs.openimis.org (ReadTheDocs via GitHub) - Not up2date

• GitBook for installation documentation

  • Multi-language support

• Module documentation needed / Definition of a “Module”

  • Each module has a configuration (json)

• Developers documentation

  • Documentation per “module”

    • Services provided

    • Contribution points

  • Generated from source code (ReadTheDocs via GitHub)

    • Same platform like for the user documentation

    • Can be mainly automated per GitHub actions and scripts

    • Can be seen in GitHub and be exported to HTML, PDF (Latex) and be displayed by ReadTheDocs

    • Possible automatic translations?

    • Output formats: HTML (including Windows HTML Help), LaTeX (for printable PDF versions), ePub, Texinfo, UNIX manual pages, plain text

  • Integration with implementers point of view is needed

• Discussion needed

  • Use of GitBook - Integration with Wiki

  • Use of ReadTheDocs for Developer Documentation - Integration with Wiki

    • Multiple different target audiences

      • Developer gets access to the full details (link to documentation on ReadTheDocs)

      • Implementers get an extract of specific information (e.g. configuration)

        • Possible to embed in Wiki? (automated / not copied)

        • Make it more accessible for non-IT people

Related points from DC

Additional Resources

• Sphinx docstring formatting syntax: https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html#the-sphinx-docstring-format