Merge pull request #9 from SFTtech/milo/docs-improvements

TheJJ · web-flow · commit fec67856caff · 2025-12-14T22:53:59.000+01:00
diff --git a/README.md b/README.md
@@ -3,10 +3,10 @@
 <img align="right" style="float: right; width: 25%;" src="assets/debmagic-logo.svg" alt="debmagic logo"/>
 
 Debmagic is for [Debian](https://debian.org)/[Ubuntu](https://ubuntu.com):
+
 - create packages **build instructions** in Python with `debian/rules.py`
 - tooling do perform packaging itself: **building** and **testing** in isolated container environments
 
-
 [![GitHub Actions Status](https://github.com/SFTtech/debmagic/actions/workflows/ci.yml/badge.svg)](https://github.com/SFTtech/debmagic/actions/workflows/ci.yml)
 
 > [!IMPORTANT]
@@ -21,7 +21,6 @@ Included features:
 - maintainer tools
   - `debmagic build` - isolated package building
 
-
 ## Example debian/rules.py
 
 Python `debian/rules.py` equivalent of [Ubuntu 24.04 htop](https://git.launchpad.net/ubuntu/+source/htop/tree/debian/rules?h=ubuntu/noble):
@@ -82,7 +81,7 @@ pkg.pack()
 
 To add custom functions directly usable from CLI (like custom `debian/rules` targets for maintainers):
 
-``` python
+```python
 pkg = package(...)
 
 @pkg.custom_function
@@ -94,54 +93,30 @@ pkg.pack()
 
 This function can be directly called with:
 
-``` console
+```console
 ./debian/rules.py something-custom --another-param=test 1337
 ```
-``` text
+
+```text
 you passed some_param=test another_param=1337
 ```
 
 And generates automatic help for:
-``` console
-./debian/rules.py something-custom --help
-```
-
-
-## Developing
-
-Prerequisites:
 
-- Debian >= trixie, either roll your own environment or to get started faster use the [devcontainer](https://containers.dev/)
-- Python >= 3.12
-- [UV](https://docs.astral.sh/uv/)
-
-Setup:
-
-```bash
-uv sync
-uv run pre-commit install
-```
-
-Build the documentation
-
-```bash
-# oneshot build
-uv run sphinx-build docs docs/_build
-# continous serving
-uv run sphinx-autobuild docs docs/_build
+```console
+./debian/rules.py something-custom --help
 ```
 
-
 ## Documentation
 
 To do packaging with debmagic, please **[read the documentation!](https://debmagic.readthedocs.io)**.
 
-
 ## Contributing
 
 Debmagic can always use more features and modules!
 You can also just request features or report bugs - this project is happy about your contributions!
 
+- [Contributor documentation](https://debmagic.readthedocs.io/en/latest/develop/index.html)
 - [Issue tracker](https://github.com/SFTtech/debmagic/issues)
 - [Code contributions](https://github.com/SFTtech/debmagic/pulls)
 - [Development roadmap](https://github.com/SFTtech/debmagic/projects)
@@ -152,12 +127,11 @@ To directly reach developers and other users, we have chat rooms.
 For questions, suggestions, problem support, please join and just ask!
 
 | Contact       | Where?                                                                                         |
-|---------------|------------------------------------------------------------------------------------------------|
+| ------------- | ---------------------------------------------------------------------------------------------- |
 | Issue Tracker | [SFTtech/debmagic](https://github.com/SFTtech/debmagic/issues)                                 |
 | Matrix Chat   | [`#sfttech:matrix.org`](https://app.element.io/#/room/#sfttech:matrix.org)                     |
 | Support us    | [![donations](https://liberapay.com/assets/widgets/donate.svg)](https://liberapay.com/SFTtech) |
 
-
 ## License
 
 Released under the **GNU General Public License** version 2 or later, [LICENSE](legal/GPL-2) for details.
diff --git a/docs/conf.py b/docs/conf.py
@@ -20,6 +20,8 @@
 ]
 myst_enable_extensions = [
     "colon_fence",
+    "html_image",
+    "attrs_inline",
 ]
 
 templates_path = ["_templates"]
diff --git a/docs/develop/index.md b/docs/develop/index.md
@@ -3,5 +3,30 @@
 This section covers documentation relevant to developing and maintaining the debmagic
 codebase, and some guidelines for how you can contribute.
 
+## Getting started with development
+
+Prerequisites:
+
+- Debian >= trixie, either roll your own environment or to get started faster use the [devcontainer](https://containers.dev/)
+- Python >= 3.12
+- [UV](https://docs.astral.sh/uv/)
+
+Setup:
+
+```shell
+uv sync
+uv run pre-commit install
+```
+
+Build the documentation
+
+```shell
+# oneshot build
+uv run sphinx-build docs docs/_build
+# continous serving
+uv run sphinx-autobuild docs docs/_build
+```
+
 ```{toctree}
-```
+
+```
diff --git a/docs/index.md b/docs/index.md
@@ -1,11 +1,13 @@
 # debmagic
 
+![debmagic image](../assets/debmagic-logo.svg){width=250px align=center}
+
 ```{toctree}
 :hidden:
 :caption: Usage
 
 usage/getting-started.md
-usage/installation.md
+usage/modules/index.md
 ```
 
 ```{toctree}
@@ -20,4 +22,4 @@ develop/index.md
 :caption: 📖 Reference
 
 develop/_changelog.md
-```
+```
diff --git a/docs/usage/getting-started.md b/docs/usage/getting-started.md
@@ -1,2 +1,107 @@
 # Getting Started
 
+## Installation
+
+### Pip
+
+```shell
+pip install debmagic
+```
+
+or directly use uv
+
+```shell
+uvx debmagic
+```
+
+### Debian / Ubuntu - Soon (tm)
+
+```shell
+apt install debmagic
+```
+
+## Example debian/rules.py
+
+Python `debian/rules.py` equivalent of [Ubuntu 24.04 htop](https://git.launchpad.net/ubuntu/+source/htop/tree/debian/rules?h=ubuntu/noble):
+
+```python
+#!/usr/bin/env python3
+
+from debmagic.v0 import Build, autotools, dh, package
+
+pkg = package(
+    preset=[dh],
+    maint_options="hardening=+all",
+)
+
+if pkg.buildflags.DEB_HOST_ARCH_OS == "linux":
+    configure_params = ["--enable-affinity", "--enable-delayacct"]
+else:
+    configure_params = ["--enable-hwloc"]
+
+# hurd-i386 can open /proc (nothing there) and /proc/ which works
+if pkg.buildflags.DEB_HOST_ARCH_OS == "hurd":
+    configure_params += ["--with-proc=/proc/"]
+else:
+    configure_params += ["--enable-sensors"]
+
+
+@pkg.stage
+def configure(build: Build):
+    autotools.configure(
+        build,
+        ["--enable-openvz", "--enable-vserver", "--enable-unicode", *configure_params],
+    )
+
+pkg.pack()
+```
+
+### debhelper compatibility
+
+Debmagic can use `dh` and provides **dh overrides** as common in `debian/rules` Makefiles:
+
+```python
+from debmagic.v0 import dh
+
+# specify dh arguments:
+dhp = dh.Preset("--with=python3 --builddirectory=build")
+pkg = package(preset=dhp)
+
+# define optional overrides:
+@dhp.override
+def dh_auto_install(build: Build):
+    print("dh override worked :)")
+    build.cmd("dh_auto_install --max-parallel=1")
+
+pkg.pack()
+```
+
+### Custom functions
+
+To add custom functions directly usable from CLI (like custom `debian/rules` targets for maintainers):
+
+```python
+pkg = package(...)
+
+@pkg.custom_function
+def something_custom(some_param: int, another_param: str = "some default"):
+    print(f"you passed {some_param=} {another_param=}")
+
+pkg.pack()
+```
+
+This function can be directly called with:
+
+```console
+./debian/rules.py something-custom --another-param=test 1337
+```
+
+```text
+you passed some_param=test another_param=1337
+```
+
+And generates automatic help for:
+
+```console
+./debian/rules.py something-custom --help
+```
diff --git a/docs/usage/installation.md b/docs/usage/installation.md
diff --git a/docs/usage/modules/autotools.md b/docs/usage/modules/autotools.md
@@ -0,0 +1 @@
+# Autotools
diff --git a/docs/usage/modules/dh.md b/docs/usage/modules/dh.md
@@ -0,0 +1 @@
+# Debhelper Compatibility
diff --git a/docs/usage/modules/index.md b/docs/usage/modules/index.md
@@ -0,0 +1,9 @@
+# Modules
+
+```{toctree}
+:hidden:
+:caption: Modules
+
+autotools.md
+dh.md
+```

Original file line number	Diff line number	Diff line change
`@@ -20,6 +20,8 @@`
`20`	`20`	`]`
`21`	`21`	`myst_enable_extensions = [`
`22`	`22`	`"colon_fence",`
	`23`	`+ "html_image",`
	`24`	`+ "attrs_inline",`
`23`	`25`	`]`
`24`	`26`
`25`	`27`	`templates_path = ["_templates"]`