About

This repository stores the source of the OTOBO Administration Manual.

The content of the documentation is in reStructuredText format and uses Sphinx to generate HTML, PDF and EPUB outputs. The various outputs can be seen on the OTOBO Documentation page.

🛠 Local Preview and Development

To verify changes to the documentation before submitting them, you can generate a local HTML preview. This helps identify syntax errors in ReStructuredText (RST) or layout issues early in the process.

Clone the repository

git clone https://github.com/RotherOSS/doc-otobo-admin.git
cd doc-otobo-admin

Prerequisites

• Python 3.10+
• make (standard on Linux/macOS; for Windows use MinGW or WSL)

Quick Start

1. Create a Virtual Environment (Recommended) To keep your system clean, create an isolated environment:

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

2. Install Dependencies Install Sphinx and the required themes/plugins directly from the repository:

pip install -r requirements.txt

3. Generate HTML Use the provided Makefile for the build:

make html

Viewing the Result

Once the build is complete, you will find the generated files in the _build/html/ directory. Open the index.html file in your browser:

# Example for Linux/macOS
open _build/html/content/index.html

NOTE: This local build uses default settings (e.g., version "dev"). Final versioning, branding, and language validation are performed automatically by the OTOBO CI Pipeline as soon as changes are pushed to the repository.

Contribution

Contribution to documentation is very welcomed. You can add new pages or edit the existing text.

To edit the documentation:

• Learn how to work with reStructureText (see help).
• Fork the repository (see help).
• Add your modifications to the documentation.
• Create a pull request (see help).

Translation

Translators should use Weblate to translate the documentation. As the documentation is in reStructuredText format, be careful not to break the structure while translating the documentation. See the examples in the Translating section of the developer documentation.

Report Bugs

If you find any kind of bugs in the documentation like typos, wrong information, dead links, etc., please create a bug report on Github issue tracker.

License

The documentation is distributed under the GNU Free Documentation License - see the accompanying COPYING file for more details.