search

ihhub / penguinV

Computer vision library with focus on heterogeneous systems
Other
119 stars 90 forks source link

Move documentation to Doxygen comments #687

Open ihhub opened 2 years ago

ihhub commented 2 years ago

This is not scalable to keep a separate file for documentation. There are many tools in the wild and one of them is Doxygen which is designed just for this purpose.

zafar-hussain commented 2 years ago

hi @ihhub,

I looked into this issue, and a few points came up, namely

  1. multiple Api descriptions documents : can these be renamed eg., cuda's api_description file as cuda_api_description.md, reason is doxygen parses the directories, it lists all similar named doc together, and causes confusion, or these docs are to be removed.

  2. multiple readme.md, same as above. ignore the readme.md in the root, that will stay

  3. contributing.md needs a bit to tyding for doxygen

  4. should separate issues be raised for for each class documentation, it will be easier to keep track

  5. do you have any logo for penguinV, so that it can be used in the docs

  6. any preferred format like html, pdf, xml for the docs, or we are to only provide a docfile plus instructions for the user to to generate the docs in their preferred format, using doxygen

cheers

ihhub commented 2 years ago

Hi @zafar-hussain , documentation generation in Doxygen is based on comments in the source code. What previously was done is to update the documentation manually which absolutely not a proper approach. Doxygen allows to generate the documentation automatically.

Doxygen can be also configured which types of tiles to be scanned. I think the first step is to add Doxygen as a part of GitHub Actions pipeline at the least to generate documentation. Answering your ideas:

  1. Yes, we can. It makes more sense.
  2. Readme.MD is picked by Github automatically. We need to see if it's possible to do such.
  3. Can you explain why? Doxygen is going to scan only the source code files
  4. It would be a lot of issues. It is better to create one with multiple checkboxes.
  5. Nope.
  6. For now just instructions. Once we are going to be close to release we will include it into an archive. Also we can generate these files as a part of GitHub Actions pipeline.
zafar-hussain commented 2 years ago

hi @ihhub

thanks for the reply,

for point 3, I allowed doxygen to parse *.md files too, and it created nice looking help pages from them too,

eg. image

ihhub commented 2 years ago

Hi @zafar-hussain , looks great, How would you like to proceed with it?

zafar-hussain commented 2 years ago

Hi @ihhub,

Sorry, I can't work on this project due to lack of time.

Cheers