Feature/gh4 select documentation tool

rdkcentral / python_raft

RAFT is a Python based testing framework for writing engineering tests. It provides a modular, config driven, low level testing framework

Apache License 2.0

3 stars 0 forks source link

Feature/gh4 select documentation tool #35

Closed TB-1993 closed 5 months ago

TB-1993 commented 6 months ago

I have added samples of documentation created using doxygen, sphinx and breath for the commandModules. I figured we could use them to choose the tool we want to use. I have generated both html and markdown format using sphinx and breathe. Github pages can be configured to work with either.

Each has an index.html/index.md file in the build directory that is the starting point for the docs.

@zghp @Ulrond @barbourshop

rdkcmf-jenkins commented 6 months ago

Copyright scan failure

Commit: 52262051abccee186b4d8ad57406c3bee3b3c68b Report detail: https://gist.github.com/rdkcmf-jenkins/5ffa85a5895f2b7aef69c6317616b74d

rdkcmf-jenkins commented 6 months ago

Blackduck scan failure details

Summary: 0 violations, 0 files pending approval, 136 files pending identification.

Protex Server Path: /home/blackduck/github/python_raft/35/rdkcentral/python_raft
Commit: 52262051abccee186b4d8ad57406c3bee3b3c68b

Report detail: gist

rdkcmf-jenkins commented 6 months ago

Coverity detected 84 issues; a security concern.

zghp commented 6 months ago

for Doxygen:

easy to set up and configure
automated code extraction and support for graphical diagrams (without the aid of external tools, unlike Sphynx)
useful if there are c/c++ components present within the project

for Sphynx:⁠

specifically designed for documenting Python projects
more freedom and flexibility while documenting
have the possibility to customise the theme to match the Sky branding (if relevant)
various extensions and plugins available

Look-wise, Doxygen would be good to use for a more familiar "vibe" but , personally, I would go with Sphynx since it has a modern look, it's made for Python and, since the project is intended to be used outside of Sky at some point, more attractive to new users.