Skip to content

Latest commit

 

History

History
125 lines (92 loc) · 3.58 KB

1_doc_howto.md

File metadata and controls

125 lines (92 loc) · 3.58 KB

Organization and building of documentation for Back In Time

This file describes briefly how to the several types of documentation existing for Back In Time (BIT), how they are maintained, structured and build.

Tip

Feel free to open issues or contact the maintenance team on the mailing list if this text is difficult to understand or not helpful.

Index

Overview

The project distinguish between three types of documentation:

  1. The User manual can be found at backintime.readthedocs.io and is generated using MkDocs based on simple Markdown files.
  2. The Source Code documentation is located at backintime-dev.readthedocs.io and generated from the Python source files using Sphinx (migration to PyDoctor is planned).
  3. The Maintenance and Developer documentation is a bunch of Markdown files, like the one you are reading currently.

Build & view user manual (MkDocs)

Install related dependencies:

  • mkdocs
  • mkdocs-material
  • See file CONTRIBUTING.md in this repo for a complete and up to date list of dependencies.

Live preview HTML documentation as working on it:

# Enter folder
$ cd doc/manual

# Start built-in server
$ mkdocs serve

Open 127.0.0.1:8000 in your browser. Every time the underlying markdown files are modified the server will on the fly generate new HTML.

Generate HTML files:

# Enter folder
$ cd doc/manual

# Build
$ mkdocs build

# Open result in default browser
$ xdg-open html/index.html

Build & view source code documentation (Sphinx)

See Using Sphinx to write and build documentation.

Tips and Examples

Markdown

Annotation boxes / Colored highlight boxes

> [!NOTE]  
> Highlights information that users should take into account, even when
> skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]  
> Crucial information necessary for users to succeed.

> [!WARNING]  
> Critical content demanding immediate user attention due to potential risks.

> [!CAUTION]
> Negative potential consequences of an action.

Note

Highlights information that users should take into account, even when skimming.

Tip

Optional information to help a user be more successful.

Important

Crucial information necessary for users to succeed.

Warning

Critical content demanding immediate user attention due to potential risks.

Caution

Negative potential consequences of an action.

September 2024