ref-manual, dev-manual: Applied feedback to edit several classes

Fixes [YOCTO #8298]

Updated several classes with feedback from Jose Lamego of Intel.
The feedback fixed some class groupings so that previously isolated
classes could be bundled under common classes (e.g.
autotools*.bbclass).

I scrubbed the cross-references for cases where a particular
class became "undocumented."  The cross-references now point to
the bundled class entry in the ref-manual.

(From yocto-docs rev: 07a533cb41ad26d202f4e303f2dbc7d7bf26e076)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

4 files changed, 59 insertions, 142 deletions

diff --git a/documentation/ref-manual/closer-look.xml b/documentation/ref-manual/closer-look.xml
index 27f674ae2f..45dcd9b3cf 100644
--- a/documentation/ref-manual/closer-look.xml
+++ b/documentation/ref-manual/closer-look.xml
@@ -1059,7 +1059,7 @@
                 the root filesystem image that lists out, line-by-line, the
                 installed packages.
                 This manifest file is useful for the
-                <link linkend='ref-classes-testimage'><filename>testimage</filename></link>
+                <link linkend='ref-classes-testimage*'><filename>testimage</filename></link>
                 class, for example, to determine whether or not to run
                 specific tests.
                 See the
diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml
index dc75eb827b..4d798bc283 100644
--- a/documentation/ref-manual/migration.xml
+++ b/documentation/ref-manual/migration.xml
@@ -980,7 +980,7 @@
         <para>
             A new automated image testing framework has been added
             through the
-            <link linkend='ref-classes-testimage'><filename>testimage*.bbclass</filename></link>
+            <link linkend='ref-classes-testimage*'><filename>testimage.bbclass</filename></link>
             class.
             This framework replaces the older
             <filename>imagetest-qemu</filename> framework.
@@ -1485,8 +1485,9 @@
             Recipes building Autotools-based
             software that fails to build with a separate build directory
             should be changed to inherit from the
-            <link linkend='ref-classes-autotools-brokensep'><filename>autotools-brokensep</filename></link>
-            class instead of the <filename>autotools</filename> class.
+            <link linkend='ref-classes-autotools'><filename>autotools-brokensep</filename></link>
+            class instead of the <filename>autotools</filename> or
+            <filename>autotools_stage</filename>classes.
         </para>
     </section>
 
@@ -1794,8 +1795,9 @@
                     need to either patch the software so that it can build
                     separately, or you will need to change the recipe to
                     inherit the
-                    <link linkend='ref-classes-autotools-brokensep'><filename>autotools-brokensep</filename></link>
-                    class instead of the <filename>autotools</filename> class.
+                    <link linkend='ref-classes-autotools'><filename>autotools-brokensep</filename></link>
+                    class instead of the <filename>autotools</filename> or
+                    <filename>autotools_stage</filename> classes.
                     </para></listitem>
                 <listitem><para><emphasis>
                     The <filename>--foreign</filename> option is
diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
index 647c67f2ba..1b7ab94801 100644
--- a/documentation/ref-manual/ref-classes.xml
+++ b/documentation/ref-manual/ref-classes.xml
@@ -101,116 +101,73 @@
 </section>
 
 <section id='ref-classes-autotools'>
-    <title><filename>autotools.bbclass</filename></title>
+    <title><filename>autotools*.bbclass</filename></title>
 
     <para>
-        The <filename>autotools</filename> class supports Autotooled
+        The <filename>autotools*</filename> classes support Autotooled
         packages.
     </para>
 
     <para>
         The <filename>autoconf</filename>, <filename>automake</filename>,
-        and <filename>libtool</filename> bring standardization.
+        and <filename>libtool</filename> packages bring standardization.
         This class defines a set of tasks (e.g.
         <filename>configure</filename>, <filename>compile</filename> and
         so forth) that
         work for all Autotooled packages.
         It should usually be enough to define a few standard variables
         and then simply <filename>inherit autotools</filename>.
-        This class can also work with software that emulates Autotools.
+        These classes can also work with software that emulates Autotools.
         For more information, see the
         "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-autotooled-package'>Autotooled Package</ulink>"
         section in the Yocto Project Development Manual.
     </para>
 
     <para>
-        By default, the <filename>autotools</filename> class
-        uses out-of-tree builds
+        By default, the <filename>autotools*</filename> classes
+        use out-of-tree builds (i.e.
+        <filename>autotools.bbclass</filename> and
+        <filename>autotools_stage.bbclass</filename>).
         (<link linkend='var-B'><filename>B</filename></link> <filename>!=</filename>
         <link linkend='var-S'><filename>S</filename></link>).
-        If the software being built by a recipe does not support
-        using out-of-tree builds, you should have the recipe inherit the
-        <link linkend='ref-classes-autotools-brokensep'><filename>autotools-brokensep</filename></link>
-        class.
-    </para>
-
-    <para>
-        It's useful to have some idea of how the tasks defined by this class
-        work and what they do behind the scenes.
-        <itemizedlist>
-            <listitem><para><link linkend='ref-tasks-configure'><filename>do_configure</filename></link> -
-                Regenerates the
-                configure script (using <filename>autoreconf</filename>) and then launches it
-                with a standard set of arguments used during cross-compilation.
-                You can pass additional parameters to <filename>configure</filename> through the
-                <filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename> variable.
-                </para></listitem>
-            <listitem><para><link linkend='ref-tasks-compile'><filename>do_compile</filename></link> - Runs <filename>make</filename> with
-                arguments that specify the compiler and linker.
-                You can pass additional arguments through
-                the <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename> variable.
-                </para></listitem>
-            <listitem><para><link linkend='ref-tasks-install'><filename>do_install</filename></link> - Runs <filename>make install</filename>
-                and passes in
-                <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>
-                as <filename>DESTDIR</filename>.
-                </para></listitem>
-        </itemizedlist>
-    </para>
-</section>
-
-<section id='ref-classes-autotools-stage'>
-    <title><filename>autotools_stage.bbclass</filename></title>
-
-    <para>
-        The <filename>autotools_stage</filename> class supports Autotooled
-        packages.
     </para>
 
     <para>
-        The <filename>autoconf</filename>,
-        <filename>automake</filename>, and <filename>libtool</filename>
-        bring standardization.
-        This class defines a set of tasks
-        (e.g. <filename>configure</filename>, <filename>compile</filename>
-        and so forth) that work for all Autotooled packages.
-        It is usually enough to define a few standard variables and then
-        simply inherit <filename>autotools</filename>.
-        This class can also work with software that emulates Autotools.
-        For more information, see the
-        "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-autotooled-package'>Autotooled Package</ulink>"
-        section in the Yocto Project Development Manual.
-    </para>
-
-    <para>
-        By default, the <filename>autotools-stage</filename> class uses
-        out-of-tree builds
-        (<link linkend='var-B'><filename>B</filename></link> <filename>!=</filename>
-        <link linkend='var-S'><filename>S</filename></link>).
         If the software being built by a recipe does not support
         using out-of-tree builds, you should have the recipe inherit the
-        <link linkend='ref-classes-autotools-brokensep'><filename>autotools-brokensep</filename></link>
-        class.
+        <filename>autotools-brokensep</filename> class.
+        The <filename>autotools-brokensep</filename> class behaves the same
+        as the <filename>autotools</filename> and
+        <filename>autotools_stage</filename> classes but builds with
+        <link linkend='var-B'><filename>B</filename></link> ==
+        <link linkend='var-S'><filename>S</filename></link>.
+        This method is useful when out-of-tree build support is either not
+        present or is broken.
+        <note>
+            It is recommended that out-of-tree support be fixed and used
+            if at all possible.
+        </note>
     </para>
 
     <para>
-        It is useful to have some idea of how the tasks defined by this
-        class work and what they do behind the scenes.
+        It's useful to have some idea of how the tasks defined by
+        the <filename>autotools*</filename> classes work and what they do
+        behind the scenes.
         <itemizedlist>
             <listitem><para><link linkend='ref-tasks-configure'><filename>do_configure</filename></link> -
-                Regenerates the configure script (using
-                <filename>autoreconf</filename>) and then launches it
-                with a standard set of arguments used during cross-compilation.
+                Regenerates the
+                configure script (using <filename>autoreconf</filename>) and
+                then launches it with a standard set of arguments used during
+                cross-compilation.
                 You can pass additional parameters to
                 <filename>configure</filename> through the
                 <filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename> variable.
                 </para></listitem>
             <listitem><para><link linkend='ref-tasks-compile'><filename>do_compile</filename></link> -
-                Runs <filename>make</filename> with arguments that specify
-                the compiler and linker.
-                You can pass additional arguments through the
-                <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename>
-                variable.
+                Runs <filename>make</filename> with arguments that specify the
+                compiler and linker.
+                You can pass additional arguments through
+                the <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename> variable.
                 </para></listitem>
             <listitem><para><link linkend='ref-tasks-install'><filename>do_install</filename></link> -
                 Runs <filename>make install</filename> and passes in
@@ -221,25 +178,6 @@
     </para>
 </section>
 
-<section id='ref-classes-autotools-brokensep'>
-    <title><filename>autotools-brokensep.bbclass</filename></title>
-
-    <para>
-        The <filename>autotools-brokensep</filename> class behaves the same
-        as the
-        <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
-        class but builds with
-        <link linkend='var-B'><filename>B</filename></link> ==
-        <link linkend='var-S'><filename>S</filename></link>.
-        This method is useful when out-of-tree build support is either not
-        present or is broken.
-        <note>
-            It is recommended that out-of-tree support be fixed and used
-            if at all possible.
-        </note>
-    </para>
-</section>
-
 <section id='ref-classes-base'>
     <title><filename>base.bbclass</filename></title>
 
@@ -791,10 +729,10 @@
 </section>
 
 <section id='ref-classes-distutils'>
-    <title><filename>distutils-*.bbclass</filename></title>
+    <title><filename>distutils*.bbclass</filename></title>
 
     <para>
-        The <filename>distutils-*</filename> classes support recipes for Python
+        The <filename>distutils*</filename> classes support recipes for Python
         version 2.x extensions, which are simple.
         These recipes usually only need to point to the source's archive and
         then inherit the proper class.
@@ -807,7 +745,7 @@
                 </para></listitem>
             <listitem><para>Extensions that use build systems based on
                 <filename>distutils</filename> require
-                the <filename>distutils-*</filename> classes in their recipes.
+                the <filename>distutils</filename> class in their recipes.
                 </para></listitem>
             <listitem><para>Extensions that use build systems based on
                 <filename>setuptools</filename> require the
@@ -816,8 +754,11 @@
                 </para></listitem>
         </itemizedlist>
         The <filename>distutils-common-base</filename> class is required by
-        some of the <filename>distutils-*</filename> classes to provide common
+        some of the <filename>distutils*</filename> classes to provide common
         Python2 support.
+    </para>
+
+    <para>
 	    The <filename>distutils-tools</filename> class supports recipes for
         additional "distutils" tools.
     </para>
@@ -827,7 +768,7 @@
     <title><filename>distutils3*.bbclass</filename></title>
 
     <para>
-        The <filename>distutils3</filename> class supports recipes for Python
+        The <filename>distutils3*</filename> classes support recipes for Python
         version 3.x extensions, which are simple.
         These recipes usually only need to point to the source's archive and
         then inherit the proper class.
@@ -3174,7 +3115,6 @@
     <title><filename>sign_rpm.bbclass</filename></title>
 
     <para>
-        The <filename>sign_rpm</filename> class
         The <filename>sign_rpm</filename> class supports generating signed
         RPM packages.
     </para>
@@ -3413,31 +3353,6 @@
     </para>
 </section>
 
-<section id='ref-classes-testimage'>
-    <title><filename>testimage.bbclass</filename></title>
-
-    <para>
-        The <filename>testimage</filename> class supports running automated
-        tests against images using QEMU and on actual hardware.
-        The class handles loading the tests and starting the image.
-    </para>
-
-    <para>
-        To use the class, you need to perform steps to set up the
-        environment.
-        The tests are commands that run on the target system over
-        <filename>ssh</filename>.
-        they are written in Python and make use of the
-        <filename>unittest</filename> module.
-    </para>
-
-    <para>
-        For information on how to enable, run, and create new tests, see the
-        "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
-        section.
-    </para>
-</section>
-
 <section id='ref-classes-testimage*'>
     <title><filename>testimage*.bbclass</filename></title>
 
@@ -3462,10 +3377,13 @@
         <literallayout class='monospaced'>
      $ bitbake -c testimage <replaceable>image</replaceable>
         </literallayout>
-        Tests run automatically on an image after the image is constructed
-        (i.e.
+        The <filename>testimage-auto</filename> class runs tests on an image
+        after the image is constructed (i.e.
         <link linkend='var-TEST_IMAGE'><filename>TEST_IMAGE</filename></link>
         must be set to "1").
+    </para>
+
+    <para>
         For information on how to enable, run, and create new tests, see the
         "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
         section in the Yocto Project Development Manual.
@@ -3657,14 +3575,14 @@
         The <filename>useradd*</filename> classes support the addition of users
         or groups for usage by the package on the target.
         For example, if you have packages that contain system services that
-        should be run under their own user or group, you can use this class to
-        enable creation of the user or group.
+        should be run under their own user or group, you can use these classes
+        to enable creation of the user or group.
         The <filename>meta-skeleton/recipes-skeleton/useradd/useradd-example.bb</filename>
         recipe in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
         provides a simple example that shows how to add three
         users and groups to two packages.
         See the <filename>useradd-example.bb</filename> recipe for more
-        information on how to use this class.
+        information on how to use these classes.
     </para>
 
     <para>
@@ -3681,10 +3599,6 @@
         <link linkend='var-GROUPMEMS_PARAM'><filename>GROUPMEMS_PARAM</filename></link>
         variables.
     </para>
-</section>
-
-<section id='ref-classes-useradd-staticids'>
-    <title><filename>useradd-staticids.bbclass</filename></title>
 
     <para>
         The <filename>useradd-staticids</filename> class supports the addition
@@ -3728,7 +3642,8 @@
     </para>
 
     <note><title>Notes</title>
-        You do not use this class directly.
+        You do not use the <filename>useradd-staticids</filename>
+        class directly.
         You either enable or disable the class by setting the
         <filename>USERADDEXTENSION</filename> variable.
         If you enable or disable the class in a configured system,
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 538936b43e..82410941c2 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -12935,7 +12935,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                     these tests, see the
                     "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
                     section in the Yocto Project Development Manual and the
-                    "<link linkend='ref-classes-testimage'><filename>testimage.bbclass</filename></link>"
+                    "<link linkend='ref-classes-testimage*'><filename>testimage*.bbclass</filename></link>"
                     section.
                 </para>
             </glossdef>
@@ -14314,7 +14314,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                         <filename>uid</filename> and <filename>gid</filename>
                         values causes the OpenEmbedded build system to employ
                         the
-                        <link linkend='ref-classes-useradd-staticids'><filename>useradd-staticids</filename></link>
+                        <link linkend='ref-classes-useradd'><filename>useradd-staticids</filename></link>
                         class.
                     </note>
                 </para>