header_docu_qt

Create documentation or SBOM from file header
(focussed on older libraries which didn't use the docs-as-code approach)

Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Plug-Ins
5. Roadmap
6. Contributing
7. License
8. Contact
9. Screenshots and Samples

About the Project

Create documentation or SBOM SPDX/CycloneDX from file header (e.g. *.c[pp], *.h[pp], ...)

short description:

File (header) parser with plug-in support for parser-plugins and writer-plugins

description:

With great respect to Doxygen, JSDoc or DoxDox, but they all reading / parsing the complete textfile.

For me I just need parsing the first comment block of a single textfile or every textfile with a defined file-extension in a folder, doesn't matter if *.js, *.h, *.hpp or whatever

Fileheader_docu_ parse a single file or recursive directories for files with defined extensions (e.g.: *.c, *.cpp, *.h, *.js, *.ts).

Parsing will be done by the defined parser plugin (e.g.: gh_markdown, doxygen).

Writing the header docu will be done by the defined writer pluging (e.g.: json, gh_markdown).

The future default writer plugin will be adoc (ASCIIdoc) so fileheader_docu can be used as an export task (binary) to doctoolchain.

scanned / collected Meta data:_*

(depends on parser-/writer plug-ins and inifile configuration)

• FILE
• TITLE
• AUTHOR
• BRIEF"
• VERSION
• DATE
• DESC
• DESCRIPTION
• LICENSE
• COPYRIGHT
• SOURCE
• COMMENT
• SYNTAX
• DEPENDENCIES
• HISTORY

scanned / collected file attributes:

• FILE_Name
• FILE_baseFileName
• FILE_completeSuffix
• FILE_baseDirName
• FILE_created_localtime
• FILE_LastModified_localtime
• FILE_lastModified_humanUTC
• FILE_lastModified_stringUTC
• FILE_lastModified_timeUTC
• FILE_lastModified_timeUtcOffset
• FILE_lastModified_timeZAbbreviation
• FILE_Perm_Numeric
• FILE_Perm_AlphaNumeric
• FILE_Size
• FILE_SHA256_Hash
• FILE_Scan_localTime
• FILE_Scan_UTCcurrent

built with

• GNU/Linux 5.15.0-69-generic x86_64 and QT 6.5 C++17 (g++).
• macOS Ventura (13.3, arm64-apple-darwin22.4.0) and QT 6.5 C++17 (clang++)
• Windows 10 and QT 6.5 C++17 (MinGW_64)

There are other, older versions:

• written in QT5 with C++17 : header_docu QT5 C++17

• written in plain C++20 : header_docu CPP C++20

docs-as-code approach:

see:

• docs-as-code
• docToolchain (user site)
• docToolchain (Github)

Getting Started

tested with:

• GNU/Linux with Kernel 5.15 and g++ 11.3.0
• MacOS Ventura (13.3, arm64-apple-darwin22.4.0) and clang++ 14.0.3
• Win10pro and MinGW_64

Prerequisites

• the Linux AppImage should run on most newer x86_64 Linux system
• the MacOS application package should be installable at least under MacOS Ventura
• the Windows Setup.exe should be installable at under Win10 and Win11

(for compiling and linking):

• PC or Laptop with Windows, MacOS or Linux *_^
• installed C++ compiler like g++ or clang++ with C++17 support
• developer tools with cmake

DEPENDENCIES:

cxxopts

a lightweight C++ option parser library, supporting the standard GNU style syntax for options. https://github.com/jarro2783/cxxopts

inifile-cpp

inifile-cpp is a simple and easy to use single header-only ini file en- and decoder for C++. https://github.com/Rookfighter/inifile-cpp

OpenSSL

OpenSSL - a robust, commercial-grade, full-featured toolkit for general-purpose cryptography and secure communication. https://www.openssl.org/

OpenSSL (Library tested: OpenSSL 3.0.2 15 Mar 2022; Linux: openssl-dev) is needed for creating SHA2-256Bit Hashes for strings and files.

Installation

1. Clone the repo

   git clone https://github.com/Zheng-Bote/header_docu_qt/.git

2. install
   • not yet implemented

(back to top)

configuration and build

Linux

1. rename CMakeList.txt_linux to CMakeList.txt
2. configure your QT project to C++17 and cmake
3. adjust your Inifile to Linux filesystem

MacOs

1. rename CMakeList.txt_macos to CMakeList.txt
2. configure your QT project to C++17 and clang
3. adjust your Inifile to MacOs filesystem

(back to top)

Usage

Tip

with configured inifile several file-extensions can be parsed during one runtime.

SYNTAX:

file header parser
Usage:
  ./Fileheader_Docu-x86_64.AppImage [OPTION...]

  -a, --auto        run with default Inifile
  -c, --create      create Inifile
  -d, --dir arg     parse directory <dir>
  -e, --ext arg     file extension to search for. E.g.:
                    <*.h> | <*.hpp> | <*.c> | <*.cpp>
  -f, --file arg    parse <pathTo/fileName>
  -i, --ini arg     use Inifile <pathTo/inifile> (default: ./Fileheader_Docu-x86_64.AppImage.ini)
  -l, --listini     list Inifile (optional with --ini <pathTo/IniFile>)
  -o, --out arg     output directory <dir>
  -p, --parser arg  how to parse the input (use --plugins to list available plugins):
                    e.g.: <gh_markdown> | <doxygen>
      --plugins     list available plugins
  -w, --writer arg  output type (use --plugins to list available plugins):
                    e.g.: <adoc> | <csv> | <html> | <json> | <md> | <txt>
  -v, --version     Print program and version
  -h, --help        Print help

EXAMPLES:

create default Inifile

./Fileheader_Docu-x86_64.AppImage --create

list/show the given Inifile

./Fileheader_Docu-x86_64.AppImage --listini --ini <pathTo/inifile>

list available Plug-Ins

./Fileheader_Docu-x86_64.AppImage --plugins
Parser Plug-Ins:
================
Plugin Name:........doxygen
Version:............doxygen header parser-v1.0.0
Plugin Name:........gh_markdown
Version:............Github Markdown parser-v1.0.0

Writer Plug-Ins:
================
Plugin Name:........gh_markdown
Version:............Github Markdown writer-v1.1.0
Plugin Name:........json_cyclonedx
Version:............json CycloneDX (spdx) writer-v0.1.0
Plugin Name:........json_spdx
Version:............json spdx writer-v1.0.0
Plugin Name:........json
Version:............json writer-v1.0.0

parse folder recursively for files with extension *.cpp, write to target folder with parser plug-in doxygen and writer plug-in json

./Fileheader_Docu-x86_64.AppImage --dir ./ESP32_libs --ext *.cpp --out ./ESP32_libs/docu --parser doxygen --writer json

default: run with inifile ./Fileheader_Docu-x86_64.AppImage.ini

./Fileheader_Docu-x86_64.AppImage -a
./Fileheader_Docu-x86_64.AppImage --auto

RETURN:

 2023-04-03 18:22:57 : 5 Files parsed with header parser gh_markdown. Output stored with format json in folder ./ESP32_libs/docu
 
 exit(0)

Plug-Ins

current available plug-ins:

Parser Plug-Ins

• gh_markdown (https://github.com/Zheng-Bote/hd_ghmd_parser_plugin)
• doxygen (https://github.com/Zheng-Bote/hd_doxygen_parser_plugin)

Writer Plug-Ins

• gh_markdown (https://github.com/Zheng-Bote/hd_ghmd_writer_plugin)
• json (https://github.com/Zheng-Bote/hd_json_writer_plugin)
• json_spdx (https://github.com/Zheng-Bote/hd_spdx_writer_plugin) => useable, but still under construction
• json_cyclonedx (https://github.com/Zheng-Bote/hd_json_CycloneDX_writer_plugin)

HISTORY:

Version	Date	Developer	Comments
1.0.0	2023-04-07	RZheng	created
1.1.0	2023-04-25	RZheng	cleaned output
1.2.0	2023-04-26	RZheng	list available Plug-Ins
1.3.0	2023-04-29	RZheng	MacOS support (without threads)
1.3.0	2023-04-30	RZheng	Windows support

Roadmap:

• quick and dirty commandline parser (see QT5 C++17)

• migrate QT commandline to vanilla cxx (see CPP, C++20)

• create final commandline, plugin-based (this one)

• create optional md file[s]

• create optional Github md file[s]

• create optional ASCIIdoc (adoc) file[s]

• create optional JSON file[s]

• create optional csv file[s]

• create optional HTML5 file[s]

• get SHA2-256 filehash

• file last modified time

• file permissions

• save output results in separared file[s] or in one file

• performance improvements for single outfiles (threaded)

• runable Linux AppImage

• installable MacOS package

• installable Windows package

• create optional SBOM (spdx) json file[s] => writer plug-in

• upload optional SBOM (spdx) json to RDBMS => writer plug-in

Maybe a Kanban board will be established (soon)

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Contact

ZHENG Robert Zhèng Bó Tè 郑 伯特

Project Link: https://github.com/Zheng-Bote/header_docu_qt/

Screenshots and Samples

Default Inifile

[Input]
# folder with files to parse
Dir=/Volume/500GB/Dev/C/Arduino_ESP32_libs
# file extensions to parse
Extensions=*.h, *.hpp, *.c, *.cpp
# default parser plug-in
Parser_Plugin=doxygen

[Meta]
# file attributes
Attributes=FILE_PERM, LAST_MODIFIED, FILE_SIZE, FILE_HASH_SHA256
# header attributes to parse
Metadata=TITLE, BRIEF, DESC, AUTHOR, LICENSE, VERSION, COPYRIGHT, SOURCE, COMMENT, SYNTAX, HISTORY, DEPENDENCIES

[Output]
# output folder
Dir=/Volume/500GB/Dev/C/Arduino_ESP32_libs/Docu
# output type => deprecated -> Writer_Plugin
Filetype=.json
# all parsed results in one single file (true), or one output file for each parsed file (singleFile=false)
singleFile=false
# default writer plug-in
Writer_Plugin=json

[Plugins]
# plug-ins folder for parser
parserDir=/Volume/500GB/Dev/QT/header_docu_qt/Plugins/parser
# plug-ins folder for output writer
writerDir=/Volume/500GB/Dev/QT/header_docu_qt/Plugins/writer

Plugin-Loader

Plug-In loader-test

wrong identifier:

Q_DECLARE_INTERFACE(Plugin, "org.somewhere.my_plugin");

Loading... "/Volume/500GB/Dev/QT/header_docu_qt/Plugins/parser/libhtml_plugin.so"
Loaded:  "/Volume/500GB/Dev/QT/header_docu_qt/Plugins/parser/libhtml_plugin.so"
Plugin Constructed
Could not cast:  "/Volume/500GB/Dev/QT/header_docu_qt/Plugins/parser/libhtml_plugin.so"
Loading... "/Volume/500GB/Dev/QT/header_docu_qt/Plugins/parser/test.so"
qt.core.plugin.loader: /Volume/500GB/Dev/QT/header_docu_qt/Plugins/parser/test.so: failed to map to memory: Das Argument ist ungültig
Error:  "/Volume/500GB/Dev/QT/header_docu_qt/Plugins/parser/test.so"  Error:  "The file '/Volume/500GB/Dev/QT/header_docu_qt/Plugins/parser/test.so' is not a valid Qt plugin."
Plugins ParserDir has no valid plugins
program criterias missmatch
Plugin Deconstructed

correct identifier:

Q_DECLARE_INTERFACE(Plugin, "net.hase-zheng.header_docu_plugin");

Loading... "/media/zb_bamboo/500GB/Dev/QT/header_docu_qt/Plugins/parser/libhd_ghmd_parser_plugin.so"
Loaded:  "/media/zb_bamboo/500GB/Dev/QT/header_docu_qt/Plugins/parser/libhd_ghmd_parser_plugin.so"
Plugin Constructor
Test from Plugin:  "Test: header_docu plugin"
Plugin Name:  "gh_markdown"
Plugin Version:  "Github Markdown parser-v0.3.0"
Plugin Deconstructed
Loading... "/media/zb_bamboo/500GB/Dev/QT/header_docu_qt/Plugins/writer/libhd_json_writer_plugin.so"
Loaded:  "/media/zb_bamboo/500GB/Dev/QT/header_docu_qt/Plugins/writer/libhd_json_writer_plugin.so"
Plugin Constructor
Test from Plugin:  "json" :  "Test: header_docu plugin"
Plugin Name:  "json"
Plugin Version:  "json writer-v0.3.0"
Plugin Deconstructed

STDOUT

"2023-04-25 19:17:12"  :  "./header_docu_qt" - "01.01.00"  started
Loading... "/media/zb_bamboo/500GB/Dev/QT/header_docu_qt/Plugins/parser/libhd_doxygen_parser_plugin.so"
Loaded:  "/media/zb_bamboo/500GB/Dev/QT/header_docu_qt/Plugins/parser/libhd_doxygen_parser_plugin.so"
Test from  "doxygen"  Plugin:  "Test: header_docu plugin"
Plugin Name:  "doxygen"
Plugin Version:  "doxygen header parser-v1.0.0"
Loading... "/media/zb_bamboo/500GB/Dev/QT/header_docu_qt/Plugins/parser/libhd_ghmd_parser_plugin.so"
Loaded:  "/media/zb_bamboo/500GB/Dev/QT/header_docu_qt/Plugins/parser/libhd_ghmd_parser_plugin.so"
Test from  "gh_markdown"  Plugin:  "Test: header_docu plugin"
Plugin Name:  "gh_markdown"
Plugin Version:  "Github Markdown parser-v1.0.0"
Loading... "/media/zb_bamboo/500GB/Dev/QT/header_docu_qt/Plugins/writer/libhd_ghmd_writer_plugin.so"
Loaded:  "/media/zb_bamboo/500GB/Dev/QT/header_docu_qt/Plugins/writer/libhd_ghmd_writer_plugin.so"
Test from  "gh_markdown"  Plugin:  "Test: header_docu plugin"
Plugin Name:  "gh_markdown"
Plugin Version:  "Github Markdown writer-v1.1.0"
Loading... "/media/zb_bamboo/500GB/Dev/QT/header_docu_qt/Plugins/writer/libhd_json_writer_plugin.so"
Loaded:  "/media/zb_bamboo/500GB/Dev/QT/header_docu_qt/Plugins/writer/libhd_json_writer_plugin.so"
Test from Plugin:  "json" :  "Test: header_docu plugin"
Plugin Name:  "json"
Plugin Version:  "json writer-v1.0.0"
"2023-04-25 19:17:13"  :  840  File(s) parsed with  "doxygen"  header parser. Output stored with format  "json"  in folder:  "/media/zb_bamboo/500GB/Dev/C/ESP32/Arduino_ESP32_libs/Docu"

the end

🖖

(back to top)