Doc update working example

[SrikanthPagadarai]

No description provided.

[tfcollins]

Remove use of the main function abstraction. It just makes the examples confusing and wastes space

[SrikanthPagadarai]

Updated.

[tfcollins]

myst is complaining about cross references.

WARNING: 'myst' cross-reference target not found

Need to add this to the conf.py

# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ["breathe", "sphinx.ext.autodoc", "myst_parser", "sphinx_inline_tabs", "sphinx.ext.graphviz"]

+# Fix use of autogenerated cross-reference warning
+myst_heading_anchors = 2

# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]

[SrikanthPagadarai]

myst is complaining about cross references.

WARNING: 'myst' cross-reference target not found

Need to add this to the conf.py

# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ["breathe", "sphinx.ext.autodoc", "myst_parser", "sphinx_inline_tabs", "sphinx.ext.graphviz"]

+# Fix use of autogenerated cross-reference warning
+myst_heading_anchors = 2

# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]

Updated conf.py.

[tfcollins]

This package needs to be added to the requirements_doc.txt

[tfcollins]

filename should be descriptive

[tfcollins]

Heading directive "======" too short. Needs to be as long as text

[tfcollins]

We use Python to illustrate this workflow in the current section. The data that we will process using Genalyzer for this example is also generated using Genalyzer. It consists of a 300 KHz tone sampled at 3 MSPS. The only source of noise in this synthetic data is quantization noise.

This doesn't flow very well. Can you simplify it a bit?

[tfcollins]

Expand the code-snippet below for details.

Remove the text and keep the code expanded by default

[tfcollins]

Refrain from using "i.e." a lot. It can be distracting.

I don't really understand the point of this paragraph. Are you trying to explain how to use the fft function? its flexibility? or its nuanced API?

For individual arguments just refer users to the reference doc. This shouldn't be a copy+paste of that here.

This section is "Compute FFT" but it probably needs to be more specific on the data types used since that's what drives everything.

[tfcollins]

Aren't we on like step 2 at this point?

This key is used for all configuring Genalyzer further

I think you meant configuration and not configuring

Can we use some other name than "object_key"? Is there something more relatable we can use?

[tfcollins]

Is there a way to inspect it?

[tfcollins]

The next step is to identify the signal tone and label it. This is done by calling either fa_fixed_tone() or fa_max_tone() functions. In both cases, the first two arguments are keys. The first key is the object_key mentioned previously, and the second key is a string that is to be associated with the signal component whose magnitude is measured and used subsequently when computing performance metrics. In both cases, the third argument is a tag which maps to the component type. To identify a component as the signal tone, we use GnFACompTagSignal. The other tags available are shown here. As the name indicates, fa_max_tone() interprets the tone with the highest magnitude as the signal to

The descriptions of keys and tags here is a bit confusing. Is there a plain way to describe what they are for?

[tfcollins]

it is useful for taking into account any desired tone that is pertinent to analysis.

I think its more than useful, its actually required in this case right?

[tfcollins]

Image files should not be in source code folders. They need to be located with doc.

[SrikanthPagadarai]

Fixed.

[tfcollins]

This is no real code in the page. Am I missing something?

[SrikanthPagadarai]

I'm pointing readers to files in this manner:

genalyzer/doc/spectral_analysis.md

Line 164 in 31b210b

In [this](../../../bindings/python/examples/gn_doc_spectral_analysis1.py) Python script, FFT analysis is run by the following line:

There are small code blocks also:
https://github.com/analogdevicesinc/genalyzer/blob/50cd0f1eed1e1bf2951097406ecf2520cbbba578/doc/spectral_analysis.md?plain=1#L123C1-L123C23

genalyzer/doc/spectral_analysis.md

Line 136 in 50cd0f1

```{code-block} python

genalyzer/doc/spectral_analysis.md

Line 165 in 50cd0f1

```{code-block} python

genalyzer/doc/spectral_analysis.md

Line 201 in 50cd0f1

```{code-block} python

[tfcollins]

This is really hard to follow. Code snippets should be in the doc so people don't have to keep context switching

[tfcollins]

See comments

[tfcollins]

I think this is in good shape. Can you clean up the git history and we'll merge