Merge pull request #86 from BrennanGit/feature/doc_builder_v4

Feature/doc builder v4
xmos · Oct 20, 2023 · 681548b · 681548b
2 parents 797eb85 + dd68ccd
commit 681548b
Show file tree

Hide file tree

Showing 25 changed files with 63 additions and 39 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -25,7 +25,7 @@ on:
   workflow_dispatch: {}
 
 env:
-  DOC_BUILDER_IMAGE: 'ghcr.io/xmos/doc_builder:v3.0.0'
+  DOC_BUILDER_IMAGE: 'ghcr.io/xmos/xmosdoc:v4.0'
 
 jobs:
   build_documentation:
@@ -43,7 +43,8 @@ jobs:
       
       - name: Build documentation
         run: |
-          docker run --rm -t -u "$(id -u):$(id -g)" -v ${{ github.workspace }}:/build -e PDF=1 -e REPO:/build -e EXCLUDE_PATTERNS=/build/doc/exclude_patterns.inc -e DOXYGEN_INCLUDE=/build/doc/Doxyfile.inc -e DOXYGEN_INPUT=ignore ${DOC_BUILDER_IMAGE}
+          docker run --rm -t -u "$(id -u):$(id -g)" -v ${{ github.workspace }}:/build ${DOC_BUILDER_IMAGE} -vv
+
       - name: Save documentation artifacts
         uses: actions/upload-artifact@v3
         with:

diff --git a/doc/README.rst b/doc/README.rst
@@ -2,6 +2,9 @@
 Documentation Source
 ####################
 
+This folder contains source files for the documentation. The sources do not render well in GitHub or an RST viewer.
+In addition, some information is not visible at all and some links will not be functional.
+
 **********************
 Building Documentation
 **********************
@@ -10,13 +13,7 @@ Building Documentation
 Prerequisites
 =============
 
-Install `Docker <https://www.docker.com/>`_.
-
-Pull the docker container:
-
-.. code-block:: console
-
-    $ docker pull ghcr.io/xmos/doc_builder:v3.0.0
+Use the `xmosdoc tool <https://github.com/xmos/xmosdoc>`_ either via docker or install it into a pip environment.
 
 ========
 Building
@@ -26,5 +23,41 @@ To build the documentation, run the following command in the root of the reposit
 
 .. code-block:: console
 
-    $ docker run --rm -t -u "$(id -u):$(id -g)" -v $(pwd):/build -e PDF=1 -e REPO:/build -e DOXYGEN_INCLUDE=/build/doc/Doxyfile.inc -e EXCLUDE_PATTERNS=/build/doc/exclude_patterns.inc -e DOXYGEN_INPUT=ignore ghcr.io/xmos/doc_builder:v3.0.0
+    # via pip package
+    xmosdoc clean html latex
+    # via docker
+    $ docker run --rm -t -u "$(id -u):$(id -g)" -v $(pwd):/build ghcr.io/xmos/xmosdoc clean html latex
+
+HTML document output is saved in the ``doc/_build/html`` folder.  Open ``index.html`` to preview the saved documentation.
+
+Please refer to the ``xmosdoc`` documentation for a complete guide on how to use the tool.
+
+**********************
+Adding a New Component
+**********************
+
+Follow the following steps to add a new component.
+
+- Add an entry for the new component's top-level document to the appropriate TOC in the documents tree.
+- If the new component uses `Doxygen`, append the appropriate path(s) to the INPUT variable in `Doxyfile.inc`.
+- If the new component includes `.rst` files that should **not** be part of the documentation build, append the appropriate pattern(s) to `exclude_patterns.inc`.
+
+***
+FAQ
+***
+
+Q: Is it possible to build just a subset of the documentation?
+
+A: Yes, however it is not recommended at this time.
+
+Q: Is it possible to used the ``livehtml`` feature of Sphinx?
+
+A: Yes, run xmosdoc with the ``--auto`` option.
+
+Q: Where can I learn more about the XMOS ``xmosdoc`` tools?
+
+A: See the https://github.com/xmos/xmosdoc repository.  See the ``xmosdoc`` repository README for details on additional build options.
+
+Q: How do I suggest enhancements to the XMOS ``xmosdoc`` tool?
 
+A: Create a new issue here: https://github.com/xmos/xmosdoc/issues
diff --git a/doc/exclude_patterns.inc b/doc/exclude_patterns.inc
@@ -1,7 +1,9 @@
 # The following patterns are to be excluded from the documentation build
-doc/README.rst
+**CHANGELOG*
+**LICENSE*
+**README*
 examples
 test
 tools
 modules/mic_array
-modules/xud
+modules/xud
diff --git a/doc/programming_guide/reference/i2c/i2c.rst b/doc/programming_guide/reference/i2c/i2c.rst
@@ -1,4 +1,3 @@
-.. include:: ../../../substitutions.rst
 
 #############
 |I2C| Library

diff --git a/doc/programming_guide/reference/i2c/i2c_master.rst b/doc/programming_guide/reference/i2c/i2c_master.rst
@@ -1,4 +1,3 @@
-.. include:: ../../../substitutions.rst
 
 ************
 |I2C| Master

diff --git a/doc/programming_guide/reference/i2c/i2c_registers.rst b/doc/programming_guide/reference/i2c/i2c_registers.rst
@@ -1,4 +1,3 @@
-.. include:: ../../../substitutions.rst
 
 ***************
 |I2C| Registers

diff --git a/doc/programming_guide/reference/i2c/i2c_slave.rst b/doc/programming_guide/reference/i2c/i2c_slave.rst
@@ -1,4 +1,3 @@
-.. include:: ../../../substitutions.rst
 
 ***********
 |I2C| Slave

diff --git a/doc/programming_guide/reference/i2s/i2s.rst b/doc/programming_guide/reference/i2s/i2s.rst
@@ -1,4 +1,3 @@
-.. include:: ../../../substitutions.rst
 
 #############
 |I2S| Library

diff --git a/doc/programming_guide/reference/i2s/i2s_common.rst b/doc/programming_guide/reference/i2s/i2s_common.rst
@@ -1,4 +1,3 @@
-.. include:: ../../../substitutions.rst
 
 ****************
 |I2S| Common API

diff --git a/doc/programming_guide/reference/i2s/i2s_master.rst b/doc/programming_guide/reference/i2s/i2s_master.rst
@@ -1,4 +1,3 @@
-.. include:: ../../../substitutions.rst
 
 ************
 |I2S| Master

diff --git a/doc/programming_guide/reference/i2s/i2s_slave.rst b/doc/programming_guide/reference/i2s/i2s_slave.rst
@@ -1,4 +1,3 @@
-.. include:: ../../../substitutions.rst
 
 ***********
 |I2S| Slave

diff --git a/doc/programming_guide/reference/i2s/i2s_tdm_slave.rst b/doc/programming_guide/reference/i2s/i2s_tdm_slave.rst
@@ -1,4 +1,3 @@
-.. include:: ../../../substitutions.rst
 
 *********
 TDM Slave

diff --git a/doc/programming_guide/reference/spi/spi.rst b/doc/programming_guide/reference/spi/spi.rst
@@ -1,4 +1,3 @@
-.. include:: ../../../substitutions.rst
 
 ###########
 SPI Library

diff --git a/doc/programming_guide/reference/spi/spi_master.rst b/doc/programming_guide/reference/spi/spi_master.rst
@@ -1,4 +1,3 @@
-.. include:: ../../../substitutions.rst
 
 **********
 SPI Master

diff --git a/doc/programming_guide/reference/spi/spi_slave.rst b/doc/programming_guide/reference/spi/spi_slave.rst
@@ -1,4 +1,3 @@
-.. include:: ../../../substitutions.rst
 
 *********
 SPI Slave

diff --git a/doc/programming_guide/reference/uart/uart.rst b/doc/programming_guide/reference/uart/uart.rst
@@ -1,4 +1,3 @@
-.. include:: ../../../substitutions.rst
 
 ############
 UART Library

diff --git a/doc/programming_guide/reference/uart/uart_rx.rst b/doc/programming_guide/reference/uart/uart_rx.rst
@@ -1,4 +1,3 @@
-.. include:: ../../../substitutions.rst
 
 *******
 UART Rx

diff --git a/doc/programming_guide/reference/uart/uart_tx.rst b/doc/programming_guide/reference/uart/uart_tx.rst
@@ -1,4 +1,3 @@
-.. include:: ../../../substitutions.rst
 
 *******
 UART Tx

diff --git a/doc/shared/introduction.rst b/doc/shared/introduction.rst
@@ -1,4 +1,3 @@
-.. include:: ../substitutions.rst
 
 ########
 Overview 

diff --git a/doc/shared/legal.rst b/doc/shared/legal.rst
@@ -1,8 +1,6 @@
 .. _sln_voice_copyright:
 
 
-.. include:: ../_templates/disclaimer.rst
-
 Licenses
 ========
 

diff --git a/doc/src_html/.gitkeep b/doc/src_html/.gitkeep
diff --git a/doc/substitutions.rst b/doc/substitutions.rst
diff --git a/modules/mic_array b/modules/mic_array
diff --git a/settings.json b/settings.json
diff --git a/settings.yml b/settings.yml
@@ -0,0 +1,14 @@
+---
+project: fwk_io
+title: XCORE Peripheral IO Framework
+version: 3.3.0
+
+documentation:
+  exclude_patterns_path: doc/exclude_patterns.inc
+  doxygen_projects:
+    fwk_io:
+      doxyfile_path: doc/Doxyfile.inc
+  pdfs:
+    doc/programming_guide/index:
+      pdf_title: "{{title}} - Programming Guide"
+      pdf_filename: "{{project}}_programming_guide_v{{version}}"
-Original file line number
+Diff line change
@@ -1,4 +1,3 @@
-    .. include:: ../../../substitutions.rst
     *******
     UART Rx
@@ Expand Down @@
+0 −57		.github/workflows/docs.yml
+60 −31		Jenkinsfile
+33 −54		doc/README.rst
+3 −1		doc/exclude_patterns.inc
+1 −1		doc/programming_guide/src/decimator_stages.rst
+1 −1		doc/programming_guide/src/getting_started.rst
+0 −5		settings.json
+14 −0		settings.yml