Docserv²

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.

High notes:

• Supports HTML, PDF, Single-HTML, and EPUB output formats

• Support for localized documentation

• Documents created outside of Docserv² can be linked to from the navigational pages

• Output directory tree is all-static Web content

• Separation of build server and publishing server(s)

• Documentation sources are automatically synchronized from a remote Git repository

• Output documents can be rebuilt and synchronized to publishing servers using a simple API call

• Rigorous configuration format that prevents many errors etc.

Installing Docserv²

RPM builds are available in the openSUSE Build Service in the Documentation:Tools repository.

openSUSE Leap

1. zypper ar --refresh https://download.opensuse.org/repositories/Documentation:/Tools/<VERSION>/Documentation:Tools.repo (replace <VERSION> with 15.5 or anything higher)

2. zypper in docserv

Dependencies

Docserv² depends on the following software:

• Linux with systemd

• Python 3.4 or higher

• pygit2, lxml

• Docker Engine

• Bash

• xmllint, xsltproc

• xmlstarlet

• Jing (needs a JVM)

• daps2docker (from https://github.com/openSUSE/daps2docker or the openSUSE Build Service’s Documentation:Tools repository)

Running Docserv² from the Git repository

To use Docserv², make sure that the dependencies listed above are installed. It’s recommended to use a VM for the development environment.

Preparing the system

1. Make sure the Docker service is running: systemctl start docker (To run Docserv² as a regular user, make sure your user is part of the group docker.)

2. Create the user docserv and group docserv by user root:

   # getent group docserv || groupadd --system docserv
   # getent passwd docserv ||  useradd --home-dir=<DOCSERV_HOME> \
       --system --gid docserv --no-create-home --shell /bin/bash docserv
   # getent group docker || groupadd --system docker
   # usermod -aG docker docserv

Preparing the output directories

If you have already a docserv.ini config file, make sure the following sections and keys are defined and the directories exist:

• server.repo_dir and server.temp_repo_dir

• target_<TARGET>.config_dir

• target_<TARGET>.backup_path

• target_<TARGET>.server_root_files

Also make sure to assign the user and group docserv to all the above directories. All directories need to be set to mode 0644 (rwxr-xr-x).

Setting up the development environment

1. cd to the local repository checkout

2. If needed, set the variable DOCSERV_CONFIG_DIR to the correct directory. The other variables in the script are usually not needed.

3. Source the dev-mode.sh script:

   $ source dev-mode.sh

4. Make sure that the right configuration (INI) directory is chosen (defaults to the configuration directory from this repository). To set a different one, use:

   $ export DOCSERV_CONFIG_DIR=/path/to/dir

5. Create a virtual environment with Python:

   $ python3 -m venv .venv

6. Activate the virtual environment:

   $ source .venv/bin/activate

7. Update the pip Python package manager:

   $ pip3 install -U pip setuptools

8. Install requirements via pip:

   $ pip3 install -r requirements.txt

9. Install Docserv² with setuptools in develop mode:

   $ python3 setup.py develop

Scripts delivered as part of Docserv²

Parts of Docserv² that can be run individually:

• docserv: The main build scheduling script.

• docserv-dchash: Reduces a DAPS DC file to its core components and creates a hash value for comparison with related DC files.

• docserv-createconfig: Creates draft product configuration files.

• docserv-stitch: Validate the Docserv² product configuration and merge it into a single big XML file (see --help).

• docserv-build-navigation: Build navigational pages for documentation content (see --help).