MUSE_OS icon indicating copy to clipboard operation
MUSE_OS copied to clipboard

Sphinx builds documentation but throws 126 warnings and not all HTML documents are rendered without artefacts

Open HarmonicReflux opened this issue 1 year ago • 0 comments

Describe the bug

Building the documentation using Sphinx results in a "build succeeded", but I receive 126 warnings.

Also, there is a problem with artefacts in the rendered HTML files. For example, after the build succeeded, taking a look at the built docs/build/application-flow.html in Chrome browser, results in the screenshot displayed further below.

To Reproduce

  1. Activate the virtual environment MUSE_OS is installed.
  2. If necessary invoke sudo apt install pandoc
  3. As per documentation 3.4.4. Building the documentation invoke python -m sphinx -b html docs docs/build

You should then see a screenshot similar to the ones posted below.

Expected behaviour

Building the documentation should run without warnings and rendering of the HTML documents should be without artefacts.

Screenshots

  1. python -m sphinx -b html docs docs/build throws 126 warnings: Screenshot from 2024-06-19 16-20-50

  2. HTML document not rendered correctly: Screenshot from 2024-06-19 16-29-23 Screenshot from 2024-06-19 16-29-39

Context

Please, complete the following to better understand the system you are using to run MUSE.

  • Operating system (eg. Ubuntu 22):
  • MUSE version: Recent development branch as of the time of writing. muse.version throws an error, so cannot specify the exact version as per the standard method.
  • Installation method: Development mode.
  • Python version (you can get this running python --version): 3.9.19

HarmonicReflux avatar Jun 19 '24 15:06 HarmonicReflux