Warning, /documentation/digikam-doc/README.md is written in an unsupported language. File is not indexed.
0001  This repository hosts the digiKam handbook based on [Sphinx](https://www.sphinx-doc.org) framework and [ReStructuredText](https://docutils.sourceforge.io/rst.html) format. 0002 0003 [digiKam](https://www.digikam.org/about/features/) is a powerful Open Source Photo Management Software. 0004 0005 This documentation generated as **HTML** can be read online [here](https://docs.digikam.org/en/index.html). 0006 0007 This documentation generated as **EPUB** can be downloaded [here](https://docs.digikam.org/en/epub/DigikamManual.epub). 0008 0009 [](https://binary-factory.kde.org/job/Website_docs-digikam-org/) 0010 0011 ## Setting Up Development Environment 0012 0013 Under Ubuntu 22.04 and later: 0014 0015 1. To install Sphinx and the Sphinx Theme use `sudo apt install python3-sphinx python3-sphinx-rtd-theme` 0016 2. You can check whether Sphinx was installed successfully by running `sphinx-build --version` 0017 0018 ## Running Sphinx on Your Computer 0019 0020 After you cloned this repository (only need to be done once), use a command line to go to its root folder (e.g. with `cd /path/to/digikam-docs`) 0021 0022 ### Generate an HTML Web Documentation 0023 0024 Under **Linux:** run `make html` 0025 0026 The HTML is generated in `build/html`. Open the file `index.html` in your preferred web browser. It must look like this: 0027 0028 [](project/images/handbook_HTML.webp) 0029 0030 ### Generate an EPUB E-book 0031 0032 Under **Linux:** run `make epub` 0033 0034 The EPUB ebook is generated in `build/epub`. Open the file `DigikamManual.epub` in your preferred e-book reader. It must look like this: 0035 0036 [](project/images/handbook_EPUB.webp) 0037 0038 ## Directories Hierarchy 0039 0040 - [LICENSES](LICENSES) : all licenses used in the project. 0041 - build : temporary dir created when documentation is compiled. 0042 - [locale](locale) : link to updated handbook translations files. Files are updated all nights. 0043 - po : Obsolete, not used. Replaced by locale directory. 0044 - [project](project) : some helpers scripts and LibreOffice schemes. 0045 - [ressources](ressources): Sphinx templates customization. 0046 - [tests](tests) : scripts to test repository contents with Continuous integration. 0047 0048 All others directories are used to host sections of the documentation implemented in ReStructuredText format. 0049 0050 ## Get Involved 0051 0052 ### File Hierarchies 0053 0054 ReStructuredText documentation implementation is located in top level directory in .rst files and sub-directories with the same name 0055 corresponding to the handbook sections. The root entry of the manual is [index.rst](index.rst). 0056 0057 Each handbook section start with a .rst file from top level directory and a dedicated 0058 sub-directory with the same name including chapters .rst files, a nested **images** sub-directory to host 0059 screen-shots, taken in WEBP format, and a nested **videos** sub-directory to host screen-casts in animated WEBP format. 0060 0061 For example, the **getting_started** section will be organized like this: 0062 0063 ``` 0064 ├── index.rst 0065 ├── getting_started.rst 0066 └── getting_started 0067 ├── images 0068 │ ├── firstrun_step1.webp 0069 │ ├── firstrun_step2.webp 0070 │ ├── firstrun_step3.webp 0071 │ ├── firstrun_step4.webp 0072 │ ├── firstrun_step5.webp 0073 │ ├── firstrun_step6.webp 0074 │ ├── firstrun_step7.webp 0075 │ ├── firstrun_step8.webp 0076 │ ├── firstrun_step9.webp 0077 │ ├── macos_pkg_installer.webp 0078 │ ├── macos_pkg_security.webp 0079 │ ├── macos_pkg_warning.webp 0080 │ ├── models_downloader.webp 0081 │ ├── scan_progress.webp 0082 │ └── tools_interface.webp 0083 ├── installation.rst 0084 ├── introduction.rst 0085 ├── quick_start.rst 0086 └── videos 0087 └── appimage_startup.webp 0088 0089 ``` 0090 0091 **getting_started.rst** is the root entry of the **Geting Started** section of this manual. 0092 All others nested **.rst** files hosted in **getting_started** sub-directory are chapters in this section. 0093 0094 ### ReStructuredText Sections/Chapters/References Implementation 0095 0096 As example, we will develop how the **getting_started** section of the manual is implemented. 0097 0098 - From the top level **index.rst**, the section is declared like this: 0099 0100 ``` 0101 Implementation Comments 0102 0103 ... Other previous sections are there 0104 0105 ############### 0106 Getting started Section title declared on the front page 0107 ############### 0108 .. figure:: images/index_getting_started.webp Visual preview of the section 0109 :width: 300px Limit preview size 0110 :alt: No alternative description 0111 :target: getting_started.html Preview link on the documentation 0112 0113 .. container:: toctile Chapter from the section will be hosted in a container 0114 0115 .. container:: tile no-descr A sub-container for a chapter 0116 0117 :ref:`application_intro` Link to the 1st chapter 0118 0119 .. container:: tile no-descr 0120 0121 :ref:`application_install` Link to the 2nd chapter 0122 0123 .. container:: tile no-descr 0124 0125 :ref:`quick_start` Link to the 3rd chapter 0126 0127 .. container:: tile no-descr 0128 0129 :ref:`database_intro` Link to the last chapter 0130 0131 .. toctree:: 0132 :maxdepth: 2 We will descend to the 2 level from nested hierarchy 0133 :hidden: 0134 0135 getting_started The name of the rst file implementing the section 0136 0137 ... Other next sections are there 0138 ``` 0139 0140 Next file is the **getting_started.rst** listing all chapters from the section: 0141 0142 ``` 0143 Implementation Comments 0144 0145 .. meta:: The metadata section of the document 0146 :description: Do Your First Steps in digiKam Photo Management Program Some words to describe the section 0147 :keywords: digiKam, documentation, user manual, photo management, open source, free, help, learn Words list used with the search engine 0148 0149 .. metadata-placeholder The license/credit lists (same for all rst files) 0150 0151 :authors: - digiKam Team 0152 0153 :license: see Credits and License page for details (https://docs.digikam.org/en/credits_license.html) 0154 0155 .. _getting_started: Internal reference for this section 0156 0157 ############### 0158 Getting started Section title 0159 ############### 0160 0161 This section give an overview to start with digiKam. A small description visible on the page 0162 0163 .. toctree:: List of chapters in this section 0164 :maxdepth: 2 0165 :caption: Contents: 0166 :glob: 0167 0168 getting_started/introduction.rst Rst files hierarchy ordered. 0169 getting_started/installation.rst 0170 getting_started/quick_start.rst 0171 getting_started/database_intro.rst 0172 ``` 0173 0174 And finally, the chapter implementation of the section, here the first one, as all others uses the same kind of code: 0175 0176 ``` 0177 Implementation Comments 0178 0179 .. meta:: The metadata section of the document 0180 :description: Introduction to digiKam Photo Management Program Some words to describe the chapter 0181 :keywords: digiKam, documentation, user manual, photo management, open source, free, learn, easy Words list used with the search engine 0182 0183 .. metadata-placeholder The license/credit lists (same for all rst files) 0184 0185 :authors: - digiKam Team 0186 0187 :license: see Credits and License page for details (https://docs.digikam.org/en/credits_license.html) 0188 0189 .. _application_intro: Internal reference for this chapter 0190 0191 Introduction Chapter title 0192 ============ 0193 0194 .. contents:: 0195 0196 Background First sub title of this chapter 0197 ---------- 0198 0199 ... The implementation continue here... 0200 ``` 0201 0202 ### Sphinx Framework 0203 0204 The Python based Sphinx documentation generator translates a set of reStructuredText source files into various output formats, automatically producing cross-references, indices etc. It just used at run-time with the **make html** command to render contents, and reports warnings and errors. 0205 0206 Documentation writer will never touch the Sphinx configuration. 0207 0208 ### The ReStructuredText Format 0209 0210 ReStructuredText is a simple file format for textual data used primarily in the Python programming language 0211 community for technical documentations. It can be edited with a Text Editor application as powerful 0212 [Kate](https://kate-editor.org/) featuring syntax highlighting and spellchecking to help documentation writers. 0213 0214 ReStructuredText is part of the [DocUtils project](https://docutils.sourceforge.io/) from the Python Documentation Special Interest Group, 0215 aimed at creating a set of tools for Python. DocUtils can extract comments and information from ReStructuredText, 0216 and format them into various forms of program documentation. 0217 0218 ReStructuredText is a lightweight markup language designed to be both processable by documentation-processing 0219 software such as DocUtils, and easily readable by human who are reading and writing source code. 0220 0221 Take care that ReStructuredText file (.rst) specificity: 0222 0223 - It's an indent featured markup language. Respect well the spaces on front of blocks to prevent compilation warnings. 0224 - Indent must be done with **4 spaces**, never use tabs at all. 0225 - Always save ResStructuredText file using **UNIX end-of-line**, Check your editor settings before. 0226 - Never use space or minus in file name, uses underscore instead. 0227 - Never uses capitalized forms in filenames, always uses lowercase characters. 0228 0229 A good place to learn **ReStructuredText** format used in this documentation, it's recommended to read: 0230 0231 - [Quick-start](https://docutils.sourceforge.io/docs/user/rst/quickstart.html). 0232 - [Cheat-sheet](http://docutils.sourceforge.net/docs/user/rst/cheatsheet.txt). 0233 - [Reference](http://docutils.sourceforge.net/docs/user/rst/quickref.html). 0234 - [Markup Languages Synthesis](https://hyperpolyglot.org/lightweight-markup). 0235 0236 [This StackOverflow entry](https://stackoverflow.com/questions/2746692/restructuredtext-tool-support) list the tools available to work with ResStructuredText files. 0237 0238 ### ReStructuredText Syntax Reminders 0239 0240 Type | Syntax 0241 -------------------------------------|------------------------------------------------------------------------------ 0242 Menu Entry | ``` :menuselection:`View --> Sort Albums --> By Category` ``` 0243 Keyboard Shortcut | ``` :kbd:`CTRL + w` ``` 0244 Internal Reference Definition | ``` .. _album_view: ``` 0245 Link to Internal reference | ``` :ref:`the Album section <albums_view>` ``` 0246 Link to External Url | ``` `digiKam Home Page <https://www.digikam.org/>`_ ``` 0247 Italic Text | ``` *Cancel button* ``` 0248 Bold Text | ``` **Ok button** ``` 0249 File Name | ``` :file:`recogintion.db` ``` 0250 Raw Text Section (as console output) | ``` .. code-block:: text ``` 0251 Inline Icon Declaration | ``` .. \|icon_fullscreen\| image:: images/mainwindow_icon_fullscreen.webp ``` 0252 Inline Icon Usage | ``` \|icon_fullscreen\| ``` 0253 GUI Elements (button, label, title) | ``` :guilabel:`Start Encoding...` ``` 0254 Section Title Level 1 | ``` ============ ``` 0255 Section Title Level 2 | ``` ------------ ``` 0256 Section Title Level 3 | ``` ~~~~~~~~~~~~ ``` 0257 0258 Table example: 0259 ``` 0260 ============== ========== ======= 0261 Title 1 Title 2 Title 3 0262 ============== ========== ======= 0263 Item 1 Value 1 Value 2 0264 Item 2 Value 1 Value 2 0265 Item 3 Value 1 Value 2 0266 Item 4 Value 1 Value 2 0267 Item 5 Value 1 Value 2 0268 ============== ========== ======= 0269 ``` 0270 Nested list 0271 ``` 0272 - Level 1 0273 0274 - Level 2 0275 - Level 2 0276 0277 - Level 1 0278 0279 - Level 2 0280 - Level 2 0281 - Level 2 0282 - Level 2 0283 ``` 0284 0285 ### Contribute Workflow 0286 0287 To help us to write this English documentation, you must use a standard git workflow based on the Fork/Merge Request mechanism. 0288 You will not have direct access to this repository. 0289 All new contributors must process as below: 0290 0291 - Create an account at [KDE identity](https://identity.kde.org/). 0292 - Be logged with this account to [KDE git server](https://invent.kde.org/users/sign_in). 0293 - [Fork this project](https://invent.kde.org/documentation/digikam-doc/-/forks/new) to your account. 0294 0295 All contributor changes must be performed in this forked repository. Contributors can use the web interface to edit 0296 existing files or to clone the repository on a computer to process advanced operations such as to create new contents. 0297 At the end, the contributor commits the new files in the forked repository. 0298 0299 When all contributor tasks are done, a Merge Request must be send to the original (Central) project to: 0300 0301 - Notify the coordinator about the contribution. 0302 - Coordinator will review the changes. 0303 - Coordinator can post comments in the Merge Request if something is wrong (aka ReStructuredText compilation fails with the Continuous Integration). 0304 - Contributor must adjust, comment, or rebase changes in the forked repository accordingly with coordinator feedback. 0305 - When all is ready, coordinator merge changes from the forked repository to the original repository. 0306 0307 Later, a contributor can re-use the forked repository to re-base contents with original repository. The forked repository 0308 will be up-to-date and the contributor can create a new Merge Request with the new changes to integrate in the original repository. 0309 0310 To have the forked repository sync with the original 'origin' upstream, uses this git command in your fork: 0311 0312 `git fetch origin` 0313 0314 To rebase your fork just call this git command: 0315 0316 `git merge origin/master` 0317 0318 This git workflow is well [documented in this page](https://www.johneverettcase.com/post/2021/07/28/git-rebase-fork.html). 0319 0320 ### WEBP Screenshot Capture 0321 0322 - Always use digiKam AppImage version 8 and later under Linux/Plasma desktop to take screenshots. 0323 0324 - Always use **White Balance** color theme to take screenshots. Select theme from **Settings/Themes** menu. 0325 0326 - Always use **Breeze** widget style and icon theme. Select widget/icon theme from **Setup/Miscs/Appearance** configuration dialog page. 0327 0328 - No face/people present as possible in photo hosted in screenshots. 0329 0330 - No digiKam version number must be present in screenshots. 0331 0332 - Desktop and application must be in English only. Do not mix languages. 0333 0334 - Use a tool as [Spectacle](https://apps.kde.org/spectacle/) to take a shot. Use the region selection option to capture only important area. 0335 0336 - Remove unnecessary buttons and dialog header to limit image file size. 0337 0338 - Always use **WEBP** file format to save images. 0339 0340 - Do not use space and capitalized characters in file name. 0341 0342 - WEBP files must be hosted in **images/** sub-folders from each documentation section. 0343 0344 - To include the screenshot in a ReStructuredText file, use the syntax below; 0345 0346 ``` 0347 .. figure:: images/my_screen_shot.webp 0348 :alt: 0349 :align: center 0350 0351 My Screenshot Legend 0352 ``` 0353 0354 ### Animated WEBP Screen-cast Capture 0355 0356 Another format supported inside the documentation is **Animated WEBP** as video. It can be used to present a region of screen 0357 from the application while an operation is under progress. It's perfect to write tutorials. 0358 0359 Use the same specifications to take screen-cast than for screenshot, aka color theme, widget style, icon theme, etc. 0360 0361 To prevent huge animated WEBP files, just capture the right area from application and limit capture to less than 10 seconds. 0362 You can edit animated WEBP in [The Gimp](https://www.gimp.org/) to reduce size and specify **video in loop** feature. 0363 0364 A good tool to capture video from desktop is [SimpleScreenRecorder](https://www.maartenbaert.be/simplescreenrecorder/). 0365 0366 Configuration: 0367 0368 - Container : WEBM. 0369 - Codec : VP8. 0370 - Bitrate: 5000 kbit/s. 0371 - Record cursor. 0372 0373 Do not use space and capitalized characters in file name. 0374 0375 This will record a screen-cast in WEBM format. Even if WEBM is supported in HTML and EPUB, 0376 Sphinx framework is not yet able to embed WEBM in EPUB. 0377 Convert it to animated WEBP using [project/webm2webp.sh](project/webm2webp.sh) script. 0378 0379 Loop animated WEBP files must be hosted in **videos/** sub-folders from each documentation section. 0380 0381 - To include the screen-cast in a ReStructuredText file, use the syntax below: 0382 0383 ``` 0384 .. figure:: videos/my_screen_cast.webp 0385 :width: 600px 0386 :alt: 0387 :align: center 0388 0389 My Screen-cast Legend 0390 ``` 0391 0392 ### Translations 0393 0394 #### Overview 0395 0396 The documentations are internationalized by KDE translator teams. In this repository, only the native **American English (United States)** version is maintained and text is written in ReStructuredText containers. These files are daily parsed by maintenance scripts to extract strings and exported to dedicated containers for translators. 0397 0398 In the background, a [top level script](https://invent.kde.org/sysadmin/l10n-scripty/-/blob/master/process-static-messages.sh) from **l10n-scripty** repository call **StaticMessages.sh** script from this repository. 0399 0400 When translations are updated by the translator teams, files are send back by other maintenance scripts to this project, 0401 in goal to compile internationalized versions of ReStructuredText files. These files are linked in [locale/](locale) sub-directories 0402 from this project for conversion to HTML/EPUB. 0403 0404 This project is not involved in the translations workflow. Please contact [KDE translation teams](https://l10n.kde.org/docs/index-script.php) 0405 if you want to contribute to the internationalization. 0406 0407 The template files to translate for this documentation must be located on [this i10n Subversion repository](https://websvn.kde.org/trunk/l10n-kf5/templates/messages/digikam-doc/). 0408 All POT file-names starts with **docs_digikam_org** prefix. 0409 0410 The status of the digiKam documentation translations is [available here](https://l10n.kde.org/stats/gui/trunk-kf5/package/digikam-doc/). 0411 0412 Important: Only files listed as **Reviewed** in [TODO](TODO) list are ready for translations. 0413 0414 #### How to Add a New Target Language 0415 0416 The list of current enabled translation languages are in the [locale/](locale) sub-directory. 0417 Corresponding languages must be enabled in the documentation web-site following this list. 4 files needs to be patched: 0418 0419 - The **alllang** list from the [version_switch JavaScript file](resources/static/js/version_switch.js) located at **resources/static/js/** from this git repository. 0420 - The **supported_languages** list from the [404handler PHP file](404handler.php) located at root from this git repository. 0421 - The **script** section from [gitlab CI Yaml config file](.gitlab-ci.yml) located at root from this git repository, where a new line must be add to generate the supported language in the Continuous Integration workflow. 0422 - The section named **docs-digikam-org** from the [custom-jobs Json infrastrusture configuration](https://invent.kde.org/sysadmin/binary-factory-tooling/-/blob/master/staticweb/custom-jobs.json) dedicated to rule translations. 0423 0424 #### How to Compile a Supported Language 0425 0426 By default the make command generate the English version. If you want to test an internationalized version using translations hosted from **locale** directory, 0427 use the syntax below: 0428 0429 `make -e SPHINXOPTS="-D language='fr'" html` 0430 0431 This will generate the French version of the document in HTML. Replace 'fr' by another code to build a translated version, as 'es', 'de', etc. 0432 0433 ## TODO List 0434 0435 See [TODO](TODO) file from this repository. 0436 0437 ## Continuous Integration 0438 0439 At all changes done in this repository, as commits and Merge Requests, the [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration) 0440 will recompile automatically all the contents to check the validity of the ReStructuredText files, including the current translations 0441 of the documentations. 0442 0443 The [CI/CD section](https://invent.kde.org/documentation/digikam-doc/-/pipelines) lists the history of the continuous integration pipelines. 0444 0445 ## Continous Deployement 0446 0447 This documentation is automatically updated online (including translations) at each changes passing the Continuous Integration (CI). 0448 0449 If the compilation of the internationalized versions can be completed with the Continuous Deployment workflow, 0450 you can show a translated version of this documentation by selecting a language from the left side of the publication page. 0451 0452 ## Convert EPUB to PDF 0453 0454 Sphinx allows to generate PDF using Latex engine in background, but this converter as several limitations, as the non support of WEBP format used for screenshots and screen-casts. 0455 0456 An alternative is to install [Calibre](https://calibre-ebook.com/) and to convert the EPUB target to PDF like this: 0457 0458 `ebook-convert build/epub/DigikamManual.epub build/epub/DigikamManual.pdf` 0459 0460 The PDF file is generated in `build/epub`. Open the file `DigikamManual.pdf` in your preferred PDF reader. 0461 0462 Note: unlike EPUB, PDF is only for print purpose. During conversion video screen-casts will be converted as still images, and all Internet links will be dropped. 0463 0464 ## Rationale 0465 0466 See the technical details from [this Phabricator entry](https://phabricator.kde.org/T16036) about the DocBook to Sphinx/ReStructuredText manual conversion.