Bug 14502

Summary:	Check documentation of variables that appear in both bitbake and yocto docs
Product:	[Documentation] Variables Glossary	Reporter:	Quentin Schulz <foss+yocto>
Component:	variables-glossary	Assignee:	Michael Opdenacker <michael.opdenacker>
Status:	RESOLVED FIXED	QA Contact:
Severity:	normal
Priority:	Medium	CC:	randy.macleod
Version:	unspecified
Target Milestone:	4.2 M1
Hardware:	x86
OS:	Multiple
Whiteboard:
OS type for building Yocto:	---	Type of Regression:	---
Verified:		Documentation change:	Yes (doc changes required)

Description Quentin Schulz 2021-08-06 08:37:02 UTC

I've discovered that BBPATH in yocto-docs is missing an important piece of information: it applies to configuration files too, not only bbclass. This was correctly documented in bitbake documentation but is overridden in yocto-docs.

At least this variable don needs to be fixed but we should check all "duplicates" to see if the overridden documentation makes sense in yocto-docs and that bitbake docs have as at least as much info as yocto-docs'.

For BBPATH, I think we might be able to just remove it from yocto-docs.

On a side note, wondering if we couldn't integrate links in yocto-docs to terms defined in bitbake documentation. I've always found the experience not very user-friendly wrt where variables are documented. E.g. some variables are only documented in bitbake docs, so if I look for it in the variables glossary, I won't find it. Maybe there's something we can do here. But that outside of this bug scope :)

Comment 1 Michael Opdenacker 2022-09-22 08:18:27 UTC

Proposed a fix for BBPATH:
https://lists.yoctoproject.org/g/docs/message/3202

I'm keeping a note about checking other variables, but this would be a too broad scope for this bug, which would remain open forever otherwise.

Same for the last item, for the moment, we can't automatically add the BitBake terms to the variable index in the Yocto Project manual. I'll keep this in my notes.

Comment 2 Michael Opdenacker 2022-09-22 08:22:40 UTC

Comment from Quentin Schulz:

What I just thought of right now is to add another custom extension which would traverse the intersphinx mapping for bitbake terms and insert them in the glossary the way you're doing it above, but just automated.

I have no idea if that is feasible, but I feel like it'd be a better solution than trying to maintain this kind of redirection.

Comment 3 Michael Opdenacker 2022-10-03 13:25:25 UTC

Now fixed in master:
https://git.yoctoproject.org/yocto-docs/commit/?id=5feb4e174e0aec6a48b1131889a5b8547b9b9921