doc_builder -> xmosdoc

.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:

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