Automating documentation using Python

One of the tasks for this week was cleaning up after an infrastructure move and then updating all the documentation. Given that there are many forms of documentation, it was a bit of a task.

I ended up putting together a spreadsheet of the main details so that there is a canonical reference. The first task was to create some diagrams to work out what we had and where, before asking if it matched what I knew. It took several iterations to fix typos and inconsistencies.

I then looked around for templates that I could use to ensure that key data is present for various audiences, such as emergencies or finding out what is where. Having found a series of suggestions on Reddit and blogs, I put together a small Markdown template that covered the questions what, where, why, how, and who? Having done some string manipulation as part of compage, I started with that before discovering Python’s Template class in string. The documentation is sufficiently small not to require anything larger really and I am just starting out on this road. That meant that I could then map the spreadsheet to Markdown and update the relevant repository.

However, having seen Lorna Mitchell talk about Vale, I thought that I would explore it to create a light weight checking pipeline. I picked up some silly typos and am sufficiently happy that it is something to develop in the longer term.

Was it worth the 3 or 4 hours writing? Well, so far so good. There is a large amount to develop as I go through this project and so many others. However, I am thinking of other projects and how that I write user documentation for varying audiences. This short post on technical writing is one to read I think as is the reference to Diataxis as a reminder for the types of piece to write.


Pi in the Street

I am about to start work on a new project, AI in the Street. I am not sure exactly my role as the kick off meetings are this week. In preparation, I have been playing around with a Raspberry Pi Pico and the aioble library to make really simple tunes on it. Not quite chiptunes […]


Weeknote: AARs and patterns in audio

I’ve been wrapping bits and pieces of the HackRF base app to have some fun. One of the challenges was updating some old code in the AAR that needed a new flag. Next up is to make the gradle build a bit nicer and to add in the name again. I also need to update […]


Weeknote: SDRs, Workshops, and tiny tools

Less weeknote and more occasional update … I celebrated passing my Viva without corrections by putting in a workshop proposal. I heard last night that it was accepted. Now to organise it. While I was working on the proposal and a paper, I wrote a prototype sonification plugin for Gephi. Now that the workshop exists, […]


Weeknotes: It’s raining sensors

Well, prototypes of sensors. I have been playing around with the piezo sensor to measure the pressure on a surface. I have been using a milk bottle as a testing environment to act as a surrogate for a plastic surface to test the code. This goes with the rain gauge, using the HC-SR04 distance sensor. […]


Weeknotes: sensors and so on

A relatively quiet week really. I put in an order for some equipment from PiHut, such as resistors and capacitors along with distance sensors to crack on with looking at audio interventions with the weather such as sonic anemometers and rain gauges. I did some come across a disdrometer which looks very appealing. Just waiting […]


Weeknotes: Listening to the Air Waves

This week I bit the bullet and plugged in some machines. I bought a HackRF One from Martin Lynch and Son with an ANT 500 antenna. I installed hackrf and gnuradio through Homebrew, which is not with out its perils. The gnuradio version (3.10) that is installed does not have the osmocom component so I […]


Social Audio

Social Audio is a new term to me in this guise. I enjoyed Brian Cantrill’s talk, Social Audio as a Vector For Engineering Wisdom, about Oxide’s use: https://youtu.be/W8qiDhlFVCE. I do like the idea for multiple voices in a meeting and sharing information. I do wonder if this is amenable to digital methods and combining the […]


Weeknotes: Phones and the Environment

A couple of weeks ago, I decided to follow up a query that I had about tracing the way that the Bluetooth signal is constructed through the various layers of software and hardware. My interest is software but this does interface with hardware sensors on the phone. I took the phone apart using screw drivers […]


Weeknotes: overdue musings

I spent the best part of a week in Dublin where I presented at the Synthetic City conference on Unheard City and Unheard Spaces. The conference was thought provoking with some great conversations, but there is work to do. Must make the app releasable along with some of the methods. I made a start on […]