Embedded Computing
  • About
  • Blog
  • Hardware
    • Which Platform?
    • Controller Platforms >
      • Adafruit Platform
      • Arduino Plaform
      • BBC micro:bit
      • Espressif Platform
      • iLabs Platform
      • Raspberry Pi Platform (MCU)
      • Seeed Platform
      • Silicon Labs Platform
      • Teensy Plaform
    • Computer Platforms >
      • BeagleBone Platform
      • Raspberry Pi Platform (SBC)
      • UDOO Platform
    • Peripherals >
      • Shields
      • Grove System
      • Sensors
      • Actuators
    • Displays >
      • E-Paper Displays
      • Reflective Displays
      • TFT Displays
      • LCD Displays
    • Legacy Platforms >
      • chipKIT Plaform
      • 4D Systems Platform
      • Intel Platform
      • LaunchPad Plaform
      • BoosterPacks for LaunchPads
      • LightBlue Bean
      • Maple Plaform
      • Mediatek Platform
      • Microsoft Azure IoT DevKit
      • Particle Platform
  • Software
    • Exploring RTOS with Galaxia >
      • Event Library
      • Semaphore Library
      • Mailbox Library
      • Timer Library
      • Clock Library
      • SWI Library
      • Task Library
    • Ultra-Low Power with EnergyTrace >
      • Ultra-Low Power with MSP430
      • Ultra-Low Power with Energia MT and Galaxia
    • Using Integers Instead of Reals
    • Going Python?
  • IoT
    • IoT Platforms: Which Hardware? >
      • Matter with Silicon Labs MG24
    • IoT Services: Which Solution? >
      • Recommended IoT Solutions
      • Platform-Specific IoT Solutions
      • Other IoT Solutions
      • Not tested IoT Solutions
      • Notification Solutions
    • Get Date and Time from Internet with NTP
    • Fast and Easy WiFi Connection with QR-Code
  • Tools
    • How to Start?
    • Reference >
      • Asking for Help
      • Boards Pins Maps
      • Ruler
      • Boards and Plugs
      • I²C Logic Level Converter
      • Standards for Connectors
    • Training >
      • Texas Instruments Workshops
      • Embedded Systems: Shape The World — MOOC edX UTAustinX UT.6.02x
      • Embedded Systems - Shape The World: Microcontroller Input/Output — MOOC edX UTAustinX UT.6.10x
      • Embedded Systems - Shape The World: Multi-Threaded Interfacing — MOOC edX UTAustinX UT.6.20x
      • Real-Time Bluetooth Networks: Shape the World — MOOC edX UTAustinX UT.RTBN.12.01x
      • Systems Thinking with Texas Instruments Robotics System Learning Kit
    • Books >
      • Getting Started with the MSP430 LaunchPad
      • Getting Started with Arduino
      • Arduino Cookbook
    • IDE >
      • The Battle of IDEs
      • More Options
      • Assessing the Next Generation of IDEs
      • Tools for Documentation
    • Equipment >
      • Saleae Logic Analyser
      • Rigol DS1102E Oscilloscope
      • XDS110 Debug Probe with EnergyTrace​
      • Segger J-Link Programmer-Debugger
      • Nordic Power Profiler Kit II
  • Projects
    • Libraries >
      • Master I²C Software Library
      • Date and Time Library
      • highView Library Suite
      • Others Libraries
    • smartDevices >
      • I²C smartColours Smart Sensor
      • I²C smartRFID Smart Sensor
      • I²C smartLED Display
      • I²C smartControls Smart Device
      • I²C smartWiFi Smart Device
      • I²C smartBLE Smart Device
      • I²C smartNode Smart Device
    • IoT Projects >
      • Remote E-Paper Weather and Message Board
      • Typie-Walkie with LoRa and E-Paper Screen
      • Typie-Walkie with E-Paper Screen
      • Remote e-Paper Pictures Panel
      • Remote e-Paper Messages Panel
      • Industrial IoT Project
      • Remote Contactless Temperature Monitor
      • Using Node-RED for IIoT
      • Low Power Home Network Weather Monitoring
      • Updated Low Power Home Network Weather Monitoring
      • Weather and Security Station with Blynk
      • SensorTag to Blynk Using Node-RED
      • Pervasive Reporting
    • AI Projects >
      • Colour Recognition with Neural Network
    • Other Projects >
      • Air Quality Monitoring
      • Driving a Large E-Paper Display with a Compact Xiao RP2040
      • Low-Power E-Paper Weather Station
      • Portable Particulate​ Matter Monitor
      • FRAM-based E-Paper Screen Controller
      • General Purpose 3.5" Screen
      • Colour Recognition with Neural Network
      • A Low Power Weather Station
      • Digital Volt-Amp-Watt Meter
      • Mobile Measurement with LCD Display
      • Screen with SRAM for GUI
      • Volt-Amp-Watt-Meter for Grove
      • Multi-Touch Project with CapTIvate

Tools for Documentation

Apart from assembling the code, writing the documentation is the most challenging task when developing a library or a tool.

Here are the tools I'm currently using for documenting a library and documenting a tool.

Documentation for a Library

I started first with a text document converted into a PDF. I was using the free word-processing Pages but the generated PDF document had flaws.

The question was whether to have a separate file for the documentation or to include the documentation into an existing file.
​
Picture
The documentation is directly inserted into the header file, and relies on standard keywords as @brief, @details, @param. 

embedXcode generates a template with the corresponding parameters for the selected function.
Picture
Then each field needs to be completed.
Picture
Then Doxygen parses the header files and generates an HTML website, and a set of XML files to be compiled into a PDF document.

​Xcode supports those keywords natively, and provides the documentation as Quick Help, here called with the alt-? short-cut.
Picture

Documentation for an IDE

Documenting a tool has been more difficult. For embedXcode, I started first with a text document converted into a PDF. I was using the free word-processing Pages but soon the file was too big to handle, especially with pictures.

Additionally, the generated PDF document had flaws, was very large, slow to upload and difficult to share.
​
Picture
The second tool I used was the iBooks Author application to generate an electronic-book shared on the iBookStore. This greatly simplified ​the way the user manual was published. However, some users heavily disliked the iBooks application (albeit available on macOS and iOS), and some countries did not have access to the iBookStore, so the PDF document was still needed. Just as before, the PDF document generated by iBooks Author had flaws, especially for the internal links.

The major problem actually came from Apple. Apple didn't update iBooks Author very often, so it kept the old interface based on floating palettes when the other productivity tools (Pages, Numbers and Keynote) have those tools grouped on a fixed pane.

More annoyingly, submitting an updated release of the user manual was always risky, as Apple was often blocking the new release for arcane reasons.

Picture
Picture

Website for an IDE

So I switched to an online only user manual, hosted on a dedicated website.

​The entire website is generated by MkDocs, a tool that turns MarkDown files into rich HTML static pages. MkDocs can be expanded with templates and plug-ins, and I'm using the Material for MkDocs template for a clean presentation.

There is one MarkDown document per page. This granularity eases maintenance and speeds the upload to the server. PDF documents are no longer available.
Picture

Links

  • Doxygen
  • MkDocs
  • Material for MkDocs
Picture
Picture
Picture
Powered by Create your own unique website with customizable templates.