Switch docs to use Sphinx (#169)

* Remove old doc

Signed-off-by: Travis F. Collins <[email protected]>

* Add Sphinx doc

Signed-off-by: Travis F. Collins <[email protected]>

* Fix logo generation

Signed-off-by: Travis F. Collins <[email protected]>

* Logo gen fixes

Signed-off-by: Travis F. Collins <[email protected]>

* Add sphinx_design dependencies

Signed-off-by: Travis F. Collins <[email protected]>

* Fix CI targets

Signed-off-by: Travis F. Collins <[email protected]>

* Update doc about generating doc

Signed-off-by: Travis F. Collins <[email protected]>

* Add logo for Toolbox back

Signed-off-by: Travis F. Collins <[email protected]>

---------

Signed-off-by: Travis F. Collins <[email protected]>

.github/workflows/build.yml

@@ -16,8 +16,8 @@ jobs:
       - name: Organize Toolbox Dependencies
         run: |
             make -C ./CI/scripts build
-            pip3 install -r requirements_doc.txt
-            make -C ./CI/gen_doc doc_ml
+            pip3 install -r CI/doc/requirements_doc.txt
+            make -C CI/doc gen_autodocs html
             make -C ./CI/scripts add_libad9361
 
       - name: Set up MATLAB

.github/workflows/doc.yml

@@ -16,10 +16,10 @@ jobs:
       - name: Install dependencies
         run: |
           sudo apt install -y python3-numpy
-          pip install -r requirements_doc.txt
+          pip install -r CI/doc/requirements_doc.txt
       - name: Check doc build
         run: |
-          make -C CI/gen_doc doc
+          make -C CI/doc gen_autodocs html
 
       - name: Publish master doc
         if: github.ref == 'refs/heads/master'

.gitignore

@@ -3,3 +3,4 @@
 **/slprj/**
 AD9361_Filter_Wizard/*TestFiltWiz*.m
 AD9361_Filter_Wizard/.previous_ip_addr
+_generated/*

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
+```