search

canonical / sphinx-docs-starter-pack

A documentation starter-pack
https://canonical-starter-pack.readthedocs-hosted.com/
Other
16 stars 42 forks source link

`html_baseurl` and `READTHEDOCS` variables #259

Open ru-fu opened 4 months ago

ru-fu commented 4 months ago

See https://about.readthedocs.com/blog/2024/07/addons-by-default/

The html_baseurl and READTHEDOCS variables will be deprecated. We don't use them in the starter pack, so most likely, we are not affected. However, several of the packages we install use them (mainly Furo and OpenGraph), so we'll need to verify that these packages include the required changes. If they don't, we'll need to include the code from the blog post in the starter pack.

IronCore864 commented 1 month ago

It seems this change is necessary, otherwise the ad placement would be wrong:

If the left-side navigation bar is not very long, the ad should show up on the left; if the nav bar is very long, taking up the entire screen height, the ad should show up on the bottom right as a pop-up.

Take RTD's own doc site as an example, if you visit this page where the nav bar isn't too long, the ad shows up on the left, but if you access this one, since the nav bar takes up all the space, the ad shows up as a pop-up on the bottom right.

After Oct 7, in order for this to work as expected, the change mentioned in the blog is required, but adding the READTHEDOCS variable alone isn't sufficient, because the furo theme uses more variables if READTHEDOCS is set, for example here. So, everything defined here should also be set in the starter pack, and the docs for the starter pack also need to be updated to remind the users to adjust these values accordingly. See a PR fixing this issue in another repo using the starter pack here.