This commit adds a documentation for the KIWI XML description.
In contrast to the former auto generated code from the XML
schema this document can now finally be used as a reference.
Along with that new chapter all auto generated and static
html content as been deleted. Also all helper scripts around
the proprietary oxygen tool and our schema doc generator
has been deleted. Auto generating this information does not
lead to a reference guide people can really work with.
As a consequence to these changes this commit also includes
some changes of the structure such that no information written
by other people in the past gets lost. This Fixes#1421
and Fixes#1474
SUSE documentation is based on docbook or asciidoc. The kiwi
documentation is maintained along with the code and uses the
sphinx system and therefore ReST as markup language. We would
like to keep one source and don't want to move to another markup
language. Thus the sources needs to be structured in a way that
allows translation into sphinx supported targets as well as
into SUSE docbook style. This commit changes the documentation
structure in a way that both is possible. With the use of Sphinx
XML and rstxml2docbook the ReST docs are converted into docbook.
From there the SUSE daps tool can create SUSE documentation
Given there is a valid Oxygen license owned by the company
as described in https://www.oxygenxml.com/oxygen_scripting.html
the schema documentation can be created using Oxygen. This
commit allows building the schema docs with alternative
doc builders and in case of Oxygen would change the way the
schema docs are generated in the following way:
1. Install Oxygen and setup the license to activate the tool
2. Setup the KIWI development shell environment to export
the schema_tool variable to point to the schemaDocumentation.sh
script provided by the Oxygen installation
export oxygen_tool=/path/to/Oxygen/schemaDocumentation.sh
3. In any case of a schema change manually call:
tox -e schema
This step was done before as part of the tox doc target
but can't be done automatically because it would require
a correctly licensed Oxygen installation in the travis
environment. Thus the result data has to be part of the
pull request
4. Build the documentation and review the result
tox -e doc
5. Create the pull request
The documentation will cover kiwi manual pages. more detailed
documentation will be written and maintained in colaboration
with the documentation department
