diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index c155acd..d70f6cd 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/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/CHANGELOG.rst b/CHANGELOG.rst index 4cd75ab..7bb8b60 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -1,6 +1,12 @@ IO Framework change log ======================= +3.4.0 +----- + + * CHANGE: Documentation infrastructure updates + * CHANGE: Updated test_support to v2.0.0 + 3.3.0 ----- 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 diff --git a/doc/exclude_patterns.inc b/doc/exclude_patterns.inc index 8064566..e7fd5ca 100644 --- 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 \ No newline at end of file +modules/xud 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 2e62996..adcd1b7 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 60956aa..2e3a7d7 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 dce935e..6f76cf5 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 22448d1..ac79313 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 5c9dc5d..62c8182 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 657aaa5..87c673f 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/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 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 954c624..7ec028c 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 440a3b2..7ec6e09 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 2dd7980..101b84b 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 7f50edd..d6834e2 100644 --- 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 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/settings.json b/settings.json deleted file mode 100644 index 16dea7a..0000000 --- a/settings.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "title": "XCORE Peripheral IO Framework", - "project": "fwk_io", - "version": "3.3.0" -} \ No newline at end of file diff --git a/settings.yml b/settings.yml new file mode 100644 index 0000000..b826a24 --- /dev/null +++ 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}}"