Building Uyuni docs for the Open Build Service
-
You have the SUSE Open build service tools setup on your local machine, and you have an account at
build.opensuse.org. For more information on configuring OBS see the OBS Tutorial. -
Our documentation tool chain should be installed. See: Toolchain Installation
-
From your local git checkout of uyuni-docs in parameters.yml verify that the default value for
site.urlis enabled for uyuni-project.org.site: - attribute: title value: "Uyuni Documentation" - attribute: start_page value: "uyuni::index" - attribute: url value: https://www.uyuni-project.org/uyuni-docs/
Check the Uyuni version number in the parameters.yml. This should be adjusted to the release version.
asciidoc:
- attribute: productname
value: "Uyuni"
- attribute: productnumber
value: "2023.12"
- attribute: docversion
value: "2023.12"
- attribute: minorversion
value: "2023.12"
+
-
Check the following attributes in the parameters.yml ensuring the file version numbers are correct. These numbers can be found in the OBS package spec files. For example:
salt.spec:asciidoc: - attribute: opensuse-version value: 15.5 - attribute: saltversion value: 3006.0 - attribute: postgresql value: PostgreSQL - attribute: postgresql-version value: 14 - attribute: sles-version value: 15 - attribute: sp-version value: SP5 #use for normal text - attribute: sp-vert value: sp5 #use for terminal block - attribute: sp-version-l value: sp5
-
Build the OBS packages. From the local checkout directory on the command line run:
examplemake obs-packages-uyuni
-
Once packages are built configure the correct environment variables for OBS:
exampleOBS_USER=keichwa OBS_USER=jcayouette OBS_USER=omaric
-
Add the target OBS repo. For Uyuni, use:
exampleOBS_REPO=systemsmanagement:Uyuni:Master
-
Checkout the docs package from OBS:
osc -A https://api.opensuse.org bco $OBS_REPO uyuni-docs_en
If this fails with a 404, login to your account at build.suse.org and try again.
-
Copy the two new packages located in build/packages into:
build/home:$OBS_USER:branches:$OBS_REPO/uyuni-docs_en -
Change into the OBS checkout dir:
cd home:$OBS_USER:branches:$OBS_REPO/uyuni-docs_en
-
Create the changes file.
For Uyuni, it is named:
-
uyuni-docs_en.changesosc vc uyuni-docs_en.changes
-
-
Copy the changes from the .changelog file under the timestamp, and save. release number as the top entry in both files. It should look something like this:
example------------------------------------------------------------------- Wed July 7 15:16:07 UTC 2021 - Joseph Cayouette <[email protected]> - Version 2021.07 <---- BUMP VERSION - Updated wording for prometheus section - Jeos VM update - Port 8050 for graphical console display - Content life-cycle docs are not enough for customer to understand (bsc#1137955) - Salt boot formula fails for SLES11 SP3 terminal (bsc#1136857) - Certificate verify failed when using vmware esxi virtual host gatherer (bsc#1136561) -------------------------------------------------------------------
The changes file must be located in the build/home:$OBS_USER:branches:$OBS_REPO/susemanager-docs_en directory, along with the package files you created earlier.
-
For Uyuni, you need to update the version release number in the .spec files. Open the following file in your text editor, and update the
Version:entry (around L19) with the version you are preparing:-
uyuni-docs_en.specexampleName: uyuni-docs_en Version: 2020.06 Release: 0
Save the files.
-
-
Check in the changes. This will also start the build:
osc ci -m "update"
-
It will take about 15 minutes for all the packages to build. You can check the build results in your home project; e.g. with:
osc pr
Alternatively, you can go to the OBS site to monitor progress.
-
When you are certain that doc packages are building properly on OBS submit an service request to Marina or Raul:
osc sr -m 'update'
After a successful review they will accept the service request (SR).
-
You have the SUSE Open build service tools setup on your local machine, and you have an internal account at
build.opensuse.org. For more information on configuring OBS see the OBS Tutorial. -
Our documentation tool chain should be installed. See: Toolchain Installation
The following guide will walk you through updating API content at: http://www.uyuni-project.org/uyuni-docs-api/uyuni/index.html . Clone our API docs repository at: https://github.com/uyuni-project/uyuni-docs-api
-
Create a new branch from master for this release:
git checkout -b uyuni-api-yyyy.mm-beta // for development git checkout -b uyuni-api-yyy.mm // for major release git push
-
On OBS search for
https://download.opensuse.org/repositories/systemsmanagement:/Uyuni:/. Click Repositories, then one of thestandardlinks. -
Use the
Downloadbutton next to aspacewalk-java-apidoc-sources-{VERSION}.noarch.rpm. -
Extract the asciidoc files:
unrpm -v spacewalk-java-apidoc-sources-VERSION.noarch.rpm
-
Enter the rpm directory:
cd usr/share/doc/packages/spacewalk-java/asciidoc/
-
Open either the apilist.adoc or the xml file from asciidoctor/docbook sources and verify the version number before building
-
Drop the adoc files into your local clone located:
-
https://github.com/uyuni-project/uyuni-docs-api/modules/api/pages
❗For each release the API is updated with new functionality. Ensure that the list of calls contained in the RPM within apilist.adoc matches the list located in our api nav and index.adoc at the following locations:
-
-
After verifying the index and api nav lists match the current calls build the api docs with:
make antora-suma
-
Copy the
build/contents to a temporary location. -
Checkout the ghpages branch:
git checkout gh-pages -
Create a new PR branch for gh-pages:
git checkout -b uyuni-api-yyyy.mm -
Create a merge request and ping Julio or Jordi.
