API documentation upgrade

[mtravaillard]

In this PR :

all the available function, macro or "subfunction" has been documented.
For each, there is a sentence to give the big picture of what the function does, also a description for each parameters and arguments.

Verisc have also been deleted in this PR, as it was deprecated.

An api config file has been added, to easily add or delete file from cminx rST generation.

All function and macro are also now included in the documentation, in the past some were missing, it's now possible due to a full recursive search, thanks to the api config file. Some files or directory have been explicitly removed from the API documentation, because they were now included but we didn't need them.

To try:

If you could try to look at the change in local, you need to do the same way than to build the docusaurus documentation, but it's not the same target.
You don't need to build the full website, you should just run make api_doc, several files will be generated.
You need to open SoCMake/docs/build/api_html/html/index.html in firefox or whatever you want, to be able to easily navigate through the API documentation.

I would like to know if I have missed some typos, if some writing things are wrong due to a misunderstanding or else.

To discuss:

Should we change the theme for this documentation ? I quickly tried other theme, this one is the only one that have a nice navigation tree on the side. I could spend more time to try to see how to do it on other theme if we want to change it.

I think that in the future, we should create a rule, so if a new function is added in the cmake directory, we shouldn't merge as long as it doesn't have a comment for documentation.
This way, the documentation will stay clean and updated.

And should I fix #192 in this PR ?

[mtravaillard]

Maybe we can also discuss about some function, especially those starting by __function_name that aren't supposed to be called directly, if they should appear or not in the API documentation.

In any case, I think it's still useful to have a small comment to explain briefly what the function does.

But having too many function in the API (that are not directly useful) might be confusing for external users...

[Risto97]

I agree with excluding the internal functions from the documentation.
Maybe we will need to patch cminx to ignore these functions

[mtravaillard]

no it won't need lot's of changes, cminx recognize doccomment if they start by [[[ and end ]] and when can choose to include or not undocumented function, macro or others, so it will be an easy fix

[mtravaillard]

I have done a few last small changes on the main pages of the documentation, from what Anvesh showed/recommended me.

@benoitdenkinger @Risto97 Is everything fine on your side for this PR ? Once you agree with this, I will resolve the conflict with the removed verisc and merge it to develop.

[Risto97]

Hello @mtravaillard ,

Sorry, will not have time to go through all the changes, as there are quite a bit.
But it looks fine for me, I am fine with merging it.

Great work on going through this, its a lot of work you done!

[benoitdenkinger]

It's fine for me too