[BUG] Problems building the documentation

Created by: jeremybennett

Is there an existing core-v-mcu bug for this?

• I have searched the existing bug issues

Bug Description

I ran into some issues when building the documentation. I have put them all in one issue, since they are probably all related.

missing MD files

Whether building for HTML or PDF (using make in the docs directory), the makefile tries to merge markdown files, which fails:

make[1]: Leaving directory '/home/jeremy/gittrees/openhw/core-v-mcu/docs'
rm -f doc-src/all.md
for f in `egrep doc-src\|auto-docs index.rst`; do cat "$f" >> doc-src/all.md; echo "\n\n" >> doc-src/all.md;done
cat: doc-src/overview.md: No such file or directory
cat: doc-src/terminology.md: No such file or directory
cat: doc-src/device_characteristics.md: No such file or directory
cat: doc-src/package_information.md: No such file or directory
cat: doc-src/startup.md: No such file or directory
cat: doc-src/interrupts.md: No such file or directory
cat: doc-src/clock_domains.md: No such file or directory
cat: doc-src/debug_approach.md: No such file or directory
cat: doc-src/evaluation_kits.md: No such file or directory
cat: doc-src/software_support.md: No such file or directory
cat: doc-src/efpga_subsystem.md: No such file or directory
(cd doc-src; pandoc -t latex -o ../index.pdf all.md)

Building PDF

Using make pdf, we create all.pdf, but it appears to have weird insertion at the top and then from time to time:

.. Copyright (c) 2023 OpenHW Group
SPDX-License-Identifier: Apache-2.0 WITH SHL-2.1
.. Level 1 =======
Level 2 ——-
Level 3 ~~~~~~~
Level 4 ˆˆˆˆˆˆˆ
.. _open_source_development_at_openhw:

HTML generation

There seems to be a problem with consistency checking, which may be to do with the migration from MD:

checking consistency... /home/jeremy/gittrees/openhw/core-v-mcu/docs/auto-docs/apb_event_cntrl_reg_defs.md: WARNING: document isn't included in any toctree
/home/jeremy/gittrees/openhw/core-v-mcu/docs/auto-docs/apb_gpio_reg_defs.md: WARNING: document isn't included in any toctree
/home/jeremy/gittrees/openhw/core-v-mcu/docs/auto-docs/apb_i2cs_reg_defs.md: WARNING: document isn't included in any toctree
/home/jeremy/gittrees/openhw/core-v-mcu/docs/auto-docs/apb_soc_ctrl_reg_defs.md: WARNING: document isn't included in any toctree
/home/jeremy/gittrees/openhw/core-v-mcu/docs/auto-docs/apb_timer_unit_reg_defs.md: WARNING: document isn't included in any toctree
/home/jeremy/gittrees/openhw/core-v-mcu/docs/auto-docs/efpga_template_reg_defs.md: WARNING: document isn't included in any toctree
/home/jeremy/gittrees/openhw/core-v-mcu/docs/auto-docs/pin-table.md: WARNING: document isn't included in any toctree
/home/jeremy/gittrees/openhw/core-v-mcu/docs/auto-docs/udma_camera_reg_defs.md: WARNING: document isn't included in any toctree
/home/jeremy/gittrees/openhw/core-v-mcu/docs/auto-docs/udma_ctrl_reg_defs.md: WARNING: document isn't included in any toctree
/home/jeremy/gittrees/openhw/core-v-mcu/docs/auto-docs/udma_i2cm_reg_defs.md: WARNING: document isn't included in any toctree
/home/jeremy/gittrees/openhw/core-v-mcu/docs/auto-docs/udma_qspi_reg_defs.md: WARNING: document isn't included in any toctree
/home/jeremy/gittrees/openhw/core-v-mcu/docs/auto-docs/udma_sdio_reg_defs.md: WARNING: document isn't included in any toctree
/home/jeremy/gittrees/openhw/core-v-mcu/docs/auto-docs/udma_uart_reg_defs.md: WARNING: document isn't included in any toctree
done
preparing documents... done

I also got a warning from recommonmark:

updating environment: [new config] 46 added, 0 changed, 0 removed
/home/jeremy/.local/lib/python3.8/site-packages/recommonmark/parser.py:75: UserWarning: Container node skipped: type=document
  warn("Container node skipped: type={0}".format(mdnode.t))