From aa24818e25a188304b393d0bbb9c5cf2b9e3ecfd Mon Sep 17 00:00:00 2001 From: Stefan Knorr Date: Mon, 10 Jan 2022 18:42:07 +0100 Subject: [PATCH 1/4] docserv: Use `my-site.ini` as default name of site config file Invoking `docserv docserv` every single time is really confusing. `docserv my-site` seems much better. --- src/docserv/docserv.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docserv/docserv.py b/src/docserv/docserv.py index 32d4c3b6..967d54b7 100644 --- a/src/docserv/docserv.py +++ b/src/docserv/docserv.py @@ -259,7 +259,7 @@ def join_conf_dir(path): config = configparser() if len(argv) == 1: - config_file = "docserv" + config_file = "my-site" else: config_file = argv[1] config_path=os.path.join(CONF_DIR, config_file + '.ini') From 586f0cdbbce2062faf4d2720bd7b0fdb005e575c Mon Sep 17 00:00:00 2001 From: Stefan Knorr Date: Mon, 10 Jan 2022 18:49:30 +0100 Subject: [PATCH 2/4] config: Update example config to actually make sense MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The example config had last been updated for Docserv² 3.x and even then was not complete. --- config/{docserv.ini => my-site.ini} | 127 +++++++++--------- config/product-config/docserv2.xml | 49 +++++++ .../example_product.xml | 35 ++--- config/{ => server-root-files}/htaccess.txt | 0 config/templates/template-product.html | 20 +++ .../templates/template-section-default.html | 25 ++++ config/templates/template.html | 13 -- config/templates/translation.xml | 22 --- 8 files changed, 168 insertions(+), 123 deletions(-) rename config/{docserv.ini => my-site.ini} (57%) create mode 100644 config/product-config/docserv2.xml rename config/{config.d => product-config}/example_product.xml (89%) rename config/{ => server-root-files}/htaccess.txt (100%) create mode 100644 config/templates/template-product.html create mode 100644 config/templates/template-section-default.html delete mode 100644 config/templates/template.html delete mode 100644 config/templates/translation.xml diff --git a/config/docserv.ini b/config/my-site.ini similarity index 57% rename from config/docserv.ini rename to config/my-site.ini index 8222ce8f..e46a0fe0 100644 --- a/config/docserv.ini +++ b/config/my-site.ini @@ -1,99 +1,92 @@ [server] + +# Where to host the REST API host = localhost port = 8080 -# Loglevels -# 0: warning -# 1: info -# 2: debug -loglevel = 2 -# The repo dir will be used to cache remote git repositories. -repo_dir = /mnt/docserv-repos/ + +# The repo dir will be used to cache remote Git repositories. +repo_dir = /home/docserv/docserv-repos/ # For building, the locally cached git repo will be cloned again. # This prevents branch checkout collisions during builds and other -# problems. It is recommended to mount a sufficiently large RAM disk -# to the temp_repo_dir directory. -temp_repo_dir = /dev/shm/ +# problems. +temp_repo_dir = /home/docserv/docserv-branches/ + +# A list of language codes that are recognized as valid. +valid_languages = en-us de-de fr-fr pt-br ja-jp zh-cn es-es it-it ko-kr hu-hu zh-tw cs-cz ar-ar pl-pl ru-ru # The upper limit of threads is the number of logical CPU cores. Use # the max_threads setting to reduce the number of threads. max_threads = 8 -# A list of language codes that are recognized as valid. -valid_languages = en-us de-de fr-fr pt-br ja-jp zh-cn es-es it-it ko-kr hu-hu zh-tw cs-cz ar-ar pl-pl ru-ru -# sections need to start with 'target_' +# Whether to enable error reports via mail +enable_mail = no +# Log levels: 0 - warning, 1 - info, 2 - debug +loglevel = 0 + + +# target section names need to start with "target_" [target_0] + # Name of the target to identify it in the documentation configuration. name = internal # If not active, documents for the target will not be built. active = yes +# Internal builds (this means even documents marked "unpublished" will be linked) +internal = no + +# Whether to enable syncing to target_path. If disabled, only the local content in backup_path is updated +enable_target_sync = no +# A URL to the publication path. Can be a local or ssh/scp URL. +target_path = ssh://docserv@localhost:/srv/www/htdocs/documentation +# A URL to the publication path. Can be a local or ssh/scp URL. +backup_path = /home/docserv/target-backup + +# Directory where the document configuration in XML format resides. +config_dir = product-config/ +# Directory for overview page templates. +template_dir = templates/ +# Directory with files to copy to the server's root directory, such as +# robots.txt, .htaccess, or a favicon. +server_root_files = server-root-files-internal +# Default XSLT parameters file (file must contain parameters of the form +# parameter=value, separated by newlines). +default_xslt_params = xslt-params.txt + +# Fragments allow using localized Server-Side Includes (SSIs) as part of the +# template -- they are optional, if `enable_ssi_fragments` is set to `no`, the +# parameter `fragment_dir` and `fragment_l10n_dir` are not required. +enable_ssi_fragments = no +fragment_dir = fragments/ +fragment_l10n_dir = l10n/ + +# Relative root path of the Docserv² installation on the publication server +# Used for relative resource paths within the navigational HTML pages +server_base_path = / +# Beginning of the URL to use for tags, must omit +# server base path and generated path +canonical_url_domain = https://www.example.org + # Add the draft watermarks to the documents. draft = yes # Add remarks to the documents. remarks = yes # Add meta information (XML ID and source file name) to the documents. meta = no -# Default XSLT parameters file (file must contain parameters of the form -# parameter='value', separated by newlines) -default_xslt_params = /etc/docserv/xslt-params.txt -# Directory for overview page templates. -template_dir = /etc/docserv/templates/ -# Directory where the document configuration in XML format resides. -config_dir = /etc/docserv/config.d/ -# A URL to the publication path. Can be a local or ssh/scp URL. -target_path = ssh://user@server:/srv/www/htdocs/documentation -# A URL to the publication path. Can be a local or ssh/scp URL. -backup_path = /mnt/internal-builds/ +# Use a non-standard build container for this target (optional attribute). +#build_container = ... + # Languages that will appear in the web UI languages = en-us # Default language of the web UI default_lang = en-us # Whether to omit the default language's path component from links by default omit_default_lang_path = no -# Internal builds (this means even documents marked "unpublished" will be linked) -internal = yes -# Document formats that should be contained in automatically generated zip files -zip_formats = pdf epub single-html -# Relative root path of the docserv2 installation on the publication server -# Used for relative resource paths within the navigational HTML pages -server_base_path = / -# Beginning of the URL to use for tags, must omit -# server base path and generated path -canonical_url_domain = https://www.example.org -# Directory with files to copy to the server's root directory, such as -# robots.txt, .htaccess, or a favicon. -server_root_files = /etc/docserv/server-root-files-internal -# Fragments allow using localized Server-Side Includes (SSIs) as part of the -# template -- they are optional, if `enable_ssi_fragments` is set to `no`, the -# parameter `fragment_dir` and `fragment_l10n_dir` are not required. -enable_ssi_fragments = yes -fragment_dir = /etc/docserv/fragment-internal -fragment_l10n_dir = /etc/docserv/fragment-l10n-internal + # Sections of the published site. Each section gets an own top-level # navigation page. XML product configuration files can be assigned to a site -# section using the attribute. Each site section -# needs an HTML template file named template-[SITE_SECTION].html. -site_sections = main best-practices +# section using the `` attribute. +site_sections = main alternative # The default site section is used as the top-level index.html page. default_site_section = main -[target_1] -name = external -active = yes -draft = no -remarks = no -meta = no -default_xslt_params = /etc/docserv/xslt-params.txt -template_dir = /etc/docserv/templates/ -config_dir = /etc/docserv/config.d/ -target_path = ssh://user@pubserver:/srv/www/htdocs/documentation -backup_path = /mnt/external-builds/ -languages = en-us de-de fr-fr pt-br ja-jp zh-cn es-es -default_lang = en-us -omit_default_lang_path = no -internal = no +# Document formats that should be added to automatically generated ZIP files. zip_formats = pdf epub single-html -server_base_path = / -canonical_url_domain = https://www.example.org -server_root_files = /etc/docserv/server-root-files-external -enable_ssi_fragments = no -site_sections = main -default_site_section = main diff --git a/config/product-config/docserv2.xml b/config/product-config/docserv2.xml new file mode 100644 index 00000000..dbca3408 --- /dev/null +++ b/config/product-config/docserv2.xml @@ -0,0 +1,49 @@ + + + + Docserv² + Ds2 + + p.erson@example.org + + + +

+ Docserv² is a tool to publish and semi-automatically update large-scale + documentation websites accommodating multiple products, product + versions, and localizations. It focuses on allowing publication of + DocBook/AsciiDoc content that is compatible with DAPS. However, it can + also accommodate links to other sources of documents. +

+ + + + 6 + + + + + + + main + docs + + + DC-docserv + + + + + + + + + + + + + + + + + diff --git a/config/config.d/example_product.xml b/config/product-config/example_product.xml similarity index 89% rename from config/config.d/example_product.xml rename to config/product-config/example_product.xml index ee19760f..d967c7df 100644 --- a/config/config.d/example_product.xml +++ b/config/product-config/example_product.xml @@ -7,7 +7,7 @@ only works within the docserv Git repository. --> - +

This product will lose control of you and help you live free. - SP is so glad to have you and your evil curls. + XP is so glad to have you and your evil curls.

Ce produit ne peut pas obtenir la contrôle de vous, mais le vous aidez - a vivir libre. SP est très heureux de vous avoir et d'avoir vos + a vivir libre. XP est très heureux de vous avoir et d'avoir vos cheveux chevalier.

@@ -75,12 +75,12 @@

Dieses Produkt hat die Kontrolle über Sie bereits verloren und will - Ihnen helfen, lieber libre zu leben. SP ist verzückt, dass Sie ihm + Ihnen helfen, lieber libre zu leben. XP ist verzückt, dass Sie ihm und seinen bösartigen Lockrufen gefolgt sind.

- + 2.0 @@ -88,7 +88,7 @@ - develop + main @@ -119,19 +119,7 @@ - - maint/xp15 - sles/de - - DC-example-all - book.user - - - DC-example-user - - - - + maint/xp15 sles/zh-cn @@ -192,7 +180,7 @@ - develop + main DC-example-all @@ -222,7 +210,12 @@ - + + + + + + diff --git a/config/htaccess.txt b/config/server-root-files/htaccess.txt similarity index 100% rename from config/htaccess.txt rename to config/server-root-files/htaccess.txt diff --git a/config/templates/template-product.html b/config/templates/template-product.html new file mode 100644 index 00000000..1e611840 --- /dev/null +++ b/config/templates/template-product.html @@ -0,0 +1,20 @@ + + + + Docset template + + + + +
+
+ + diff --git a/config/templates/template-section-default.html b/config/templates/template-section-default.html new file mode 100644 index 00000000..52cceee9 --- /dev/null +++ b/config/templates/template-section-default.html @@ -0,0 +1,25 @@ + + + + Site section template + + + + +
+ +
+
Downloading data...
+
+
+
Select a product
+
+ + diff --git a/config/templates/template.html b/config/templates/template.html deleted file mode 100644 index a519caf7..00000000 --- a/config/templates/template.html +++ /dev/null @@ -1,13 +0,0 @@ - - - - - Docserv² Sample Template - - - - - - - - diff --git a/config/templates/translation.xml b/config/templates/translation.xml deleted file mode 100644 index 0782cb8a..00000000 --- a/config/templates/translation.xml +++ /dev/null @@ -1,22 +0,0 @@ - - - - Docserv² - Docserv² - -

- This is Docserv². -

- - - (beta) - (not publicly available) - (deliverable title missing) - (path for link missing) - multi-page view - one-page view - E-Book (EPUB) - PDF - - - From 519a907601f1ebbdfb0c8bcf513d06538adf994a Mon Sep 17 00:00:00 2001 From: Stefan Knorr Date: Mon, 10 Jan 2022 18:48:26 +0100 Subject: [PATCH 3/4] =?UTF-8?q?docs:=20Add=20Docserv=C2=B2=20config,=20ins?= =?UTF-8?q?tall,=20API=20docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Sorry for the huge commit. Suddenly everything was dependent on each other. :/ Co-authored-by: Tom Schraitle Co-authored-by: Quang Tran --- docs/DC-docserv | 6 + docs/adoc/0-docserv-guide.adoc | 26 + docs/adoc/1-attribute.adoc | 10 + docs/adoc/api.adoc | 77 +++ docs/adoc/backup.adoc | 48 ++ docs/adoc/config-localization.adoc | 69 +++ docs/adoc/config-overview.adoc | 23 + docs/adoc/config-product.adoc | 327 ++++++++++++ docs/adoc/config-site.adoc | 314 +++++++++++ docs/adoc/config-ssi-fragment.adoc | 125 +++++ docs/adoc/config-template.adoc | 134 +++++ docs/adoc/install-run.adoc | 88 ++++ docs/adoc/intro-overview.adoc | 35 ++ docs/adoc/intro-terminology.adoc | 60 +++ docs/docserv-style.css | 38 ++ docs/images/src/svg/docserv2-overview.svg | 607 ++++++++++++++++++++++ 16 files changed, 1987 insertions(+) create mode 100644 docs/DC-docserv create mode 100644 docs/adoc/0-docserv-guide.adoc create mode 100644 docs/adoc/1-attribute.adoc create mode 100644 docs/adoc/api.adoc create mode 100644 docs/adoc/backup.adoc create mode 100644 docs/adoc/config-localization.adoc create mode 100644 docs/adoc/config-overview.adoc create mode 100644 docs/adoc/config-product.adoc create mode 100644 docs/adoc/config-site.adoc create mode 100644 docs/adoc/config-ssi-fragment.adoc create mode 100644 docs/adoc/config-template.adoc create mode 100644 docs/adoc/install-run.adoc create mode 100644 docs/adoc/intro-overview.adoc create mode 100644 docs/adoc/intro-terminology.adoc create mode 100644 docs/docserv-style.css create mode 100644 docs/images/src/svg/docserv2-overview.svg diff --git a/docs/DC-docserv b/docs/DC-docserv new file mode 100644 index 00000000..32ca5922 --- /dev/null +++ b/docs/DC-docserv @@ -0,0 +1,6 @@ +MAIN=0-docserv-guide.adoc + +HTML_CSS=docserv-style.css +ADOC_POST=yes +ADOC_TYPE=book +XSLTPARAM=--stringparam chunk.section.depth=0 diff --git a/docs/adoc/0-docserv-guide.adoc b/docs/adoc/0-docserv-guide.adoc new file mode 100644 index 00000000..3a977f6c --- /dev/null +++ b/docs/adoc/0-docserv-guide.adoc @@ -0,0 +1,26 @@ +include::1-attribute.adoc[] + +[#docserv2-guide] +# {ds2} Guide + +include::intro-overview.adoc[leveloffset=+1] + +include::intro-terminology.adoc[leveloffset=+1] + +include::install-run.adoc[leveloffset=+1] + +include::config-overview.adoc[leveloffset=+1] + +include::config-site.adoc[leveloffset=+1] + +include::config-product.adoc[leveloffset=+1] + +include::config-template.adoc[leveloffset=+1] + +include::config-localization.adoc[leveloffset=+1] + +include::config-ssi-fragment.adoc[leveloffset=+1] + +include::backup.adoc[leveloffset=+1] + +include::api.adoc[leveloffset=+1] diff --git a/docs/adoc/1-attribute.adoc b/docs/adoc/1-attribute.adoc new file mode 100644 index 00000000..8e84de81 --- /dev/null +++ b/docs/adoc/1-attribute.adoc @@ -0,0 +1,10 @@ +:ds2: Docserv² +// FIXME: Can't get this to work :/ cf. https://docs.asciidoctor.org/asciidoc/latest/attributes/attribute-entry-substitutions/ +// :dscmd: `**dscmd**` +:dscmd: dscmd +:db: DocBook +:ad: AsciiDoc +:daps: DAPS +:os: openSUSE +:leap: {os} Leap +:tw: {os} Tumbleweed diff --git a/docs/adoc/api.adoc b/docs/adoc/api.adoc new file mode 100644 index 00000000..337a5513 --- /dev/null +++ b/docs/adoc/api.adoc @@ -0,0 +1,77 @@ +include::1-attribute.adoc[] + +[#api] +# Using the {ds2} API + +{ds2} includes a nascent (read, "not particularly good") REST API. + +The API runs at the API interface defined via the site configuration's `host` and `port` attributes. +For more information, see <>. + + +[#api-client-dscmd] +## The {dscmd} command-line API client + +The official API client is {dscmd} which is available as an RPM package from the openSUSE Build Service's `Documentation:Tools` repository or from the link:https://github.com/openSUSE/dscmd[dscmd GitHub repository]. +Installation from the RPM works analogously to that of {ds2} itself, see <>. + +The {dscmd} client includes a `--help` switch. + +To set up {dscmd}, create a configuration file `~/.dscmd-server.conf` with the following content: + +[source,bash,subs="+quotes"] +---- +server=__[HOST]__ +port=__[PORT]__ +validtargets=__[TARGETS]__ +---- + +Replace `__[HOST]__`, `__[PORT]__`, and `__[TARGETS]__` with values appropriate for your installation. +Target names must match the names defined using the `name` attribute of the target sections in the site configuration (<>). +You can combine multiple target values using commas characters (`,`), for example: `validtargets=target_1,target_2`. +(Do not add spaces around the comma characters.) + +This configuration file will be sourced by Bash. +This means it must follow Bash syntax (and may contain arbitrary code). + +[#api-call] +## API calls + + +[#api-check-build] +### Checking build status + +To check the current build statuses and review the past build queue, make a `GET` request to the JSON endpoint `http://__[HOST]__:__[PORT]__/`. + +Alternatively, use `**dscmd queue**`. + + +[#api-send-build-instruction] +### Sending a build instruction + +To send a build instruction, make a `POST` request to the endpoint `http://__[HOST]__:__[PORT]__/` with JSON data attached: + +[source,bash,subs="+quotes"] +---- +> curl \ + --header "Content-Type: application/json" \ + --request POST \ + --data '{"target":"__[TARGET]__","product":"__[PRODUCT]__","docset":"__[DOCSET]__","lang":"__[LANGUAGE_CODE]__"}' \ + __[HOST]__:__[PORT]__ +---- + +Replace `__[TARGET]__`, `__[PRODUCT]__`, `__[DOCSET]__`, `__[LANGUAGE_CODE]__`, `__[HOST]__`, and `__[PORT]__` with appropriate values. +You can combine multiple build instructions into a single `POST` requests by sending a data field with multiple JSON objects separated with comma characters (`,`). + +Alternatively, use: + +[source,bash,subs="+quotes"] +---- +> dscmd trigger \ + --target=__[TARGET]__ + --product=__[PRODUCT_ID]__ --docset=__[DOCSET_ID]__ + --lang=__[LANGUAGE_CODE]__. +---- + +Within each parameter, you can combine multiple values using comma characters (`,`), for example: `--target=target_1,target_2`. +(Do not add spaces around the comma characters. Always use equal-to characters [`=`] as shown in the example.) diff --git a/docs/adoc/backup.adoc b/docs/adoc/backup.adoc new file mode 100644 index 00000000..beabbbda --- /dev/null +++ b/docs/adoc/backup.adoc @@ -0,0 +1,48 @@ +include::1-attribute.adoc[] + +[#backup] +# Backing up {ds2} data + +{ds2} itself has no built-in backup functionality. +Neither for the configuration nor for its configuration or its document metadata store. + +You need make sure to back up all relevant data yourself. + + +[#maintain-backup-config] +## Maintaining, backing up, and restoring configuration files + +To maintain and back up configuration, create a Git repository at `/etc/docserv/`. +To do so, run `git -C /etc/docserv/ init`. +Then add, commit, and push all content as desired. + +To restore configuration, use Git commands. +You do not need to exit or restart {ds2} to apply most configuration, as it is re-evaluated upon every build instruction. +The exception to this is restoring site configuration: In this case, make sure to exit {ds2} and restart after having restored it. + + +[#backup-metadata] +## Backing up the metadata store + +The metadata store contains metadata extracted from documents, such as document titles and subtitles. +If it is deleted, all metadata will have to be created anew. +This means, all docsets of the site have to be rebuilt which can take a substantial amount of time. +If you do not do so, navigational pages will lose links to most content after the immediate next build. + +To maintain and back up the metadata store, create a Git repository at `/var/cache/docserv/`. +To do so, run `git -C /var/cache/docserv/ init`. +Create a `.gitignore` file that ignores `.json` files on the top level of the repository to avoid backing up build queue files. +Then add, commit, and push all content as desired. + +It usually makes sense to create a cronjob or similar that automatically adds/commits/pushes all changes on a regular basis. + + +[#backup-content] +## Backing up {ds2} content + +{ds2} content is stored in the directory configured as the `backup_dir` in the site configuration for each target. +This directory can be compressed (for example with: `tar -cvf "__[BACKUP_FILE]__.tar" -C "__[BACKUP_DIR_FOR_TARGET]__" .`). +Finally, upload or copy the backup. + +To restore content, exit {ds2}, temporarily rename the `backup_dir`. +Then extract the content of the backup to `backup_dir`. diff --git a/docs/adoc/config-localization.adoc b/docs/adoc/config-localization.adoc new file mode 100644 index 00000000..b113e396 --- /dev/null +++ b/docs/adoc/config-localization.adoc @@ -0,0 +1,69 @@ +include::1-attribute.adoc[] + +[#config-localization] +# Localization + +{ds2} supports localization of the templates for navigational pages via localization files in conjunction with __Server Side Includes__ (SSI) fragments (see <>). +Use of the SSI fragment feature also necessitates use of localization files. + +All localization files must be collected in a single directory. + +There must be at least one localization file for the default UI language. +This file must contain all requested localization strings. + +Files for alternative UI languages and the strings within them are optional. +In case they are missing, the default UI language's string will be used as a fallback. + + +[#config-localization-file] +## Localization file structure + +Localization files are based on a simple file format and easy to validate. +Each file represents a single language. +Within a localization file, localization strings are uniquely identified by their __localization key__. + +Localization files must be named `__[LANGUAGE_CODE]__.xml`. +The `__[LANGUAGE_CODE]__` must use the format `la-ng` (see also <>). + +The file format of localization files looks like this: + +[source,xml,subs="+quotes"] +---- + + + + __[LOCALIZED_CONTENT]__ + + +---- + +* The `__[LANGUAGE_CODE]__` must use the format `la-ng` (see also <>). +This language code definition is purely informative, as {ds2} will pick up the language code from the file name. + +* The `__[LOCALIZATION_KEY]__` must be unique within each localization file. +The localization key uses an `xsd:ID` data type. +It must not contain spaces or a leading digit. + +* The `__[LOCALIZED_CONTENT]__` can be any content, including a limited XHTML subset. + + +[#config-localization-placeholder] +## Placeholders + +Localized content can contain the following placeholders: + +* `@{{#year#}}` within the content: +Placeholder for the current year (for example, `2022`). +This replacement is not handled by XML tools. + +* `@({{#ui_language#}}` within the content: +Placeholder for the language code of the generated fragment (in the format `la-ng`, see also <>). +This replacement is not handled by XML tools. + +* `@{{#ui_language_omissible#}}` +Placeholder for the UI language of the generated fragment, for situations where the language code is omissible in URLs (for example, __empty string__ for the default UI language or `la-ng` for alternative UI languages). +This replacement is not handled by XML tools. + +* `@{{#ui_language_omissible_slash#}}` +Placeholder for the UI language of the generated fragment with a slash appended, for situations where the language code is omissible in URLs (for example, __empty string__ for the default UI language or `la-ng/` for alternative UI languages). +This replacement is not handled by XML tools. diff --git a/docs/adoc/config-overview.adoc b/docs/adoc/config-overview.adoc new file mode 100644 index 00000000..bc7555f8 --- /dev/null +++ b/docs/adoc/config-overview.adoc @@ -0,0 +1,23 @@ +include::1-attribute.adoc[] + +[#config-overview] +# Configuration overview + +Configuration of {ds2} is split in a number of parts that are described in the following. + +* Site configuration configures the site and sync targets in itself. +For more information, see <>. + +* Product configuration configures what documentation to publish. +For more information, see <>. + +* Templates for navigational pages configure the look of the homepage and product overview pages. +For more information, see <>. + +* Localization files allow localizing the homepage and product overview pages. +For more information, see <>. + +* SSI fragments allow reusing XHTML page fragments as part of different navigational pages. +For more information, see <>. + +The order above gives a rough idea of the order and importance of each item, though you are free to work on them any other order. diff --git a/docs/adoc/config-product.adoc b/docs/adoc/config-product.adoc new file mode 100644 index 00000000..9b02bd05 --- /dev/null +++ b/docs/adoc/config-product.adoc @@ -0,0 +1,327 @@ +include::1-attribute.adoc[] + +[#config-product] +# Product configuration + +The product configuration of {ds2} is a directory of XML files that define which documents to build and which external documents to link to and where they are place within the overall structure of the site. +Each XML file from the directory defines documentation for a single product (alternatively, it may also be used as a first-level category). + +Internally, {ds2} validates and combines all configuration files into a single large file ("stitching"). +{ds2} will re-evaluate the product configuration with each new build instruction. + +A very reduced example of a product configuration file may look like this: + +[source,xml] +---- + + + Example Product + + + p.erson@doma.in + + + + + + + +

+ This product is good. +

+ + + + 1.0 + + + + main + + DC-example-admin + + + + + + + + + + + + + + + + + + +---- + +A product configuration file has the following basic components: + +* Product metadata: + +** `@productid` and ``: The product ID which is used by the API and as a URL component, and the product name which is displayed to users. + +** ``: A section defining documentation maintainers. +Email addresses referenced here receive email when a build instruction in the context of this product fails. + +** ``: Product-specific categories allow sorting documents within docset navigational pages. +In some contexts, these on-page categories may be called "third-level categories". +** ``: A generic product description. +* `` definitions: Docsets define which documents to reference within a docset navigational page. +A docset usually maps to a product version. +In some contexts, docsets may be called "second-level categories". ++ +In most cases, there are multiple docsets within a product configuration file. + +A longer, annotated example configuration file is available from link:https://github.com/openSUSE/docserv/blob/main/config/config.d/example_product.xml[GitHub]. + + +[#config-product-metadata] +## Product metadata configuration + +This document will not focus further on defining product metadata. + +//FIXME For more information about product metadata, see the annotated schema at link:FIXME[]. + + +[#config-product-docset] +## Docset configuration + +A `` collates all information needed to generate output documents and navigational pages for a specific product version (or second-level category). + +The `` element has the following basic elements: + +* Docset metadata: +** `@setid` and ``: The docset ID which is used by the API and as a URL component, and the product version which is displayed to users. +** The lifecycle attribute is set according to the support lifecycle of the product. +It defines how and in which context the docset is displayed. + +* References to documents to build and link to + +## The `@lifecycle` attribute of docsets + +The `@lifecycle` attribute is meant to map to the product lifecycle: + +* `unpublished`: Documents can only be built and published for targets marked internal and by default will carry a _DRAFT_ watermark. + +* `beta`: Documents can be built and published for any target and will carry a _DRAFT_ watermark. + +* `supported`: Documents can be built and published for any target and will not carry a _DRAFT_ watermark by default. + +* `unsupported`: Documents can be built and published for any target and will not carry a _DRAFT_ watermark by default. However, they will only be published within a single ZIP file, making them non-indexable for search engines. This also reduces visibility in the navigational pages, as documents will only be shown under Deprecated documents header. + + +[#config-product-reference] +## Document references in docsets + +`` elements allow different types of document references, each defined within an own element: + +* ``: DAPS-compatible DocBook and AsciiDoc Documents that {ds2} can build itself. +{ds2} will define the publishing URL and extract metadata such as the document title from these documents during the build process. +{ds2} will automatically create ZIP archives of these documents. ++ +However, to update the navigational pages for such documents, the documents need to remain buildable within {ds2}, even if the product is no longer supported. +* ``: References to {ds2} navigational pages or documents defined elsewhere in the product configuration. +{ds2} will extract the URL and metadata such as the document title from their original context in the product configuration. + +* ``: References to documents created outside of {ds2}. +Such documents can be located anywhere on the internet. +They can also be located on the same host as {ds2}-created documents, placed in such a way that they do not interfere with the directory structure created by {ds2}. +URLs and document titles of such documents must be defined manually. +{ds2} cannot prevent link breakage or similar issues for these documents. + +[IMPORTANT] +.No page dependency management +==== +Docset navigational pages can only be rebuilt individually. + +Internal links can become outdated when the original document is reconfigured but the docset containing the internal reference is not specifically rebuilt after the change. +Make sure to rebuild dependent docsets manually. +==== + + +[#config-product-build] +### Documents generated with {ds2}, `` + +References within `` are references to documents that are generated within Docserv² for that product version. +Documents can only be generated via {ds2} if they fulfull both of the following requirements: + +* DAPS-compatible {db} or {ad} documents. + +* Hosted in a Git repository which the {ds2} build server can unauthenticated read access. + +Such documents can be configured for multiple output formats and languages. + +The primary ordering principle for documents within `` is by language. +The listing of documents available in the default language (``) must come first. + +After the listing of documents available in the default language, you can set up translation languages (``). +The document listing from the default language will be used as the reference for all other languages, indirectly promoting consistency within the source documentation repositories. +In translation languages, you cannot define additional documents—the set of translated documents must be a subset of the documents that exist in the primary language. + +The default language is defined per docset only. +If necessary, it can be different for each docset. + +Within the `` section, you must define a Git source repository using the `` element. +Use the HTTPS-based remote address to configure Git source repositories. + +This Git repository must contain all documents to generate in this product context. +However, documents in different languages can use different branches and subdirectories of the Git source repository. +To present documents from multiple Git repositories as part of the same product context, include the documents from the secondary repository using internal references. + +For DocBook set documents and similar collection documents, you can add `` elements to link to a specific ID within the set. + +Each `` element defines `` elements, that is, output documents. +Choose which formats to enable for which document using the ``. + +Subsequent `` elements, that is, references to translations can use two modes: + +* `@translation-type="full"`: All documents available in the default language will also be generated for the translation. + +* `@translation-type="list"`: Use `` elements to select those documents from the default language which have a translation. +Within a `` element of a non-default `` element, the number of elements available is restricted to `` and ``, other parameters will be + + +[#config-product-external-reference] +### References to documents not generated within {ds2}, `` + +The `` element collects links to documents that are not generated using {ds2}. +{ds2} makes no effort to ensure availability of such documents, meaning all links to them must be checked manually. +Such documents can be co-hosted along with {ds2} or be on another host altogether. + +For each required document, add a `` element to the `` element. +A `` can reference documents in multiple formats and multiple languages. +The primary language (``) must be listed first. + + +[#config-product-internal-reference] +### {ds2}-internal references, `` + +Within the `` element, reference documents already defined elsewhere in the {ds2} configuration. +Document references (using the `` element) will inherit all properties of the original document, such as available formats and languages and reduce duplication. +You can also reference related product pages within this element. + +References identify the document using the product ID, docset ID, and DC file/link ID. + +A `` can have the following structures: + +* A reference to the default docset of a product: `` + +* A reference to a specific docset of a product: `` + +* A reference to a specific DC definition within ``: `` + +* A reference to a specific DC definition that has subdeliverables within ``: `` + +* A reference to a specific external link: `` +The value for `__[LINK_ID]__` has to be specifically set on the corresponding `` element by adding the attribute ``. `__[NAME_OF_ID]__ must be unique within the current `` and may consist of alphanumeric characters and the characters `_-.`. + +In addition, elements can have a category attribute which categorizes them on the target page. + + +[#config-product-identifier] +## Identifying elements and URL generation + +{ds2} product configuration uses a number of independent identifier systems and values other values that must be unique in a certain context: + +* `` identifies the product and is used as a path component for that product's documents. +This identifier must be unique across all product configuration files. + +* `` identifies the product version and is used as a path component for that product version's documents. +This identifier must be unique within the context of each product configuration file. + +* `` identifies categories that are used to sort documents on docset navigational pages and can appear as an ID in HTML documents. +This identifier must be unique within the contextof a product configuration file. + +* Language names (`@lang` attributes) are checked for uniqueness within the context of their parent element. +For example, there must only be a single US English (`en-us`) product description (``) for a product/first-level category (``). +Likewise, within a `` section, the `@lang` attributes' values of `` elements must be unique. + +* DC file names (`` attributes) must be unique within the `` that contains them. +After removing the `DC-` prefix, DC file names are used as path components. +These identifiers can be used for `` references to generated documents. +* `` is an optional identifier for `` links. +These identifiers can be used for `` references to such links. + +* URLs referenced within external links (``) elements must be unique within the context of the docset they are used in. + + +[#config-product-createconfig-tool] +## Generating configuration for a product with `docserv-createconfig` + +To add a new product, you can use the tool `*docserv-createconfig*` +This tool works well to create draft configuration files for repositories that follow the following conventions: + +* The main branch is called `master`. +* Maintenance branches for previous product versions are named `maintenance/__[PRODUCT_VERSION]__`. +* Translations for documents are available in branches named `trans/__[PRODUCT_VERSION]__`. + +* DC files for documents in the primary language are kept in the root directory of the repository. + +* A DC file named with its name ending in -all references a set of books and articles. + +Its usefulness degrades the fewer of these conventions are implemented in the Git source repository. + +To add a new product, proceed as follows: + +. Install {ds2} locally or clone the {ds2} Git repository and create a developer setup. + +. Clone the product documentation repository that you want to create a configuration file for. +Make sure this repository has no uncommitted changes in it. +The tool used in the following steps needs to be able to change branches freely. + +. On the command line, navigate to your product configuration directory. + +. Run `docserv-createconfig __[PATH_TO_REPO_CLONE]__` + +. Follow the instructions. + +. `docserv-createconfig` will output the file name of the generated file at the end. +Open this file and make any necessary finishing touches, such as removing unnecessary branches and setting up document translations and external links. + + +[#config-product-remove] +## Removing documents + +* To remove an entire product definition, remove the corresponding XML file from the product configuration directory +* To remove a docset, a language, or a deliverable element, remove the corresponding elements from the appropriate XML file. + +[IMPORTANT] +.Output documents removed from the configuration are not deleted automatically in all cases +==== +{ds2} will remove individual documents that have been removed from the product configuration with the next successful rebuild of the respective docset. +However, when an entire docset or product definition is removed from the product configuration, {ds2} will not automatically remove associated content. +{ds2} will no longer link to such content from the homepage. + +To remove such content from the site entirely, delete it from the `backup_dir` for the target that is defined in the site configuration. +The relevant directories are: + +* The content within each language-specific directory (`la-ng/`, <>) for the respective product or docset. + +* The metadata stored in `docserv/data` for the respective product or docset. +==== + + +[#config-product-html] +## Supported HTML subset + +Certain elements in the schema support the use of a restricted XHTML subset. +Notably, the `` element for product descriptions and `` descriptions support XHTML. +Because your XHTML is nested within a XML document, it must also be valid XML. +It must not use SGML-only structures, such as unclosed tags. +You cannot use SGML-style short tags such as `
`, instead use an XML-style self-closing tag, `
`. +Validation of XHTML structures is otherwise minimal, ensuring flexibility. + +The following XHTML elements are allowed: + +* Block elements: `

` (a paragraph), `

` (a generic block), `
` (preformatted text), `