[BUG] Problems building the documentation

[jeremybennett]

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

• [X] 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))

[MikeOpenHWGroup]

Thanks for the report @jeremybennett. As you suspect, I have made many and substantive changes to the user manual. Those auto-doc warnings have been there for some time and do not affect the generation of the static html pages. Use of the auto-generated CSR and pin-tables for the user manual has been depreciated and I will be removing the generation of the auto-docs directory from the Makefile soon.

The generation of the PDF is broken - those odd structures you see are ReStructured Text comment headers. It seems that the PDF generator does not understand (or have not been properly configured for) rst files.

I will generate a pull-request to resolve these issues later today.

[jeremybennett]

Thanks @MikeOpenHWGroup

[MikeOpenHWGroup]

Pull-request #283 created. Please give it a go @jeremybennett. Thanks!