8584 2015-10-27 08:50:12 +0000 Enable building API documentation 2017-05-26 18:44:18 +0000 1 1 7 Build System, Metadata & Runtime OE-Core devtools / tool chain 2.0 All Multiple VERIFIED FIXED 21 Nov 2016: RESOLVED Medium+ enhancement 2.3 M1 1 ross.burton juan.fernandox.ramos.frayle alex.kanavin alexandru.c.georgescu bluelightning jose.perez.carranza juan.fernandox.ramos.frayle meta.mr.watcher meta.watcher song.liu srifenbark jose.perez.carranza --- --- Done (doc changes complete) oldest_to_newest 55799 0 ross.burton 2015-10-27 08:50:12 +0000 For people using a OE-generated SDK it would be useful to have a corresponding API documentation bundle for all of the packages in the SDK. This would mean enabling at least the following: - man page generation (troff, texinfo, etc) - doxygen - gtk-doc 55996 1 bluelightning 2015-10-29 13:48:19 +0000 I finally found the bug I thought already covered this - it's a bit short on details, but it's bug 1619. 56366 2 ross.burton 2015-11-10 17:19:41 +0000 *** Bug 1619 has been marked as a duplicate of this bug. *** 65585 3 alex.kanavin 2016-08-29 12:24:28 +0000 The gtk-doc patchset has been sent for review, but there's still significant amount of work to do (doxygen in particular requires lots of small tweaks to recipes), so the whole thing is postponed to 2.3. 66411 4 alex.kanavin 2016-09-21 10:19:39 +0000 I've finished the survey of doxygen support in upstream projects, and here are the findings: 1) doxygen api documentation generation is supported in some way by 67 recipes 2) of those, only 9 support doxygen in a way that is distribution-friendly, specifically: - there is a configure switch to enable/disable usage of doxygen - generation of html documentation happens with make's default target, and installation happens with 'make install' Those recipes are dbus, flac, libexif, libfakekey, libvorbis, libxcb, libxcbcommon, mc, source-highlight. 3) The rest of the recipes do things in various different ways: - the most common way is that there is a separate make target to build doxygen (make apidocs, make doxygen, make docs, make html and so on - everyone names it differently), and no configure switches or installation targets. - another common approach is to ship only doxyfile (the config file for doxygen) and provide no makefile support at all. 4) The conclusion I have is that upstreams, by and large, don't see doxygen documentation as something that distributions should package or worry about. To upstream projects, doxygen support is their own internal thing, that they use to put the html output on their websites. I'd say we should not struggle against this by doing a ton of recipe fixing and tweaking - there are more beneficial things to do. 66545 5 alex.kanavin 2016-09-23 13:18:15 +0000 Okay, now onto manpages. A large amount of upstream projects ship and install ready-to-use manpages, for them nothing needs to be done. Then there projects where manpages can be conditionally built. A few of those can be found by looking for "--enable/disable-manpages" in recipe directory, but there might be others lurking - so I'll look for "enable-man" and its variants in the build tree as well. I first wanted to be more generic and look for variants of "manpage" in the source tree, but quickly realized that it's a road to insanity, caused by monotonous, astronomical amount of false positives. Then building of manpages will be conditionally enabled if 'api-documentation' is in distro features, as it tends to pull in the whole xml stack and other specialized tools. 66749 6 alex.kanavin 2016-09-30 11:14:34 +0000 The patchset for manpages is now available here (will submit for review after 2 weeks of holiday): https://git.yoctoproject.org/cgit/cgit.cgi/poky-contrib/log/?h=akanavin/enable-documentation I've also added patches that remove the aging, difficult to maintain SGML stack to the same branch. Amazingly, nothing seems to need it in meta-oe, so it doesn't have to be moved there (unless someone using a 3rd party layer complains). 67325 7 alex.kanavin 2016-10-18 12:01:27 +0000 Patches sent for review: http://lists.openembedded.org/pipermail/openembedded-core/2016-October/127647.html 67525 8 alex.kanavin 2016-10-25 12:00:24 +0000 Paul, I'm now ready to enable adding the generated documentation into SDKs. Can you point me to the files where SDKs generation and configuration happens, so I don't need to look for it with grep etc.? :) 67551 9 bluelightning 2016-10-25 19:43:06 +0000 I'm not sure much needs to be done - for bitbake -c populate_sdk <image> you will get documentation packages in the SDK right now if you add doc-pkgs to SDKIMAGE_FEATURES. 67588 10 alex.kanavin 2016-10-26 09:53:18 +0000 (In reply to comment #9) > I'm not sure much needs to be done - for bitbake -c populate_sdk <image> you > will get documentation packages in the SDK right now if you add doc-pkgs to > SDKIMAGE_FEATURES. Actually, also 'api-documentation' must be in DISTRO_FEATURES so that additional manpages and gtk-doc based documentation is produced, so where should I place that? It's not enabled by default as it adds significantly to the build time for common images (core-image-sato etc.). 67607 11 bluelightning 2016-10-26 19:27:53 +0000 I'm not sure I fully understand the question. These are two different things: * 'api-documentation' in DISTRO_FEATURES enables building the documentation * 'doc-pkgs' in IMAGE_FEATURES / SDKIMAGE_FEATURES enables installing all related documentation (API or otherwise) into the image / SDK respectively. You might perhaps trigger doc-pkgs from api-documentation I suppose, but it's possible that's not always going to be what the user wants. 67628 12 alex.kanavin 2016-10-27 08:29:10 +0000 (In reply to comment #11) > I'm not sure I fully understand the question. These are two different things: > > * 'api-documentation' in DISTRO_FEATURES enables building the documentation > * 'doc-pkgs' in IMAGE_FEATURES / SDKIMAGE_FEATURES enables installing all > related documentation (API or otherwise) into the image / SDK respectively. The question is, for every SDK that gets generated, how do we ensure that 'api-documentation' was enabled in DISTRO_FEATURES? 67631 13 bluelightning 2016-10-27 11:37:52 +0000 The process that constructs an SDK cannot control DISTRO_FEATURES, so I can't see how that would be possible. 67633 14 alex.kanavin 2016-10-27 12:28:40 +0000 (In reply to comment #13) > The process that constructs an SDK cannot control DISTRO_FEATURES, so I > can't see how that would be possible. The SDK building could refuse to continue if DISTRO_FEATURES doesn't have the needed entry? 67657 15 bluelightning 2016-10-27 18:34:13 +0000 I really don't think that's appropriate. There will be quite a number of people out there who don't care to have the documentation included in their SDK. 67659 16 alex.kanavin 2016-10-27 19:07:25 +0000 (In reply to comment #15) > I really don't think that's appropriate. There will be quite a number of > people out there who don't care to have the documentation included in their > SDK. In that case I think the work is basically complete here (when the patchset for manpages gets merged). I'll file a separate bug for changing the site configuration so that when Yocto SDKs are generated, the api-documentation distro feature is in use. Ross, any comment? 67825 17 ross.burton 2016-11-01 16:59:51 +0000 There's outstanding issues with adding doc-pkgs to SDK images (as they get giant) but Alex is aware of that. I think we should also add doc-pkgs to SDKIMAGE_FEATURES (maybe if api-documentation is enabled in DISTRO_FEATURES) so that generated SDKs (not SDK images) also get the documentation (I think that docs in standalone SDKs is more important than in SDK images) but apart from that we're done. 68090 18 alex.kanavin 2016-11-08 15:07:09 +0000 'api-documentation' DISTRO_FEATURE needs to be documented. Something like: When this feature is in use, generation of API documentation during recipe builds is enabled, and the resulting documentation will be added to SDK tarballs produced by 'bitbake -c populate_sdk'. 68105 19 srifenbark 2016-11-08 17:15:09 +0000 Regarding documenting api-documentation, here is a section in the ref-manual that lists the DISTRO_FEATURES available in YP: http://www.yoctoproject.org/docs/2.2/ref-manual/ref-manual.html#ref-features-distro. Would adding an entry for api-documentation cover this issue? Note that the glossary entry for DISTRO_FEATURES does not provide an exhaustive list but rather highlights some stuff - http://www.yoctoproject.org/docs/2.2/ref-manual/ref-manual.html#var-DISTRO_FEATURES. In the SDK manual we have a chapter here (http://www.yoctoproject.org/docs/2.2/sdk-manual/sdk-manual.html#sdk-appendix-customizing) that talks about customizing an SDK. Should we create a subsection on how to add API documentation? Setting this to ACCEPTED since I own it now. Scott 68182 20 alex.kanavin 2016-11-09 13:24:16 +0000 (In reply to comment #19) > Regarding documenting api-documentation, here is a section in the ref-manual > that lists the DISTRO_FEATURES available in YP: > http://www.yoctoproject.org/docs/2.2/ref-manual/ref-manual.html#ref-features- > distro. Would adding an entry for api-documentation cover this issue? Yes. > In the SDK manual we have a chapter here > (http://www.yoctoproject.org/docs/2.2/sdk-manual/sdk-manual.html#sdk- > appendix-customizing) that talks about customizing an SDK. Should we create > a subsection on how to add API documentation? Yes please. 68258 21 srifenbark 2016-11-11 17:44:25 +0000 Hi, This api-documentation fix... Did it make it into Morty? I am guessing that it did not. Correct? Thanks, Scott 68330 22 srifenbark 2016-11-15 18:19:59 +0000 Hi, The fix is in for this now. There were several areas that were touched. Here they are: * http://www.yoctoproject.org/docs/2.3/sdk-manual/sdk-manual.html#sdk-appendix-customizing-standard - this is a new appendix in the SDK manual for customizing the standard SDK. This is where we talk about adding API documentation to the SDK. I had to put in another subsection in this appendix to justify creating a whole new appendix. That other section was on how to add individual packages to the SDK. * http://www.yoctoproject.org/docs/2.3/ref-manual/ref-manual.html#var-TOOLCHAIN_HOST_TASK - I added a cross-reference from this variable description to the new section on adding packages to a standard SDK. * http://www.yoctoproject.org/docs/2.3/ref-manual/ref-manual.html#var-TOOLCHAIN_TARGET_TASK - same thing here. Cross-reference to new section. * http://www.yoctoproject.org/docs/2.3/ref-manual/ref-manual.html#ref-features-distro - Added the api-documentation feature to this list. Let me know of any changes or modifications. Thanks, Scott 68366 23 alex.kanavin 2016-11-16 15:15:00 +0000 (In reply to comment #21) > This api-documentation fix... Did it make it into Morty? I am guessing that > it did not. Correct? No, it didn't. Only gtk-doc support made it to morty, not all the other stuff, so morty documentation doesn't need to be touched. 68367 24 alex.kanavin 2016-11-16 15:23:57 +0000 > http://www.yoctoproject.org/docs/2.3/sdk-manual/sdk-manual.html#sdk-appendix- > customizing-standard - this is a new appendix in the SDK manual for > customizing the standard SDK. This is where we talk about adding API > documentation to the SDK. I had to put in another subsection in this > appendix to justify creating a whole new appendix. That other section was > on how to add individual packages to the SDK. This says: " You might want to include documentation as part of the standard SDK. For example, you might want the API documentation to be built and included with the SDK. You can include API documentation as well as any other documentation with the standard SDK by setting the SDKIMAGE_FEATURES and DISTRO_FEATURES variables: SDKIMAGE_FEATURES = "doc-pkgs" DISTRO_FEATURES = "api-documentation" Setting these variables as shown here causes the OpenEmbedded build system to build the documentation and then include it in the standard SDK." You can drop the first two sentences, they're just repeating the same thing. And also changing SDKIMAGE_FEATURES is not needed, just adding to DISTRO_FEATURES is enough. Here's how it should be fixed: "You can include API documentation as well as any other documentation provided by recipes with the standard SDK by adding 'api-documentation' to the DISTRO_FEATURE variable: DISTRO_FEATURES_append = " api-documentation" Setting this variable as shown here causes the OpenEmbedded build system to build the documentation and then include it in the standard SDK." > Let me know of any changes or modifications. Looks ok otherwise. 68445 25 srifenbark 2016-11-18 21:12:56 +0000 Hi, See http://www.yoctoproject.org/docs/2.3/sdk-manual/sdk-manual.html#adding-api-documentation-to-the-standard-sdk for the changes. Scott 68454 26 alex.kanavin 2016-11-21 12:50:51 +0000 Seems fine to me now. 68474 27 srifenbark 2016-11-22 00:20:13 +0000 Thanks, I am setting to RESOLVED and marking the doc flag to "done". Scott 73533 28 juan.fernandox.ramos.frayle 2017-05-26 18:44:18 +0000 Changing to verified since the documentation is here: http://www.yoctoproject.org/docs/2.3/sdk-manual/sdk-manual.html#adding-api-documentation-to-the-standard-sdk