1 / 15

Next Generation Documentation for the JCOP Framework

Proposal for the next generation documentation in JCOP Framework, moving from HTML to Qt Help, with benefits for users and developers. Includes structure, benefits, and future efforts.

dyers
Download Presentation

Next Generation Documentation for the JCOP Framework

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

  1. Industrial Controls and Safety Group The FwHelp Project Our proposal for next generation documentation in JCOP FW Graham R. Armstrong Jonas Arroyo Garcia MariuszSuder Riku-PekkaSilvola Piotr Golonka

  2. The FwHelp Project JCOP 8.4.0 beta Next Generation Documentation for the JCOP Framework Moving documentation from HTML to Qt Help

  3. Demonstration Next Generation Documentation for the JCOP Framework Requirements: • WinCC OA 3.16 • fwInstallation v8.4.0-beta • Components from JCOP v8.4.0-betawith Qt help files Requirements available from JCOP website: https://jcop.web.cern.ch/jcop-framework-0

  4. Industrial Controls and Safety Group

  5. What is The Qt Help Framework? Help file and Collection Generation Viewer, Assistant Next Generation Documentation for the JCOP Framework A comprehensive set of tools for generating and viewing documentation. Used by WinCC OA.

  6. Qt Help Internals Qt Help Project Extension *.QHP XML file with table of contents, indices, references to HTML documentation. Qt Help Collection Project Extension *.QHCP XML file referencing compressed help files to be included in the collection. Qt Compressed Help Extension *.QCH Compressed documentation, ready for distribution. Qt Help Collection Extension *.QHC Compressed collection file that will be read by the Qt Help Assistant. https://doc.qt.io/qt-5/qthelp-framework.html Next Generation Documentation for the JCOP Framework

  7. Structure WinCC OA Project Qt Help Collection (Single *.qhc per project) WinCC OA Help Component Help User-specific Help Other Component Help Qt Compressed Help File Next Generation Documentation for the JCOP Framework

  8. Documentation generation process Doxyfile Ctrl Source Doxygen Pre-process keywords Qt Help Project (XML) HTML Docs Qt Help Generator JCOP Component, append <qtHelp> tag to component XML with path. Qt Compressed Help file <Project Root>/help/en_US.utf8/fwComponent/fwComponent.qch Next Generation Documentation for the JCOP Framework

  9. Collection Installation process Installing Components with FwInstallation JCOP Component Help WinCC OA Help User Help Generic Qt Help Collection FwInstallation Project-specific Qt Help Collection <Project Root>/help/en_US.utf8/WinCC_OA.qhc Next Generation Documentation for the JCOP Framework

  10. Benefits of FwHelp for users Next Generation Documentation for the JCOP Framework • Dedicated cross-platform viewer application (Qt Assistant) with: • Contents • Indexing • Bookmarks • Search • GEDI Integration • Right-click ‘Open Help’ for functions • Toolbar ‘WinCC OA Overview’No need to go through FwInstallation panel

  11. Benefits of FwHelp for developers Next Generation Documentation for the JCOP Framework • Same technology, Doxygen • Documentation generated from inline comments like at present, no need for change. • Just a few settings to change in Doxyfile. • Automatic documentation building • Kobe builds the documentation and includes it in the *.zip file. • Kobe adds <qtHelp> tag in component XML. • Single file for documentation, fewer files to manage • Also about a quarter of the file size.

  12. Proposal for future efforts Next Generation Documentation for the JCOP Framework • Update the contents of help documentation for JCOP components. • Include user guides in the Qt Compressed Help files. • Deprecate HTML documents • Panel documentation is outdated • Perhaps we should remove legacy documentation? • Or move it online only?

  13. Proposal Feedback Next Generation Documentation for the JCOP Framework These changes are only in our beta, please try the new help system and give us feedback. Icecontrols.Support@cern.ch

  14. Industrial Controls and Safety Group

  15. Integrating your component Next Generation Documentation for the JCOP Framework • Follow the directory convention • PVSS/ contains everything to be packed • Libs under PVSS/scripts/libs/ComponentName/ • Add below snippet to the top of your .gitlab-ci.yml file. • Detailed instructions on GitLab

More Related