From aafc47cf614e8e3608578ac31d43731f1d419c98 Mon Sep 17 00:00:00 2001 From: Brennan Magee Date: Tue, 19 Sep 2023 16:08:03 +0100 Subject: [PATCH 1/8] Remove manual rst substitutions --- doc/programming_guide/reference/i2c/i2c.rst | 1 - doc/programming_guide/reference/i2c/i2c_master.rst | 1 - doc/programming_guide/reference/i2c/i2c_registers.rst | 1 - doc/programming_guide/reference/i2c/i2c_slave.rst | 1 - doc/programming_guide/reference/i2s/i2s.rst | 1 - doc/programming_guide/reference/i2s/i2s_common.rst | 1 - doc/programming_guide/reference/i2s/i2s_master.rst | 1 - doc/programming_guide/reference/i2s/i2s_slave.rst | 1 - doc/programming_guide/reference/spi/spi.rst | 1 - doc/programming_guide/reference/spi/spi_master.rst | 1 - doc/programming_guide/reference/spi/spi_slave.rst | 1 - doc/programming_guide/reference/uart/uart.rst | 1 - doc/programming_guide/reference/uart/uart_rx.rst | 1 - doc/programming_guide/reference/uart/uart_tx.rst | 1 - doc/shared/introduction.rst | 1 - 15 files changed, 15 deletions(-) diff --git a/doc/programming_guide/reference/i2c/i2c.rst b/doc/programming_guide/reference/i2c/i2c.rst index 97136a4..3027ac5 100644 --- 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 index 9cf8266..10b949d 100644 --- 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 index d21cce9..4c7a1cb 100644 --- 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 index 848ceba..8b04949 100644 --- 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 index c942e78..252eacd 100644 --- 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 index 87dcf39..cbba580 100644 --- 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 index 0b6500a..ebfc5aa 100644 --- 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 index 150810f..036fd00 100644 --- 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/spi/spi.rst b/doc/programming_guide/reference/spi/spi.rst index ba85cfe..538c7a7 100644 --- 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 index 22be5d5..2d6f332 100644 --- 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 index f3b9f20..24c8b92 100644 --- 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 index 4a8162d..4e600f4 100644 --- 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 index b4cb9a2..d06986e 100644 --- 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 index f28a098..9cf6907 100644 --- 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 index 35bb5d1..6c38be2 100644 --- a/doc/shared/introduction.rst +++ b/doc/shared/introduction.rst @@ -1,4 +1,3 @@ -.. include:: ../substitutions.rst ######## Overview From a14bfbd10e884c82e31eb0c1d84d1eedae34dba5 Mon Sep 17 00:00:00 2001 From: Brennan Magee Date: Fri, 22 Sep 2023 16:14:28 +0100 Subject: [PATCH 2/8] fixes for xmosdoc v4 also will need update to mic_array --- doc/exclude_patterns.inc | 4 +++- doc/shared/legal.rst | 2 -- doc/src_html/.gitkeep | 1 - doc/substitutions.rst | 2 -- modules/uart/api/uart.h | 2 +- settings.json | 5 ----- settings.yml | 14 ++++++++++++++ 7 files changed, 18 insertions(+), 12 deletions(-) delete mode 100644 doc/src_html/.gitkeep delete mode 100644 doc/substitutions.rst delete mode 100644 settings.json create mode 100644 settings.yml diff --git a/doc/exclude_patterns.inc b/doc/exclude_patterns.inc index 8064566..84d6680 100644 --- a/doc/exclude_patterns.inc +++ b/doc/exclude_patterns.inc @@ -1,5 +1,7 @@ # The following patterns are to be excluded from the documentation build -doc/README.rst +CHANGELOG.rst +LICENSE.rst +**README* examples test tools diff --git a/doc/shared/legal.rst b/doc/shared/legal.rst index 785d9fa..6a3183b 100644 --- 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 deleted file mode 100644 index 5f5ae08..0000000 --- a/doc/src_html/.gitkeep +++ /dev/null @@ -1 +0,0 @@ -# This directory needs to exist for the doc builder diff --git a/doc/substitutions.rst b/doc/substitutions.rst deleted file mode 100644 index a06ed94..0000000 --- a/doc/substitutions.rst +++ /dev/null @@ -1,2 +0,0 @@ -.. |I2C| replace:: I\ :sup:`2`\ C -.. |I2S| replace:: I\ :sup:`2`\ S diff --git a/modules/uart/api/uart.h b/modules/uart/api/uart.h index d800f5d..bf185cf 100644 --- a/modules/uart/api/uart.h +++ b/modules/uart/api/uart.h @@ -26,7 +26,7 @@ * Enum type representing the different options * parity types. */ -typedef enum uart_parity_t { +typedef enum { UART_PARITY_NONE = 0, UART_PARITY_EVEN, UART_PARITY_ODD diff --git a/settings.json b/settings.json deleted file mode 100644 index f45574d..0000000 --- a/settings.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "title": "XCORE Peripheral IO Framework", - "project": "fwk_io", - "version": "3.1.0" -} \ No newline at end of file diff --git a/settings.yml b/settings.yml new file mode 100644 index 0000000..79a6899 --- /dev/null +++ b/settings.yml @@ -0,0 +1,14 @@ +--- +project: fwk_io +title: XCORE Peripheral IO Framework +version: 3.1.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}}" From a1f759690252a2c1f61b34e072fcc088b69009fc Mon Sep 17 00:00:00 2001 From: Brennan Magee Date: Fri, 22 Sep 2023 16:58:58 +0100 Subject: [PATCH 3/8] update github actions workflow to use new xmosdoc --- .github/workflows/docs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 6f7f61e..2b9781a 100644 --- 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/doc_builder:pr-67' jobs: build_documentation: @@ -43,4 +43,4 @@ 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 From 4c62ece96bfe92006d964bba494ac96979736955 Mon Sep 17 00:00:00 2001 From: Brennan Magee Date: Fri, 22 Sep 2023 17:05:01 +0100 Subject: [PATCH 4/8] upload docs in github actions --- .github/workflows/docs.yml | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 2b9781a..caa4ddb 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -44,3 +44,19 @@ jobs: - name: Build documentation run: | docker run --rm -t -u "$(id -u):$(id -g)" -v ${{ github.workspace }}:/build ${DOC_BUILDER_IMAGE} -vv + + - name: Save HTML documentation artifact + uses: actions/upload-artifact@v2 + with: + name: fwk_io_docs_html + path: ./doc/_build/html + if-no-files-found: error # 'warn' or 'ignore' are also available, defaults to `warn` + retention-days: 5 + + - name: Save PDF documentation artifact + uses: actions/upload-artifact@v2 + with: + name: fwk_io_docs_pdf + path: ./doc/_build/latex + if-no-files-found: error # 'warn' or 'ignore' are also available, defaults to `warn` + retention-days: 5 \ No newline at end of file From 49d8a2db213070be1226bb4790d934adb94b1cf2 Mon Sep 17 00:00:00 2001 From: Brennan Magee Date: Tue, 3 Oct 2023 17:11:34 +0100 Subject: [PATCH 5/8] doc_builder -> xmosdoc --- .github/workflows/docs.yml | 2 +- doc/README.rst | 49 +++++++++++++++++++++++++++++++------- 2 files changed, 42 insertions(+), 9 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index caa4ddb..76f3342 100644 --- 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:pr-67' + DOC_BUILDER_IMAGE: 'ghcr.io/xmos/xmosdoc:pr-67' jobs: build_documentation: diff --git a/doc/README.rst b/doc/README.rst index e005816..8c9fe66 100644 --- 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 `_. - -Pull the docker container: - -.. code-block:: console - - $ docker pull ghcr.io/xmos/doc_builder:v3.0.0 +Use the `xmosdoc tool `_ 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 From dae11baa098da5cf45a759040f71f9148aec0137 Mon Sep 17 00:00:00 2001 From: Brennan Magee Date: Tue, 10 Oct 2023 15:55:50 +0100 Subject: [PATCH 6/8] set xmosdoc version to v4 --- .github/workflows/docs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 76f3342..3acb314 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -25,7 +25,7 @@ on: workflow_dispatch: {} env: - DOC_BUILDER_IMAGE: 'ghcr.io/xmos/xmosdoc:pr-67' + DOC_BUILDER_IMAGE: 'ghcr.io/xmos/xmosdoc:v4.0' jobs: build_documentation: @@ -59,4 +59,4 @@ jobs: name: fwk_io_docs_pdf path: ./doc/_build/latex if-no-files-found: error # 'warn' or 'ignore' are also available, defaults to `warn` - retention-days: 5 \ No newline at end of file + retention-days: 5 From 1179bc34c721f00077cb086ad1f0ad39ca581951 Mon Sep 17 00:00:00 2001 From: Brennan Magee Date: Fri, 20 Oct 2023 10:39:36 +0100 Subject: [PATCH 7/8] update mic_array submodule --- modules/mic_array | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/mic_array b/modules/mic_array index 28cc9b1..5e74ad5 160000 --- a/modules/mic_array +++ b/modules/mic_array @@ -1 +1 @@ -Subproject commit 28cc9b13ea73c9301ee6c786cb64218d773bc43e +Subproject commit 5e74ad58c1c32832711f871e9f6312a415bf64a2 From dd68ccd7bcef55de290a8d4318f8f3f806974e37 Mon Sep 17 00:00:00 2001 From: Brennan Magee Date: Fri, 20 Oct 2023 10:53:35 +0100 Subject: [PATCH 8/8] clearing up a couple of sphinx warnings --- doc/exclude_patterns.inc | 6 +++--- doc/programming_guide/reference/i2s/i2s_tdm_slave.rst | 1 - 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/doc/exclude_patterns.inc b/doc/exclude_patterns.inc index 84d6680..e7fd5ca 100644 --- a/doc/exclude_patterns.inc +++ b/doc/exclude_patterns.inc @@ -1,9 +1,9 @@ # The following patterns are to be excluded from the documentation build -CHANGELOG.rst -LICENSE.rst +**CHANGELOG* +**LICENSE* **README* examples test tools modules/mic_array -modules/xud \ No newline at end of file +modules/xud diff --git a/doc/programming_guide/reference/i2s/i2s_tdm_slave.rst b/doc/programming_guide/reference/i2s/i2s_tdm_slave.rst index eba15f6..af92646 100644 --- 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