zhuhaijun753 / 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