Chinese readme	English readme

介紹

Doxygen Plugin for Qt Creator
此專案 fork 於 https://github.com/fpoussin/qtcreator-doxygen , 並新增以下功能

1. 新增快速建置 doxygen 並開啟自動開啟輸出網頁功能
2. 完善此專案的 Github actions CI 配置
3. 補充 doxygen config 使用範例

專案資訊

License	Release	Download	Issues	Wiki

前置作業

Qt Creator Source code 編譯及配置

1. 下載 Qt creator source code

• 方法1. download release

      wget https://download.qt.io/official_releases/qtcreator/4.13/4.13.3/qt-creator-opensource-src-4.13.3.tar.xz
  

• 方法2. github clone (should checkout to yuor traget branch)

  git clone https://github.com/qt-creator/qt
  

2. 編譯

• 方法1. 手動編譯

  • 建置 Qt 5.14 以上的編譯環境
  • 編譯 source code

• 方法2. 下載編譯好的檔案

  • Linux (Qtc 4.13.3)
    • https://download.qt.io/official_releases/qtcreator/4.13/4.13.3/installer_source/linux_x64/qtcreator.7z

> 其他平台請於以下連結尋找  
  https://download.qt.io/official_releases/qtcreator/

安裝相關套件

• Ubuntu system

  1. doxygen

  sudo apt-get install doxygen -y

  2. doxyqml pulgin

  sudo apt-get install python3
  git clone https://invent.kde.org/sdk/doxyqml.git
  cd doxyqml
  ./setup.py build
  sudo ./setup.py install

  Check

  whereis doxygen
  whereis doxyqml
  

• Windows system

  1. doxygen

    https://www.doxygen.nl/download.html
    (下載完成後，需設定 PATH 環境變數)
  

  2. doxyqml pulgin

  請先裝 Windows 版的 python3

  git clone https://invent.kde.org/sdk/doxyqml.git
  cd doxyqml
  python setup.py build
  python setup.py install

  Check

  doxygen --version
  doxyqml --version
  

編譯方式

使用 Command line

• 需要設定 QTC_SOURCE 及 QTC_BUILD 環境變數
• QTC_SOURCE: Qt creator sorce code 路徑
• QTC_BUILD Qt creator sorce code compile 建置路徑 (或者選擇已編譯好安裝檔路徑)
• USE_USER_DESTDIR 自動安裝模組
• Example command:

qmake USE_USER_DESTDIR=yes QTC_SOURCE=\~/src/qt-creator-opensource-src-4.13.3 QTC_BUILD=\~/qtcreator-4.13.3* .  

make

使用 Qt Creator

• Step1. 手動新增 QTC_SOURCE 及 QTC_BUILD 環境變數， 操作說明如下：

右方專案選項-> build & run (build) -> build environment -> 新增 QTC_SOURCE 以及 QTC_BUILD 環境變數

• Step2.執行建置專案

輸出檔案

編譯完成後 libDoxygen.so 將輸出於 Qt creator sorce code compile 建置路徑

e.g. build-qtcreator-4.13.3/lib/qtcreator/plugins/libDoxygen.so

Qt Creator 安裝 Doxygen plugin 方式

• 將編譯/下載的 libDoxygen.so 放置 Qt Creator 安裝目錄下的 lib/qtcreator/plugins/
• 重新啟動 Qt Creator

配置 Doxygen plugin

1. 將 qtcreator-doxygen/doxygen_config_examle/Doxygen 移動至您所定的目錄:

• e.g.

  cp -R qtcreator-doxygen/doxygen_config_examle/Doxygen ~/Doxygen
  

或者可以使用建立連結的方式：

• e.g.

  ln -s ~/qtcreator-doxygen/DoxygenConfig.example ~/Project/Doxygen
  

2. 開啟 qtcreator -> 選項 -> doxygen -> 配置以下項目：

• Doxygen Configuration

  Item	Description	value
  cpp doxygen config file	c++ doxygen config example	~/Doxygen/doxygen_cpp
  Qml doxygen config file	qml doxygen config example	~/Doxygen/doxygen_qml
  python doxygen config file	pythondoxygen config example	~/Doxygen/doxygen_py
  Docs doxygen config file	mrakdown doxygen config example	~/Doxygen/doxygen_doc
  Output Directory	doxygen Output Directory	~/doxytemp
  doxygen command path	doxygen execute Directory	/usr/bin/doxygen
  Doxywizard command path	doxygen GUI tool Directory	/usr/bin/doxywizard
  Auto open result html file	Set web browser path & arg	/usr/bin/firefox , -new-window

3. Comments Settings

Comment style:

自動產生的 comment 可選擇以下三種style

• JavaDoc / Qt / Custom (由右方 Custom comments setting 配置)

e.g. Custom C# base style

    ///
    /// @brief    
    /// @fn runCommand
    /// @param command
    /// @param arguments
    /// @param workingDirectory
    ///
    void runCommand(QString command, const QStringList& arguments, QString workingDirectory);

File to Comments:

• Header / implementation / All

Print bref tag

自動產生的 comment 是否有 bref tag

Short variable document

• enable

QString message; /*!< TODO: describe */

• disable

    /*!
     \brief 
    
     \var message
    */
    QString message;

Verbose (fn,var,class file ...)

自動產生的 comment 是否開啟自動判斷產生對應的 Verbose macro

Automatically add retrun type

自動產生的 comment function 是否自動產生 retrun type tag

Comment file

file macro 是否自動新增自定義字串(由右方 file comments setting 配置自定義的 Comment)

進階應用

Diagrams and Images in Doxygen

1. DOT graphs

• 安裝

  • linux

    sudo apt-get install graphviz -y
    

  • windows
    https://graphviz.org/download/#windows
    (需設定 PATH 環境變數)

• 確認安裝及配置是否成功

  dot -V
  

• Doxygen 配置

  DOT_PATH = /usr/bin/dot #安裝目錄
  DOTFILE_DIRS = DIA_file #DOT檔案目錄(設定檔為root Path)
  DOT_GRAPH_MAX_NODES
  DOT_MULTI_TARGETS
  DOT_CLEANUP

• 使用說明

  • macro

    @dot
    <your graphviz code>
    @enddot
    

  • import dot file

    @diafile dot_test.dot
    

2. MSC sequence diagrams

• 安裝

  • linux

      sudo apt-get install -y mscgen
  

  • windows
    https://www.mcternan.me.uk/mscgen/
    (需設定 PATH 環境變數)

• 確認安裝及配置是否成功

  mscgen -l
  

• Doxygen 配置

   MSCFILE_DIRS = MSC_file #*.msc 檔案目錄(設定檔為root Path)

• 使用說明

  • macro

    @msc
    <your plantuml code>
    @endmsc
    

  • import dot file

    @mscfile msc_test.msc
    

3. plantuml

• 安裝

  • linux

        sudo apt-get install plantuml -y
    

  • windows
    https://plantuml.com/zh/download
    (需設定 PATH 環境變數)

• 確認是否安裝成功

  whereis plantuml
  plantuml -version
  

• Doxygen 配置

  PLANTUML_JAR_PATH = …/…/jar #PLANTUML jar 檔案目錄
  PLANTUML_CFG_FILE =
  PLANTUML_JAR_PATH =

• 使用說明

  • macro

    @startuml
    <your plantuml code>
    @enduml
    

4. dia

• 安裝

  • linux

        sudo apt-get install -y dia
    

  • windows
    http://dia-installer.de/download/index.html
    (需設定 PATH 環境變數)

• 確認是否安裝成功

  dia -v
  

• Doxygen 配置

      DIA_PATH = /usr/bin/dia #安裝目錄
      DIAFILE_DIRS = DIA #DIA檔案目錄(設定檔為root Path)

• 使用說明

  • import DIA file

    @diafile test.dia
    

Wavedrom in Doxygen

wavedrom 介紹

• 使用說明

於 doxygen htmlonly macro 中加上以下內容：

\htmlonly
<script src="https://cdnjs.cloudflare.com/ajax/libs/wavedrom/2.6.8/skins/default.js" type="text/javascript"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/wavedrom/2.6.8/wavedrom.min.js" type="text/javascript"></script>

<script type="WaveDrom">
----------------------- your wavedrom code -------------------------
</script>

<script type="text/javascript">(function() {try {WaveDrom.ProcessAll();} catch(e) {}})();</script>
\endhtmlonly

• example:

\htmlonly
<script src="https://cdnjs.cloudflare.com/ajax/libs/wavedrom/2.6.8/skins/default.js" type="text/javascript"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/wavedrom/2.6.8/wavedrom.min.js" type="text/javascript"></script>

<script type="WaveDrom">
{ signal: [
  { name: 'A', wave: '01..0..',  node: '.a..e..' },
  { name: 'B', wave: '0.1..0.',  node: '..b..d.', phase:0.5 },
  { name: 'C', wave: '0..1..0',  node: '...c..f' },
  {                              node: '...g..h' }
  ],
  edge: [
    'b-|a t1', 'a-|c t2', 'b-|-c t3', 'c-|->e t4', 'e-|>f more text',
    'e|->d t6', 'c-g', 'f-h', 'g<->h 3 ms'
  ]
}
</script>

<script type="text/javascript">(function() {try {WaveDrom.ProcessAll();} catch(e) {}})();</script>
\endhtmlonly

• 輸出

  

使用 Demo

• Document current entry

• Document current file

• Build doxygen And Open HTML

TODO

1. cmake support
2. Windows 平台 Qt creator 4.14.x 無法編譯成功問題
3. doxygen for python support
4. add github page support