Skip to content

Commit 779bf83

Browse files
tomschrtomschr
committed
Document the Docserv config migration process
1 parent f2a61bd commit 779bf83

2 files changed

Lines changed: 211 additions & 0 deletions

File tree

‎docs/source/developer/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ This guide provides all the necessary information for contributing to the projec
2929
create-release
3030
trigger-actions
3131

32+
migrate-config
3233
build-docs
3334
howto
3435

‎docs/source/developer/migrate-config.rst‎

Lines changed: 210 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
1+
.. _migrate-config:
2+
3+
Migrating old Docserv Config to new Portal Config
4+
=================================================
5+
6+
.. note::
7+
8+
This section is used to document the migration process from the old Docserv config to the new Portal Schema. It has to be done only once and is not
9+
relevant for the regular users of the new Portal Schema or users starting
10+
from scratch.
11+
12+
With the introduction of the new Portal Schema in version 7, the schema got
13+
a massive overhaul.
14+
15+
Therefore, the old Docserv config is not compatible with the new Portal Schema
16+
anymore and needs to be migrated. The migration process can be done by a
17+
migration XSLT stylesheet.
18+
19+
You have two options how the result can look like:
20+
21+
* A directory with multiple files.
22+
23+
This is the recommended approach if you want to organize your configuration
24+
in a modular way and split the configuration into multiple files.
25+
It allows for better tracking of changes and easier collaboration.
26+
Files are referenced by XInclude elements and resolved during the validation
27+
process.
28+
29+
* A single configuration file.
30+
31+
This is useful if you want to debug the whole file, want to search for
32+
specific entries or values, or just prefer a single file.
33+
34+
Pre-requisites
35+
--------------
36+
37+
Before starting the migration process, ensure you have the following tools installed:
38+
39+
* :command:`xmllint`
40+
* :command:`xsltproc`
41+
* :command:`jing`
42+
43+
Furthermore, you need a Docserv stitchfile:
44+
45+
* Copy it with :command:`scp` from the Docserv server to your local machine.
46+
47+
The Docserv stitchfile, typically located at
48+
:file:`/tmp/docserv-stitch-${{DATE}}.xml` (whereas ``${DATE}`` is the
49+
ISO date of the stitchfile creation in the YYYY-MM-DD format).
50+
51+
* Create it locally by following the instructions in :ref:`prepare-stitchfile`.
52+
53+
54+
55+
.. _prepare-stitchfile:
56+
57+
Preparing the Docserv Stitchfile
58+
--------------------------------
59+
60+
.. note::
61+
62+
The steps below is what the command :command:`docserv-stitch` does on
63+
the Docserv server to create the stitchfile. Of course, the script is
64+
more complex and takes care of validation and other checks, but the above steps are the core of the stitchfile creation process.
65+
66+
As such, make sure your Docserv configs are valid.
67+
68+
69+
If you don't have access to the Docserv server or prefer to create the stitchfile locally, follow these steps to prepare it:
70+
71+
#. Clone the Docserv config repo if you haven't already:
72+
73+
.. code-block:: console
74+
75+
git clone https://gitlab.suse.de/susedoc/docserv-config.git
76+
cd docserv-config/config.d
77+
78+
#. Set the result file name and path:
79+
80+
.. code-block:: console
81+
82+
stitchfile="/tmp/docserv-stitch-$(date --iso-8601).xml"
83+
84+
#. Prepare the header of the stitchfile:
85+
86+
.. code-block:: console
87+
88+
cat << EOF > "$stitchfile"
89+
<?xml version="1.0" encoding="UTF-8"?>
90+
<docservconfig>
91+
<!-- <hashes>...</hashes> -->
92+
93+
EOF
94+
95+
#. Copy content from all categories into result:
96+
97+
.. code-block:: console
98+
99+
xmllint --xpath "/*" _categories.xml >> "$stitchfile"
100+
101+
#. Append all config files to the result:
102+
103+
.. code-block:: console
104+
105+
xmllint --xpath "/*" $TMPCONFIGDIR/[a-z]*.xml >> "$stitchfile"
106+
107+
#. Close the root element:
108+
109+
.. code-block:: console
110+
111+
printf "</docservconfig>\n" >> "$stitchfile"
112+
113+
114+
.. _convert-stitchfile:
115+
116+
Converting the Stitchfile
117+
-------------------------
118+
119+
To convert the stitchfile to the new Portal Schema format, use:
120+
121+
* the command :command:`xsltproc` to run the XSLT transformation,
122+
* some of the available XSLT parameters to customize the output as needed (see :ref:`available-xslt-parameters`),
123+
* the migration XSLT stylesheet located at :file:`src/docbuild/config/xml/data/convert-v6-to-v7.xsl`, and
124+
* the stitchfile you prepared in the :ref:`previous section <prepare-stitchfile>`.
125+
126+
127+
.. _available-xslt-parameters:
128+
129+
Available XSLT Parameters
130+
~~~~~~~~~~~~~~~~~~~~~~~~~
131+
132+
The migration XSLT stylesheet accepts the following XSLT parameters:
133+
134+
* ``cat.prefix`` (default ``cat.``)
135+
136+
The prefix for category IDs.
137+
138+
* ``schemafile`` (default empty)
139+
140+
The path to the new Portal Schema file (e.g., :file:`portal-config.rnc`).
141+
The stylesheet recognize the format (RNC or RNG) and changes the ``<?xml-model?>`` PI accordingly.
142+
143+
* ``outputfile`` (default :file:`portal.xml`)
144+
145+
The name of the main configuration file.
146+
147+
* ``outputdir`` (default :file:`output/`)
148+
149+
The base directory where the output file(s) will be saved.
150+
If you want to use the current directory, use ``./``.
151+
152+
* ``use.xincludes`` (default ``false``)
153+
154+
A boolean parameter that determines whether to use XInclude elements in the output.
155+
Set it to ``true`` to create a directory with multiple files, or use the
156+
default to create a single configuration file.
157+
158+
* ``schemaversion`` (default latest)
159+
160+
The version of the new Portal Schema to target. This is used to determine the necessary transformations to apply during the migration process.
161+
162+
163+
.. _create-config-file-with-multiple-files:
164+
165+
Creating Multiple Files
166+
~~~~~~~~~~~~~~~~~~~~~~~
167+
168+
To create a directory with multiple files, do the following:
169+
170+
#. Run the XSLT transformation with the following command:
171+
172+
.. code-block:: console
173+
174+
xsltproc --stringparam outputfile portal.xml \
175+
--stringparam outputdir "./output/" \
176+
--param use.xincludes 'true()' \
177+
src/docbuild/config/xml/data/convert-v6-to-v7.xsl $stitchfile
178+
179+
This will create all files in the :file:`output/` directory, with the main
180+
configuration file named :file:`portal.xml` and additional files for
181+
each category as needed.
182+
183+
#. Copy the generated files to the desired location.
184+
185+
#. Adjust the env configuration to point to the main configuration file,
186+
use the variable :literal:`paths.config_dir` and :literal:`paths.main_portal_config`.
187+
188+
189+
.. _create-single-config-file:
190+
191+
Creating a Single File
192+
~~~~~~~~~~~~~~~~~~~~~~
193+
194+
To create a single configuration file, , do the following:
195+
196+
#. Run the XSLT transformation with the following command:
197+
198+
.. code-block:: console
199+
200+
xsltproc --stringparam schemafile "portal-config.rnc" \
201+
--stringparam outputfile portal-$(date --iso-8601).xml \
202+
--stringparam outputdir "./" \
203+
src/docbuild/config/xml/data/convert-v6-to-v7.xsl $stitchfile
204+
205+
This will create a file named :file:`portal-<DATE>.xml` in the current directory.
206+
207+
#. Copy the generated output file to the desired location.
208+
209+
#. Adjust the env configuration to point to the main configuration file,
210+
use the variable :literal:`paths.config_dir` and :literal:`paths.main_portal_config`.

0 commit comments

Comments
 (0)