sof-docs: build out of source directory #9878
Conversation
System tools for sphinx etc tend to be behind the versions available via pip. Prefer the pip version and automatically enable the Python virtual environment when starting the script. Signed-off-by: Liam Girdwood <[email protected]>
Move the intermediate doxygen build output out of the source directory. Signed-off-by: Liam Girdwood <[email protected]>
lgirdwood
requested review from
plbossart,
mmaka1,
lbetlej,
dbaluta and
kv2019i
as code owners
| # this needs to run from the Zephyr python virtual environment | ||
| # so that the python packages are available (and more up to date than | ||
| # the system packages). | ||
| source ~/zephyrproject/.venv/bin/activate |
There was a problem hiding this comment.
Firstly I don't think a requirement of zephyrproject being called that way and being in $HOME should be imposed. This isn't just for docker images or DUTs, this is for developers, using these manually on their development machines, right? Secondly, I also use venv, I'm not against it in general, but has it become an absolute requirement yet? Thirdly, the venv directory doesn't necessarily have to be called .venv, I've seen multiple examples just using venv and that's also what I use FWIW. Wouldn't it be better, if we do want to enforce the use of venv, to just check that it's enabled and error out otherwise? In general, I'd leave it to the user to activate and deactivate the venv.
There was a problem hiding this comment.
This really needs to be simple and align to the getting started documentation for both SOF and Zephyr. Going off track here just add complexity.
Firstly I don't think a requirement of
zephyrprojectbeing called that way and being in$HOMEshould be imposed.
Zephyr is locked in as a hard requirement now and the path aligns with the instructions that most developers will use.
This isn't just for docker images or DUTs, this is for developers, using these manually on their development machines, right?
This is for developers, github runners and docker. Its really simple now to get the right ingredients to build docs.
Secondly, I also use venv, I'm not against it in general, but has it become an absolute requirement yet? Thirdly, the venv directory doesn't necessarily have to be called
.venv, I've seen multiple examples just usingvenvand that's also what I use FWIW. Wouldn't it be better, if we do want to enforce the use of venv, to just check that it's enabled and error out otherwise? In general, I'd leave it to the user to activate and deactivate the venv.
Again this is following the default instructions. Yes a Python virtual environment is needed as pip is better managed for python support than apt-get based python packages. Leaving it to the user is just an extra step and then the system python packages could be used and fail (and hence developers may then waste time/effort debugging). This scripts are for convenience, developers can still manually invoke a venv and manually run make if they so desire.
There was a problem hiding this comment.
This will surprise (e.g. all my working trees on all my machines), but I can live with making the default setup easier. We do have a "choose-your-workspace" approach in our own SOF docs https://thesofproject.github.io/latest/getting_started/build-guide/build-with-zephyr.html
Build the sof docs outside of the source directory and within a Python virtual environment.