First commit of doc with new folder org

Signed-off-by: spagadar <[email protected]>

CI/ci_flags.md

@@ -0,0 +1,7 @@
+# CI Signaling
+
+Its possible to configure CI on build a project based on flags in the commit message. This is done by adding a special line to the commit that starts with CI: (must be all caps). The line can contain a list of flags separated by semi-colons. The following flags are supported:
+- skip=<Name of stage>
+- skip_branch=<Name of parallel branch to skip>:<Name of parent stage>
+- enable_only_branch=<Name of parallel branch to enable>:<Name of parent stage>
+- env:<Name of environment variable>=<Value of environment variable>

CI/doc/Makefile

@@ -0,0 +1,28 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+PYTHON		  = python
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+gen_autodocs:
+	cd gen_pages ; \
+	$(PYTHON) gen_sysobj_pages.py ; \
+	$(PYTHON) gen_rd_svg.py ; \
+	$(PYTHON) gen_hdl_refdesigns.py

CI/doc/README_doc.md

@@ -0,0 +1,24 @@
+# Doc Creation
+
+Doc is create by leveraging Sphinx as the documentation engine. To create the entire documentation set you must generate the dynamic pages which document the system object APIs and the reference designs. Then the output targets can be run. Since doc gen requires sphinx and some plugins they need to be installed first and ideally in a virtual environment. The following commands will create a virtual environment and install the necessary packages:
+
+```bash
+python3 -m venv venv
+source venv/bin/activate
+pip install -r CI/doc/requirements_doc.txt
+```
+
+Next we can build the documentation. The following commands will build the documentation and place it in the *build* folder under the *CI/doc* folder:
+
+```bash
+make -C CI/doc gen_autodocs html
+```
+
+## Updating the System Object Documentation
+
+The system object documentation is generated from the MATLAB code and comments, which requires use of MATLAB itself. By running the script gen_sysobj_doc.m within the *gen_pages* folder, it will create the necessary sysobjs.json file which sphinx will then use to create the individual component pages. This is done by running the following command from the root of the toolbox in MATLAB:
+
+```matlab
+cd CI/doc/gen_pages
+gen_sysobj_doc
+```

CI/doc/gen_pages/Makefile

@@ -0,0 +1,14 @@
+# Define the Python interpreter
+PYTHON = python
+
+# Define the targets and their dependencies
+all: gen_sysobj_pages gen_rd_svg gen_hdl_refdesigns
+
+gen_sysobj_pages:
+	$(PYTHON) gen_sysobj_pages.py
+
+gen_rd_svg:
+	$(PYTHON) gen_rd_svg.py
+
+gen_hdl_refdesigns:
+	$(PYTHON) gen_hdl_refdesigns.py

CI/doc/gen_pages/_templates/allrefdesigns.tmpl

@@ -0,0 +1,20 @@
+{% include 'header.tmpl' %}
+# HDL Reference Designs
+
+Available hardware streaming interfaces in HSX Toolbox:
+<!--
+- [{{ obj }}](matlab:web([docroot '/3ptoolbox/analogdevicesinchighspeedconvertertoolboxtoolbox/doc/sysobjects/{{ obj }}/index.html']))
+-->
+
+```{eval-rst}
+.. toctree::
+   :maxdepth: 1
+{% for obj in designs %}
+   _generated/hdlrefdesigns/{{ obj }}
+{%- endfor %}
+
+```
+
+
+
+Click on left table of contents for individual component pages.

CI/doc/gen_pages/_templates/allsysobjs.tmpl

@@ -0,0 +1,20 @@
+{% include 'header.tmpl' %}
+# Hardware Interface APIs
+
+Available hardware streaming interfaces in HSX Toolbox:
+<!--
+- [{{ obj }}](matlab:web([docroot '/3ptoolbox/analogdevicesinchighspeedconvertertoolboxtoolbox/doc/sysobjects/{{ obj }}/index.html']))
+-->
+
+```{eval-rst}
+.. toctree::
+   :maxdepth: 1
+{% for obj in devices %}
+   _generated/sysobjects/{{ obj }}
+{%- endfor %}
+
+```
+
+
+
+Click on left table of contents for individual component pages.

CI/doc/gen_pages/_templates/header.tmpl

@@ -0,0 +1,7 @@
+{%- if disable_nav -%}
+---
+hide:
+  - navigation
+  - toc
+---
+{%- endif -%}

CI/doc/gen_pages/_templates/refdesign.html

@@ -0,0 +1,46 @@
+{% block content %}
+
+# {{ obj.name }} Reference Design Integration
+
+This page outlines the HDL reference design integration for the *{{ obj.name }}* reference design for the Analog Devices
+{{ obj.chip }} component. The IP-Core Generation follow is available on the based on the following base HDL reference design for the following board and design variants: 
+
+- [Base reference design documentation]({{ obj.hdl_rd_doc }})
+- Supported FPGA carriers: 
+{%- for carrier in obj.fpga %}
+    - {{ carrier.upper() }}
+{%- endfor %}
+- Supported design variants:
+{%- for supported_rd in obj.supported_rd %}
+    - {{ supported_rd.upper() }}
+{%- endfor %}
+
+## Reference Design
+
+  {% if obj.rd_image == "ad9361" %}
+```{figure} /_static/assets/rd_ad9361_custom.svg
+  {% elif  obj.rd_image == "adrv9001" %}
+```{figure} /_static/assets/rd_adrv9001_custom.svg
+  {% elif  obj.rd_image == "jesd" %}
+```{figure} /_static/assets/rd_jesd_custom.svg
+  {% endif %}
+HDL Reference Design with Custom IP from HDL-Coder. Click on sub-blocks for more documentation.
+```
+
+The IP-Core generation flow will integrate IP generated from Simulink subsystem into an ADI authored reference design. Depending on the FPGA carrier and FMC card or SoM, this will support different IP locations based on the diagram above.
+
+## HDL Worflow Advisor Port Mappings
+
+When using the HDL Worflow Advisor, the following port mappings are used to connect the reference design to the HDL-Coder generated IP-Core:
+
+| Type | Target Platform Interface (MATLAB) | Reference Design Connection (Vivado) | Width | Reference Design Variant |
+| ---- | ------------------------ | --------------------------- | ----- | ----------- |
+{%- for rds in obj.ports[0] %}
+
+{%- for rd in obj.ports[0][rds] %}
+| {{ rd['type'].upper() }}-{% if rd['input' == "true"] %}IN{% else %}OUT{% endif %} | {{ rd['m_name'] }} | {{ rd['name'] }} | {{ rd['width'] }} | {{ rds.upper() }} |
+{%- endfor %}
+
+{%- endfor %}
+
+{% endblock %}

CI/doc/gen_pages/_templates/sysobj.html

@@ -0,0 +1,94 @@
+{% block content %}
+# {{ obj.name }}
+<!-- <div class="sysobj_h1">{{ obj.name }}</div> -->
+
+<!-- <div class="sysobj_top_desc">
+Receive data from Analog Devices AD9361 transceiver
+</div> -->
+
+<!-- <div class="sysobj_desc_title">Description</div> -->
+
+<div class="sysobj_desc_txt">
+<span>
+{{ obj.dec }}
+</span>
+
+</div>
+
+<div class="sysobj_desc_title">Creation</div>
+
+The class can be instantiated in the following way with and without property name value pairs.
+
+```matlab
+dev = {{ obj.name }}
+dev = {{ obj.name }}(Name, Value)
+```
+
+<div class="sysobj_desc_title">Properties</div>
+
+<div class="sysobj_desc_txt">
+<span>
+Unless otherwise indicated, properties are non-tunable, which means you cannot change their values after calling the object. Objects lock when you call them, and the release function unlocks them.
+<br><br>
+If a property is tunable, you can change its value at any time.
+<br><br>
+For more information on changing property values, see <a href="https://www.mathworks.com/help/matlab/matlab_prog/system-design-in-matlab-using-system-objects.html">System Design in MATLAB Using System Objects.</a>
+</span>
+</div>
+<br>
+
+
+{% for prop in obj.props %}
+:::{dropdown} {{ prop.prop_name }}
+{{ prop.prop_description }}
+:::
+{% endfor -%}
+
+
+
+
+{% endblock %}
+
+<br>
+<div class="sysobj_desc_title">Example Usage</div>
+
+```matlab
+{% if obj.type == "Tx" %}
+%% Configure device
+tx = {{ obj.name }};
+tx.uri = 'ip:analog.local';
+{% if obj.name == "adi.ADRV9002.Tx" %}
+tx.CenterFrequencyChannel0 = 1e9;
+{% else %}
+tx.CenterFrequency = 1e9;
+{% endif %}
+tx.DataSource = 'DMA';
+tx.EnableCyclicBuffers = true;
+tx.EnabledChannels = 1;
+%% Generate tone
+amplitude = 2^15; frequency = 0.12e6;
+swv1 = dsp.SineWave(amplitude, frequency);
+swv1.ComplexOutput = true;
+swv1.SamplesPerFrame = 2^14;
+swv1.SampleRate = tx.SamplingRate;
+y = swv1();
+% Send
+tx(y);
+{% else %}
+%% Rx set up
+rx = {{ obj.name }}('uri','ip:analog.local');
+{% if obj.name == "adi.ADRV9002.Rx" %} 
+rx.CenterFrequencyChannel0 = 1e9;
+{% else %}
+rx.CenterFrequency = 1e9;
+{% endif %}
+rx.EnabledChannels = 1;
+%% Run
+for k=1:10
+    valid = false;
+    while ~valid
+        [out, valid] = rx();
+    end
+end
+{% endif %}
+```

CI/doc/gen_pages/gen_hdl_refdesigns.py

@@ -0,0 +1,83 @@
+from jinja2 import Environment, FileSystemLoader
+import os
+import json
+import numpy as np
+
+
+def update_hdl_refdesigns():
+
+    template_filename = "refdesign.html"
+
+    folder_of_this_file = os.path.dirname(__file__)
+    source_folder = os.path.join(folder_of_this_file, "..", "source")
+
+    ci_scripts_folder = os.path.join(folder_of_this_file, "..", "..", "scripts")
+
+    _generated_folder = os.path.join(folder_of_this_file, "..", "source", "_generated")
+    if not os.path.exists(_generated_folder):
+        os.mkdir(_generated_folder)
+
+    hdlrefdesigns_folder = os.path.join(_generated_folder, "hdlrefdesigns")
+    if not os.path.exists(hdlrefdesigns_folder):
+        os.mkdir(hdlrefdesigns_folder)
+
+
+    with open(os.path.join(ci_scripts_folder, "ports.json")) as f:
+        objs = json.load(f)
+
+    # Import template
+    loc = os.path.dirname(__file__)
+    loc = os.path.join(loc, "_templates")
+    file_loader = FileSystemLoader(loc)
+    env = Environment(loader=file_loader)
+
+    loc = os.path.join(template_filename)
+    template = env.get_template(loc)
+
+    designs = {}
+
+    for obj in objs:
+
+        print("Generating", obj)
+
+        # Render template
+        objs[obj]["name"] = obj
+
+        if objs[obj]["name"] in ["fmcomms2", "adrv9361z7035", "adrv9364z7020", "pluto"]:
+            objs[obj]["rd_image"] = "ad9361"
+        elif objs[obj]["name"] in ["adrv9002"]:
+            objs[obj]["rd_image"] = "adrv9001"
+        else:
+            objs[obj]["rd_image"] = "jesd"
+
+        output = template.render(obj=objs[obj])
+        # Write output
+        output_filename = os.path.join(hdlrefdesigns_folder, f"{obj}.md")
+        loc = os.path.join(output_filename)
+        f = open(loc, "w")
+        f.write(output)
+        f.close()
+        designs[obj] = output_filename
+
+    # # Update mkdocs.yml
+    # loc = os.path.join("mkdocs.tmpl")
+    # template = env.get_template(loc)
+    # output = template.render(designs=designs)
+
+    # loc = os.path.join("..", "mkdocs.yml")
+    # with open(loc, "w") as f:
+    #     f.write(output)
+
+    # Create allrefdesigns.md
+    loc = os.path.join("allrefdesigns.tmpl")
+    template = env.get_template(loc)
+    output = template.render(designs=designs)
+
+    loc = os.path.join(source_folder, "allrefdesigns.md")
+    with open(loc, "w") as f:
+        f.write(output)
+
+    return designs
+
+if __name__ == "__main__":
+    update_hdl_refdesigns()