[Ovmsdev] How I got sphinx working on ubuntu 23.1 + WSL

[Michael Geddes]

Firstly, thanks to Michael Balzer for fixing my errors in the rst files I
checked in. (Also, apparently I can't spell Auxiliary - doh).  I _had_
tried to get sphinx working recently and failed miserably, so I tried again
this morning.

The problem is that ubuntu:
* Doesn't provide a package for m2r2 or sphinx-mdinclude (a fork of m2r2)
* No longer allows you to pip install into the main python library path

So first I got rid of the installed sphinx-doc
sudo apt remove sphinx-doc

Then I set up a sphinx virtual environment

pipx install sphinx
pipx inject sphinx sphinx_rtd_theme docutils mistune requests
sphinx-mdinclude

For some reason I was getting run-time python errors with m2r2 which is why
I tried switching to mdinclude.

In docs/source/conf.py I changed
 extensions = [ 'm2r2' ]
to be  'sphinx_mdinclude' instead of 'm2r2'

The pipx command creates a virtual execution environment for sphinx and
puts a shim for sphinx in your local path that runs it in the virtual
environment.

//.ichael
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openvehicles.com/pipermail/ovmsdev/attachments/20241117/71965e0d/attachment.htm>