Add SUSE metadata to the sphinx build

[schaefi]

To support further features on the SUSE documentation an additional metadata block needs to be added to the XML representation of the sphinx documentation build use by the make docs_suse target.

[schaefi]

@tomschr This change already breaks the docbook results. Please rebuild and check yourself via

make docs_suse

from the kiwi git checkout

Thanks

[tomschr]

Thanks! 👍 I have only one minor comment, see below.

Just for references, when you apply the metadata, Sphinx creates this structure:

<field_list>
   <field>
     <field_name>meta</field_name>
     <field_body>
        <field_list>
           <field>
              <field_name>description</field_name>
              <field_body>
                  <paragraph>Your flexible operating system image and appliance builder</paragraph>
              </field_body>
           </field>
        <!-- ... expect more fields, but pruned ... -->
        </field_list>
     <field_body>
   <field>
</field_list>

In rstxml2docbook, we need to create a template rule that matches the tags from above. This template rule includes the necessary DocBook 5 <meta> tags.

[schaefi]

@tomschr you approved this but I keep it as draft and will not merge because it breaks the build. See here

make docs_suse

...
[INFO    ] - rstxml2db.xml.process - Writing results to 'build/xml/book.xml'...
bash -c 'mkdir -p doc/build/images/src/png && \
	cp -a doc/source/.images/* doc/build/images/src/png'
cp doc/DC-kiwi doc/build/
bash -c 'pushd doc/build && daps -d DC-kiwi html'
~/kiwi/doc/build ~/kiwi
ERROR: Inappropriate root element! Allowed elements are:
       appendix article assembly bibliography book chapter glossary glossdiv part preface qandaset reference refsect1 refsect2 refsect3 refsection sect1 sect2 sect3 sect4 sect5 section set
       Found variablelist

As you can see the produced doc/build/xml/book.xml is now wrong because it resolved the new
suse_metadata.rst into something like this

<variablelist xmlns="http://docbook.org/ns/docbook" role="field_list">
   ...
</variablelist>
<?xml-model 
      href="file:/usr/share/xml/docbook/schema/rng/5.1/docbookxi.rnc"
      type="application/relax-ng-compact-syntax"
     ?>

So I believe adaptions to rstxml2docbook are required and I can't make those

[tomschr]

Uhh, thanks. Yes, that certainly needs adaptions in the stylesheet of rstxml2docbook. Let's see when I find some time...

[tomschr]

@schaefi I've had a quick look and found something interesting. We basically are faced with two issues:

• The metadata from suse_metadata.rst.
  This should be an easy fix; it's basically adding new template rules to the stylesheet and converting the list into something useful (probably a DocBook <meta> tag).

• An empty .. toctree output.
  This is a more severe issue. In your main entry file source/index.rst you have a table of content in line 26ff:

  .. toctree::
     :maxdepth: 1
     :hidden:
  
     overview
     [...]

  This is fine. When you run make xml_suse, Sphinx transforms this into a <compound classes="toctree-wrapper">.

  However, I get this result in build/xml/index.xml:

  <compound classes="toctree-wrapper">
  </compound>

  It's empty! This is VERY unfortunate as my script needs this information to traverse all the files. If it's empty, this traversal cannot occur. Hence this is why you get a <book> element, but without much content. Argh! 😢

I'm not actually sure why this happened. This makes my script unusable as it relies on this element. Seems Sphinx changed something. I used Sphinx 9.1.0.

Before this change, there was a whole list inside <compound>. This is gone now. 😞

Not sure how to proceed here...

[schaefi]

Not sure how to proceed here...

Thanks much for digging into this. I made a commit that should solve the toctree problem