building suma docs
-
From your local git checkout run the following command to see all available build options:
make help
-
To build the suma static HTML pages and PDF documents run:
make antora-suma
The following guides are currently available.
|
💡
|
If you are having troubles building a guide, check the antora.yml file to ensure a book is not commented out. For example architecture. (This book is not actively published.) |
Run make with one of the following build targets to build a single book.
| Command | Output |
|---|---|
make pdf-install-suma |
SUMA Installation Guide |
make pdf-client-config-suma |
SUMA Client Configuration Guide |
make pdf-upgrade-suma |
SUMA Upgrade Guide |
make pdf-reference-suma |
SUMA Reference Manual |
make pdf-administration-suma |
SUMA Administration Guide |
make pdf-salt-suma |
SUMA Salt Guide |
make pdf-retail-suma |
SUMA Retail Guide |
make pdf-architecture-suma |
SUMA Architecture Guide |
Run make with the following build target to build the SUMA PDF collection. Keep in mind that by default when building with make antora-suma the entire PDF collection is built automatically.
-
make pdf-all-sumaBuild the SUMA PDF Collection
- Starting Assumptions
-
You have the SUSE OBS tools setup on your local machine and you have an internal account
For more information on setting up OBS see the OBS Tutorial.
-
From your local git checkout of doc-susemanager modify your suma-site.yml file. Disable the site.url key with a comment when building for the product UI since the files are stored locally.
# Contribute, not edit this page # Doc site [title, and start page] site: title: SUSE Manager Documentation start_page: suse-manager::index-suma # site.url should be adjusted before building depending on the desired target. # The site.url value is used to create the base url for the sitemap.xml file. # # The following selections are available # - Github Pages: https://opensource.suse.com/doc-susemanager # - Product UI can be left blank. # - SUSE.com: https://www.suse.com/documentation/suse-manager-4/4.0/ # - (docteam) Docserv Development https://documentation.provo.novell.com/external-tree/en-us/suma/4.0/suse-manager # - (docteam) Docserv Production https://documentation.suse.com/external-tree/en-us/suma/4.0/suse-manager #url:
-
Under the content.sources key comment out the local key, you want to build from the remote:
content: sources: # Uncomment to build from your local git clone #- url: . # Uncomment to build from the remote github repository. - url: https://github.com/SUSE/doc-susemanager.git # To build locally ensure you have your current local branch listed. branches: - 'master'
-
Select the correct ui.bundle key and ui.supplemental_files key. For example when building for OBS you would set the following :
ui: bundle: # Choose a default-ui to use # - suma-susecom.zip (suse.com branding theme) # - suma-product.zip (no search no draft watermark use for OBS) # local git repo bundle for development url: ./branding/default-ui/suma/suma-product.zip snapshot: true # Choose a UI for your publishing endpoint # - suma-webui (product ui on OBS) # - suma-ghpages (for publishing to gh-pages) # - susecom (suse.com/documentation publishing and docserv) supplemental_files: ./branding/supplemental-ui/suma/suma-webui
-
Build the OBS packages:
make obs-packages-suma
-
Now that you have the packages built configure your environment variables for OBS on the CLI:
OBS_USER=keichwa OBS_USER=jcayouette OBS_USER=lbrindley
-
Add the target repo, in most cases this will be Head:
Add for Head: OBS_REPO=Devel:Galaxy:Manager:Head Add for 3.0 OBS_REPO=Devel:Galaxy:Manager:3.0 Add for 3.1 OBS_REPO=Devel:Galaxy:Manager:3.1
-
Checkout the docs package from OBS (usually I check it out into my doc-susemanager/build folder as it is cleaned up anyway on a new build):
osc -A https://api.suse.de bco $OBS_REPO susemanager-docs_en
-
Copy the two new packages located in build/packages into build/home:$OBS_USER:branches:$OBS_REPO/susemanager-docs_en
-
Change into the OBS checkout dir:
cd home:$OBS_USER:branches:$OBS_REPO/susemanager-docs_en
-
Make a new version change before checkin. You need to have the exact same changes in two files:
susemanager-docs_en.changes susemanager-doc-indexes.changes
I usually make the changes to one then copy them to the other file. They must have the same timestamps see the examples below:
osc vc susemanager-docs_en.changes
susemanager-docs_en.changes------------------------------------------------------------------- Wed Jun 19 15:16:07 UTC 2019 - Joseph Cayouette <[email protected]> - 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) -------------------------------------------------------------------
Make an exact copy of your changes above including white space and add them to the doc indexes.
osc vc susemanager-doc-indexes.changes
susemanager-doc-indexes.changes------------------------------------------------------------------- Wed Jun 19 15:16:07 UTC 2019 - Joseph Cayouette <[email protected]> - 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) -------------------------------------------------------------------
-
Checkin the changes:
osc ci -m "update"
-
You can check the build results in your home project; e.g. with:
osc pr
-
Once you are certain doc packages are building properly on OBS submit an service request to Julio (If everything looks good he will accept and the docs will be included in the new RPM’s.):
osc sr -m 'update'
This completes publishing on OBS.