# docserv

**Repository Path**: mirrors_openSUSE/docserv

## Basic Information

- **Project Name**: docserv
- **Description**: A server for building and publishing documentation with DAPS 
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-08-18
- **Last Updated**: 2026-04-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

:ds2: Docserv²
:db: DocBook
:ad: AsciiDoc
:daps: DAPS

# {ds2}

{ds2} 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 {db}/{ad} 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 {ds2} 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 {ds2}

RPM builds are available in the openSUSE Build Service in the link:https://build.opensuse.org/project/show/Documentation:Tools[`Documentation:Tools` repository].


### openSUSE Leap

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

. `zypper in docserv`


## Dependencies

{ds2} 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 {ds2} from the Git repository

To use {ds2}, make sure that the dependencies listed above are installed. It's recommended to use a VM for the development environment.

### Preparing the system

. Make sure the Docker service is running: `systemctl start docker`
  (To run {ds2} as a regular user, make sure your user is part of the group `docker`.)

. 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

. `cd` to the local repository checkout

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

. Source the `dev-mode.sh` script:

    $ source dev-mode.sh

. 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

. Create a virtual environment with Python:

    $ python3 -m venv .venv

. Activate the virtual environment:

    $ source .venv/bin/activate

. Update the pip Python package manager:

    $ pip3 install -U pip setuptools

. Install requirements via pip:

    $ pip3 install -r requirements.txt

. Install {ds2} with setuptools in develop mode:

    $ python3 setup.py develop


## Scripts delivered as part of {ds2}

Parts of {ds2} 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 {ds2} product configuration and merge it into a single big XML file (see `--help`).

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