From ce83411b44ffce77e57fb1b834c6008f4222a3fe Mon Sep 17 00:00:00 2001 From: xengineering Date: Thu, 4 Jan 2024 22:05:39 +0100 Subject: doc: Write section 'Versioning' This section is important to communicate how to interpret version numbers in the context of this device repository. --- README.md | 1 + doc/diagrams/device-semver.svg | 223 +++++++++++++++++++++++++++++++++++++++++ doc/doc.mk | 14 ++- doc/documentation.tex | 31 +++++- 4 files changed, 265 insertions(+), 4 deletions(-) create mode 100644 doc/diagrams/device-semver.svg diff --git a/README.md b/README.md index 54efd20..8b83ec3 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,7 @@ required: - GNU coreutils - GNU make - pdflatex +- Inkscape - OpenSCAD - Prusa Slicer diff --git a/doc/diagrams/device-semver.svg b/doc/diagrams/device-semver.svg new file mode 100644 index 0000000..8a68362 --- /dev/null +++ b/doc/diagrams/device-semver.svg @@ -0,0 +1,223 @@ + + + + + + + + + + Mechanicalparts + + Electronicparts + + Firmware + + Software + + + Device + + + + + + + User + 'API' as defined bySemantic Versioning + + + diff --git a/doc/doc.mk b/doc/doc.mk index 8c56847..351cd48 100644 --- a/doc/doc.mk +++ b/doc/doc.mk @@ -1,11 +1,19 @@ DOC_BUILD_DIR := $(BUILD_DIR)/doc DOCS := documentation -PDF := $(DOCS:%=$(DOC_BUILD_DIR)/%.pdf) +DOCUMENTS := $(DOCS:%=$(DOC_BUILD_DIR)/%.pdf) + +DIAGRAMS_BUILD_DIR := $(DOC_BUILD_DIR)/diagrams +DIAGRAMS := device-semver +IMAGES := $(DIAGRAMS:%=$(DIAGRAMS_BUILD_DIR)/%.pdf) .PHONY: doc -doc: $(PDF) +doc: $(DOCUMENTS) -$(BUILD_DIR)/%.pdf: %.tex +$(DOC_BUILD_DIR)/%.pdf: doc/%.tex $(IMAGES) mkdir -p $(dir $@) pdflatex -halt-on-error -output-directory $(DOC_BUILD_DIR) $< pdflatex -halt-on-error -output-directory $(DOC_BUILD_DIR) $< + +$(DIAGRAMS_BUILD_DIR)/%.pdf: doc/diagrams/%.svg + mkdir -p $(dir $@) + inkscape -o $@ $< diff --git a/doc/documentation.tex b/doc/documentation.tex index 14cf828..f7c0fee 100644 --- a/doc/documentation.tex +++ b/doc/documentation.tex @@ -2,6 +2,12 @@ \author{xengineering} \title{soundbox documentation} +\usepackage{graphicx} +\graphicspath{ {./diagrams/} } +\usepackage{hyperref} + +\setlength\parindent{0pt} + \begin{document} \maketitle @@ -10,11 +16,34 @@ \tableofcontents \newpage +\listoffigures +\newpage + \chapter{Introduction} \texttt{soundbox} is a device to connect classic audio systems to the network. -%\section{Versioning} +\section{Versioning} + +This device is versioned with Semantic +Versioning\footnote{\href{https://semver.org}{https://semver.org}}. The +resulting version numbers have the format \texttt{..} like +e.g. \texttt{2.0.3}. While Semantic Versioning is usually targeted at software +only it is here used for the whole device. This includes mechanical, electronic +and software aspects as shown in figure \ref{diagram:device-semver}. + +\begin{figure}[h] + \centering + \includegraphics[width=\textwidth]{device-semver.pdf} + \caption{API for a device versioned with Semantic Versioning} + \label{diagram:device-semver} +\end{figure} + +This versioning makes sure that users do not have to care about the device +internals at all. Devices can be seen as atomic from a user's perspective. This +level of granularity is choosen because users are not expected to disassemble +devices or to care about the software internals. + %\section{Licensing} %\chapter{User guide} -- cgit v1.2.3-70-g09d2