1434cga/cgadoxygen

Doxygen PERLMOD to Markdown converter(v0.9) to support ASPICE (Automotive SPICE)

1. About CGADOXYGEN
1.1. Purpose
1.2. Backgrounds
2. Environment of Development
2.1. Prerequisition
2.2. docker to make an environment easily
3. How to Run
3.1. make a documents automatically
3.1.1. If you have unsolved problems in installing tools
3.2. example
3.3. clean
4. Docker
4.1. How to use docker in detail
5. What is the result

    ___   ___    __      ____   _____  _  _  _  _   ___  ____  _  _
   / __) / __)  /__\    (  _ \ (  _  )( \/ )( \/ ) / __)( ___)( \( )
  ( (__ ( (_-. /(__)\    )(_) ) )(_)(  )  (  \  / ( (_-. )__)  )  (
   \___) \___/(__)(__)  (____/ (_____)(_/\_) (__)  \___/(____)(_)\_)

1. About CGADOXYGEN

• Doxygen PERLMOD to Markdown & Word & Excel converter for supporting ASPICE
  • It is helpful to make a documents from source code and your doxygen comments.
  • It is helper of doxygen.

1.1. Purpose

• Reduce the tedious jobs (LLD : Low level Design documents). When we make a document for customer , we should make a markdown & word & excel documents with detailed class information.
• and I hop it is helpful to save your time for your life.
  • Some customer Wants
    • want detailed documents like LLD (Low Level Design).
    • LLD should include the detailed information for Class and your source code.
  • Deliverables
    • upport word and xlsx file for detailed documents.

1.2. Backgrounds

• Doxygen comments is the best method as a good programmer
• Always synchronize source and documents
• Doxygen gives some warning to you when your comments mismatch with your code.
  • it is helpful for us to make a better source and comments (documents)
• I think that doxygen is a de facto standard in open source.
• It gives improving your international skills.

2. Environment of Development

2.1. Prerequisition

• ubuntu package : python-dev python-pip python-setuptools javacc java-common pandoc doxygen vim python3-pip python3-setuptools graphviz
• perl module ( Excel::Writer::XLSX )
  • cpan Excel::Writer::XLSX
• hpp2plantuml
• markdown-pp

2.2. docker to make an environment easily

• docker pull cheoljoo/ubuntu16:cgadoxygen
  • Command

3. How to Run

• How to make a document (LLD & SDD) automatically

3.1. make a documents automatically

• (optional) if you have many subdirectories , you try to run copy.sh at first.
  • sh copy.sh [SOURCE DIRECTORY] [DESTINATION STORAGE Name]

    sh copy.sh ../../OUTPUT/stc  ./src

• sh run.sh { lists of directories including your codes (cpp and h) }
  • if you run copy.sh (destination : ./src)

    $ sh run.sh ./src

  • ex) if you have sources in ../.. ../../inc /home/user/src , then

    $ sh run.sh ../..  ../../inc  /home/user/src

  • directory list is not recursive
    • you can verify in ./CGADoxygen/build_doxygen/src as soft-link files.
• OUTPUT will be generated in "[git repository directory]/build_perlmod/OUTPUT"
  • LLD (Low Level Design) Document : it is full document
  • NECE (Necessary) LLD : it is necessary document. I remove the doc when they do not have doxygen comments.
  • SEQU (Sequential) LLD : it solves the detailed information each function sequentially. it will support multiple plantuml and note and details.

OUTPUT	HTML	Markdown
Low Level Design (LLD)	LLD.css.html	LLD.md
NECE (Necessary) LLD	nece.css.html	nece.html.md
SEQU (Sequential) LLD	sequ.css.html	sequ.html.md

3.1.1. If you have unsolved problems in installing tools

• Show "How to install tools" of https://github.com/cheoljoo/CGADoxygen/blob/master/reference/README.md

3.2. example

    $ sh run.sh ./example/A  ./exampleC   ./exampleD/Source
    or 
    $ sh run.sh example/B

3.3. clean

    $ sh run.sh clean

4. Docker

4.1. How to use docker in detail

• docker image pull

  • $ docker pull cheoljoo/ubuntu16:cgadoxygen
  • $ docker run -it -v /home/username/doxygen:/docker --name cga1 cheoljoo/ubuntu16:cgadoxygen /bin/bash
    • /home/username/doxygen : is your host directory to use for your code
    • /docker : is directory in docker shell
  • $ docker ps -all

    CONTAINER ID        IMAGE                          COMMAND     CREATED             STATUS                   PORTS               NAMES
    74027e97f2b8        cheoljoo/ubuntu16:cgadoxygen   "/bin/bash" 12 days ago         Exited (1) 12 days ago                       cga1
    

  • $ docker start cga1
  • $ docker attach cga1

• docker shell

  • cd /docker
    • you can see files in host (/homeusername/doxygen)
  • cd /tmp/CGADoxygen
    • copy your source_code in /tmp/CGADoxygen/YourName
    • sh run.sh YourName
    • you can find the result (SDD.html) in /tmp/CGADoxygen/build_perlmod/

• How to make Docker Environment in detail - NEW

  • Docker Environment in detail - old

5. What is the result

• Architecture
  • 
• Deliverables (SDD Component)
  • HLD Documents (HLD.md HLD.docx) : High Level Design from HLD.plantuml.md
    • 
  • LLD Documents (LLD.md LLD.docx LLD.xlsx) : Low Level Design generated from doxygen comments automatically
    • 
    • 
  • SDD Documents (SDD.md SDD.docx) : It is final result combined with HLD and LLD
    • 
• screenshot

working note

• 2022-07-15 : cga2nece.pl
  • this job is for code beamer upload.
  • upload destination : http://10.158.14.216:8080/cb/tracker/16558297
  • build_perlmod/makefile
    • perl cga2nece.pl default.GV OUTPUT/nece.html.md > c_nece.log
    • cga2nece.pl : "nece.html.md" is final document.
      • log : c_nece.log
  • code beamer wiki format document : https://codebeamer.com/cb/wiki/8730#section-Basic+formatting
  • deliverables : nece.perl.data , nece.python.data

cgadoxygen's Issues

Some target-specific paths are used

I found a target-specific path from the warning log:

warning: source /home/cheoljoo/code/common_telltale/GP/Apps/Src/MgrTelltale/CGADOXYGEN/build_doxygen is not a readable file or directory... skipping.

They should be removed (if not needed) or replaced to the correct path.

write documents sequentially

write documents sequentially.

• show the documents sequentially according to doxygen comments

current docker is not working well.

update docker to use easily.

test for multiple lines of SRS (alias) & remove @step

• @srs : multiple lines
• @step :
  • remove @step
  • replace it to @details

Stuck on installing hpp2plantuml

I am stuck on the very 1st step. When I ran run.sh, I got the following error:

Do install hpp2plantuml
Method-1. run setting_env_user_mode.sh in current directory
Method-2. Install by  yourself  from URL)   https://github.com/thibaultmarin/hpp2plantuml

so I did Method-1. Then, I got another error:

hpp2plantuml
#### Checking < hpp2plantuml > Package ####
#### Install hpp2plantuml package ####
Cloning into 'hpp2plantuml'...
remote: Enumerating objects: 295, done.
remote: Total 295 (delta 0), reused 0 (delta 0), pack-reused 295
Receiving objects: 100% (295/295), 129.42 KiB | 0 bytes/s, done.
Resolving deltas: 100% (148/148), done.
Checking connectivity... done.
Traceback (most recent call last):
  File "setup.py", line 7, in <module>
    from setuptools import setup, find_packages, Command
ImportError: No module named 'setuptools'

To resolve this, I installed setuptools by pip:

pip install setuptools --user

but got the error above again.

(Actually, I got another error first (fatal: destination path 'hpp2plantuml' already exists and is not an empty directory.) It was resolved after I removed ./tmp directory. You had better fix setting_env_user_mode.sh to remove ./tmp before cloning http2plantuml)

How can I resolve this dependency issue?

• IMHO, describing prerequisites at README.md (or INSTALL.md) is very useful.

doxygen : Can I remove doxygen document with @cond?

EXTRACT_ALL = NO
HIDE_NODOC_CLASS = YES

Verify whether it makes doxygen documents or not when we use @cond
210 /**
211 * @cond TTT
212 * test
213 * @endcond
214 */

result : make doxygen documents without any comments in /** /
So we should remove /* */ not to show doxygen documents

Could we support to remove the doxygen documents when contents is empty?

show the title only when it has contents

• show title when it has contents.
• member functions
• private functions
• class