Skip to content
This repository was archived by the owner on Apr 9, 2025. It is now read-only.

Clarify Read the Docs configs #59

Closed
humitos opened this issue Apr 15, 2020 · 2 comments · Fixed by #64
Closed

Clarify Read the Docs configs #59

humitos opened this issue Apr 15, 2020 · 2 comments · Fixed by #64
Labels
Needed: documentation Documentation is required

Comments

@humitos
Copy link
Member

humitos commented Apr 15, 2020

I just realized that these three configs (hoverxref_project, hoverxref_version and hoverxref_api_host) are confusing for users, and we should probably add a note that they should not be modified.

https://sphinx-hoverxref.readthedocs.io/en/latest/configuration.html#confval-hoverxref_api_host

People is modifying them because their CI starts failing saying they are not defined and they have fail on warnings enabled. So, defining them makes the CI happy but breaks all the tooltips on RTD.

It may be good to explain this case and suggest the users to define the environment variables READTHEDOCS_PROJECT and READTHEDOCS_VERSION in their CI to avoid it failing in case they are using -W.

Reference: scrapy/scrapy#4480 (comment)

@humitos humitos added the Needed: documentation Documentation is required label Apr 15, 2020
@humitos
Copy link
Member Author

humitos commented Apr 15, 2020

We are showing this warning message:

WARNING: hoverxref extension is not fully configured. Set hoverxref_project and hoverxref_version in your conf.py file.

That's probably wrong, and should explain more the situation.

@ericholscher
Copy link
Member

I'm 👍 on moving this to an INFO, as it will break CI builds if not.

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Needed: documentation Documentation is required
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants