[sphinx][PATCH] overview-manual: Clean up warnings for sphinx

[sphinx][PATCH] overview-manual: Clean up warnings for sphinx

[akuster]

Signed-off-by: Armin Kuster <akuster808@gmail.com>
---
 .../overview-manual/overview-manual-concepts.rst    | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

diff --git a/documentation/overview-manual/overview-manual-concepts.rst b/documentation/overview-manual/overview-manual-concepts.rst
index 7f8f735b3..c7a34f649 100644
--- a/documentation/overview-manual/overview-manual-concepts.rst
+++ b/documentation/overview-manual/overview-manual-concepts.rst
@@ -251,7 +251,7 @@ if versions do not already exist in the Build Directory at the time you
 source the build environment setup script.
 
 Because the Poky repository is fundamentally an aggregation of existing
-repositories, some users might be familiar with running the ```` script
+repositories, some users might be familiar with running the "script"
 in the context of separate
 :term:`OpenEmbedded-Core (OE-Core)` and BitBake
 repositories rather than a single Poky repository. This discussion
@@ -382,10 +382,10 @@ In general, three types of layer input exists. You can see them below
 the "User Configuration" box in the `general workflow
 figure <#general-workflow-figure>`__:
 
--  *Metadata (``.bb`` + Patches):* Software layers containing
+-  *Metadata (".bb" + Patches):* Software layers containing
    user-supplied recipe files, patches, and append files. A good example
    of a software layer might be the
-   ```meta-qt5`https://github.com/meta-qt5/meta-qt5 layer from
+   `meta-qt5`https://github.com/meta-qt5/meta-qt5 layer from
    the `OpenEmbedded Layer
    Index <http://layers.openembedded.org/layerindex/branch/master/layers/>`__.
    This layer is for version 5.0 of the popular
@@ -704,8 +704,7 @@ architecture are placed in ``build/tmp/deploy/ipk/qemux86``.
 
 .. _bitbake-dev-environment:
 
-BitBake
--------
+=, BitBake
 
 The OpenEmbedded build system uses
 :term:`BitBake` to produce images and
@@ -1143,9 +1142,9 @@ the extensible SDK (eSDK):
 
 Like image generation, the SDK script process consists of several stages
 and depends on many variables. The
-:ref:`ref-tasks-populate_sdk`
+`ref-tasks-populate_sdk`
 and
-:ref:`ref-tasks-populate_sdk_ext`
+`ref-tasks-populate_sdk_ext`
 tasks use these key variables to help create the list of packages to
 actually install. For information on the variables listed in the figure,
 see the "`Application Development SDK <#sdk-dev-environment>`__"
-- 
2.17.1

Re: [docs] [sphinx][PATCH] overview-manual: Clean up warnings for sphinx

[Nicolas Dechesne]

[-- Attachment #1: Type: text/plain, Size: 4492 bytes --]

hi Armin!

thanks for trying out the Sphinx docs!

On Sat, Sep 12, 2020 at 10:50 PM akuster <akuster808@gmail.com> wrote:

> Signed-off-by: Armin Kuster <akuster808@gmail.com>
> ---
>  .../overview-manual/overview-manual-concepts.rst    | 13 ++++++-------
>  1 file changed, 6 insertions(+), 7 deletions(-)
>
> diff --git a/documentation/overview-manual/overview-manual-concepts.rst
> b/documentation/overview-manual/overview-manual-concepts.rst
> index 7f8f735b3..c7a34f649 100644
> --- a/documentation/overview-manual/overview-manual-concepts.rst
> +++ b/documentation/overview-manual/overview-manual-concepts.rst
> @@ -251,7 +251,7 @@ if versions do not already exist in the Build
> Directory at the time you
>  source the build environment setup script.
>
>  Because the Poky repository is fundamentally an aggregation of existing
> -repositories, some users might be familiar with running the ```` script
> +repositories, some users might be familiar with running the "script"
>

This is not the proper fix. This is a weird artifact of the pandoc
migration.. if you look at the original XML you will see:

            <para>


                Because the Poky repository is fundamentally an aggregation
of

                existing repositories, some users might be familiar with


                running the <filename>&OE_INIT_FILE;</filename> script


                in the context of separate


                <ulink
url='&YOCTO_DOCS_REF_URL;#oe-core'>OpenEmbedded-Core</ulink>


                and BitBake repositories rather than a single Poky
repository.

                This discussion assumes the script is executed from


                within a cloned or unpacked version of Poky.


            </para>

Because pandoc does not understand the &XXX; notation, it ends up with an
'empty' string in verbatim mode, so : ````. So the right fix here is to
replace ```` with the link to this section:
https://docs.yoctoproject.org/ref-manual/ref-structure.html#oe-init-build-env


e.g. :ref:`ref-manual/ref-structure:\`\`oe-init-build-env\`\``

 in the context of separate
>  :term:`OpenEmbedded-Core (OE-Core)` and BitBake
>  repositories rather than a single Poky repository. This discussion
> @@ -382,10 +382,10 @@ In general, three types of layer input exists. You
> can see them below
>  the "User Configuration" box in the `general workflow
>  figure <#general-workflow-figure>`__:
>
> --  *Metadata (``.bb`` + Patches):* Software layers containing
> +-  *Metadata (".bb" + Patches):* Software layers containing
>     user-supplied recipe files, patches, and append files. A good example
>     of a software layer might be the
> -   ```meta-qt5`https://github.com/meta-qt5/meta-qt5 layer from
> +   `meta-qt5`https://github.com/meta-qt5/meta-qt5 layer from
>

hmm. did that produce the right link? I would expect

`meta-qt5 <https://github.com/meta-qt5/meta-qt5>`__

    the `OpenEmbedded Layer
>     Index <http://layers.openembedded.org/layerindex/branch/master/layers/
> >`__.
>     This layer is for version 5.0 of the popular
> @@ -704,8 +704,7 @@ architecture are placed in
> ``build/tmp/deploy/ipk/qemux86``.
>
>  .. _bitbake-dev-environment:
>
> -BitBake
> --------
> +=, BitBake
>

what is this change?


>
>  The OpenEmbedded build system uses
>  :term:`BitBake` to produce images and
> @@ -1143,9 +1142,9 @@ the extensible SDK (eSDK):
>
>  Like image generation, the SDK script process consists of several stages
>  and depends on many variables. The
> -:ref:`ref-tasks-populate_sdk`
> +`ref-tasks-populate_sdk`
>

I think this change was not needed (e.g. the link is already the right
one). It's a link to a label in another doc, so :ref: is right here.


>  and
> -:ref:`ref-tasks-populate_sdk_ext`
> +`ref-tasks-populate_sdk_ext`
>

Right, here, it's a link to a label which doesn't seem to exist. Looking a
bit closer.. it doesn't exist in the DocBook XML files themselves, so it's
a bug in the docbook xml file! If you look at the manual it has the
following link:
https://www.yoctoproject.org/docs/3.1.2/ref-manual/ref-manual.html#ref-tasks-populate_sdk_ext
which does not exist..

 tasks use these key variables to help create the list of packages to
>  actually install. For information on the variables listed in the figure,
>  see the "`Application Development SDK <#sdk-dev-environment>`__"
> --
> 2.17.1
>
> 
>

[-- Attachment #2: Type: text/html, Size: 8685 bytes --]