Skip to content

Latest commit

 

History

History
107 lines (69 loc) · 3.21 KB

DOCUMENTATION.md

File metadata and controls

107 lines (69 loc) · 3.21 KB
Raw

Armbian Documentation

Create offline documentation to release

logo

Overview

Documentation is written in markdown and stored in the docs/ subfolder. Images go in docs/images.

This repo is meant for storing and quick glances. Official output is https://docs.armbian.com.

Armbian Documentation is available in the following formats:

Contributing

This site is built with mkdocs and depends on mkdocs-material.

Armbian Documentation naming of document files follows this rules:

[Parent-Topic-Example]_[Child-Topic]-example.md

Parent-Topic-Name and Child-Topic-Name are separated by an underscore _. Hyphens - are automatically converted to space.

Please try to avoid creating new parent topics unless absolutely necessary.

Current Parent Topics:

  • User Guide
  • Hardware notes
  • Developer Guide
  • Contributor Process
  • Release management
  • Community

See the document template before you writing any content.

Working on the content

Prerequisites

Ensure you have Python and the necessary development packages installed:

sudo apt-get update
sudo apt-get install python3 python3-pip python3-venv python3.11-dev

If using Debian, you may need to install the following packages for mkdocs-material:

sudo apt-get install libcairo2 pango1.0-tools

Cloning the Repository

Next, clone the Armbian documentation repository:

git clone https://github.com/armbian/documentation
cd documentation

Setting Up the Environment

Set up a Python virtual environment to isolate the project dependencies:

python3 -m venv .venv
source .venv/bin/activate
pip install --use-pep517 -r requirements.txt

Building and Serving the Documentation

To build and serve the documentation locally, allowing you to make edits and observe the results in real time, use:

mkdocs build --clean
mkdocs serve -a 0.0.0.0:8000

You will be able to make edits to existing files and observe the results in real time.

Generate tools

After adding a new file, either hand-edit mkdocs.yml, or re-run tools/mkArmbianDocs.py unless making changes to the structure of the docs/ folder. (See below)

mkArmbianDocs.py

Generate mkdocs.yml based on the contents of docs/ folder

  • Command-line options for input and output directories
  • Requires install requirement
  • You don't need to run it every time unless making changes to the structure of the docs/ folder
  • See mkArmbianDocs.py -h for help

From the parent folder of the repo, run:

python3 tools/mkArmbianDocs.py && mkdocs build

This will generate the mkdocs.yml and publish built HTML to the site/ folder.