Docs findings/challenges

[danwos]

Thanks for the great extension ;)

I try to understand some details and to use it in my project, but as user I have some problems to follow the docs. So here is a generic list. Happy to help here, when I have some time.

Workflow

I don't get it how this extension, the cli tool, the directive and the config are working together.

• How is the config of the Analysis Page linked to the Sphinx config? What are the commands to use it?
  • Would be good to name the tabs Input (cpp) and Output (json)
  • "Oneline needs" should be explained or at least highlighted here as well. There is only a small one-line, that it is supported as well.
• Is the Command line the first class citizen and the Sphinx integration minor important? Need to ask this, as it is given as first sidebar-entry under "Components" but the page has zero description for what it is needed in the user workflow.
  • Also it does not explain what the output of the commands is. Their explanation just uses "analyse ..." and "discover ...". Sounds for me like task without an output.

Introduction pieces

In general, the docs are very technical and often start directly describing a detail. Some kind of overview or introduction is missing.
For instance: One line comment style
It explains the motivation of having it and then directly explains the options.
But I don't see any configuration reference at the beginning, so that it's hard to understand where and how these options shall be used. Only a link to the config-page, where I can find this most important piece of information.

Also some examples would be good, which configurations allow me to use what kind of comment style.
It is much easier to learn by example.

Local link

I don't understand why it is not available, as it is a link to a HTML page.
If it would be a direct link to a c/cpp file, ok, that can't work
But a HTML file should be part of the Sphinx project, or not?
It's even linking to data in the _build folder, but it is a absolute link, not a relative one. Maybe that's the problem.

[danwos]

What are the allowed options for the comment_type?

What does it mean if set to "c"?
What kind of comments are supported? Some rough examples per language or a link would be good.

[danwos]

First Directive example code should not contain optional options.
https://codelinks.useblocks.com/components/directive.html

That :file: or directory is optional, is somewhere hidden 5 sentences later.
That's confusing, as it looks like you have to use one of these options.