search

arkq / bluez-alsa

Bluetooth Audio ALSA Backend
MIT License
864 stars 189 forks source link

Convert D-Bus API documentation to rst and man pages #668

Closed borine closed 1 year ago

borine commented 1 year ago

Bluez appears to be in the process of converting its D-Bus API documentation to manual page format, using rst2man . This PR attempts to make the same conversion for BlueALSA. Some points that may need discussion:

  1. There does not yet appear to be any general consensus on how to catalogue D-Bus API manual pages. From the examples I have on my system, I see:

    • Debian (org.debian.apt) uses section 7, group "D-Bus Interface"
    • Systemd (org.freedesktop.*) uses section 5, each in its own group. For example org.freedesktop.resolve1 is in group "org.freedesktop.resolve1" and org.freedesktop.systemd1 is in group "org.freedesktop.systemd1"
    • Bluez (org.bluez.*) uses section 5, group "Linux System Administration"

    I've chosen to place these manual pages in section 7 of the manual, and in group "D-Bus Interface", but that can easily be changed if required.

  2. I've used my own the presentation style, based on a combination of the org.debian and org.bluez pages, which seems to give the clearest manual page layout for a relatively simple API like BlueALSA's. Systemd uses a very different presentation, a json-like syntax, which I find more difficult to follow; but again these BlueALSA pages are just an initial draft and can be re-worked as necessary.

codecov[bot] commented 1 year ago

Codecov Report

All modified lines are covered by tests :white_check_mark:

see 3 files with indirect coverage changes

:loudspeaker: Thoughts on this report? Let us know!.

arkq commented 1 year ago

+1 for that! I thought that maybe we should follow BlueZ and systemd and use section 5, but then I've checked man-pages manual and it reads:

7 Overview, conventions, and miscellaneous Overviews or descriptions of various topics, conventions, and protocols, character set standards, the standard filesystem layout, and miscellaneous other things.

so I think we can stick with section 7.