Skip to content

Install optional self-documentation tools

This section requires the embedXcode+ edition and is optional.

The installation of the following tools is optional and only required if you want to use the self-documentation feature.

  • Doxygen generates all the help files based on comments added to the code. Doxygen requires Graphviz to draw elaborate dependency trees.

  • Doxygen Helper provides a handy shortcut to add a ready-to-use template for comments.

  • TeXShop translates the Doxygen output into PDF documents.

  • Artistic Style is a utility to indent, format and improve the presentation of the code.

Install Doxygen

Doxygen parses the code, looks for comments and generates the HTML pages.

Doxygen generates HTML files, Xcode native help files and LaTeX files. LaTeX files can be converted into PDF documents using TeXShop.

I strongly recommend to install DoxyWizard included in the Doxygen package.

DoxyWizard provides a GUI for an easy tweaking of the parameters.

In case DoxyWizard complains about the missing Qt framework,

  • Open a Terminal window.

  • If Homebrew isn’t installed, launch the following command.

$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
  • Run the following command to install the missing Qt framework.
$ brew install qt

Install Graphviz

Graphviz generates dependency trees, very handful for classes.

Graphviz is no longer available as a package for macOS and no longer features a GUI. Instead, it relies on Homebrew for its installation and is operates through command line only.

To install Graphviz,

  • Open a Terminal window.

  • If Homebrew isn’t installed, launch the following command.

$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
  • Run the following command to install Graphviz.
$ brew install graphviz

For more information,

  • Please refer to the Homebrew website.

  • Please refer to the Download page on the Graphviz website.

Install Doxygen Helper

To ease and speed up the writing of the comments, I use the Automator Service Doxygen Helper .

By just selecting a function and pressing Cmd+Shift+D, the helper generates a template for the comment lines.

///
/// @brief   Blink a LED
/// @details LED attached to pin is light on off
/// @n       Total cycle duration = ms
/// @param   pin pin to which the LED is attached
/// @param   times number of times
/// @param   ms cycle duration in ms
///
void blink(uint8_t pin, uint8_t times, uint16_t ms);

A modified version of the Automator Service is included in the ~/Documents/embedXcode folder. To install it:

  • Unzip the automator_service_xcode_modified file.

  • Double-click on the Document Code workflow.

A window pops-up and asks for confirmation:

  • Confirm by clicking on Install.

  • Optionally, click on Open with Automator to launch Automator and edit the service.

However, if you prefer to install the original Automator Service,

The previously recommended alternative, the ThisService utility, is no longer available.

Below, an example of a LaTeX file translated into a PDF document.

Install TeXShop

Finally, TeXShop builds a PDF document from the LaTeX files Doxygen has generated. TeXShop and all the related utilities are included in the MacTeX package.

The major issue with the MacTeX package is its size. BasicTeX provides a lighter alternative.

Install full MacTeX

To install the full MacTeX bundle with other utilities and fonts,

  • Download the MacTeX full distribution.

embedXcode supports the 2017 and 2020 distributions of MacTeX. All mentioned releases generate the HTML website.

Warning

Releases 2017 and 2020 of MacTeX succeed in generating PDF, while other fail.

  • Launch the installation package and follow the instructions.

Install lighter BasicTeX

Note

Albeit lighter than the full MacTeX distribution (more than 4 GB), the BasicTeX distribution (less than 100 MB) doesn’t include some of the required packages and none of the GUI applications, of which TeXShop.

As a lighter alternative, install the smaller BasicTeX bundle. It includes the LaTeX-to-PDF converter, but not the optional utilities TeXShop and TeX Live Utility, to be installed separately.

Optionally,

Alternatively, with Homebrew on the Terminal,

  • Open a Terminal window.

  • If Homebrew isn’t already installed, launch the following command.

$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
  • Install the smaller BasicTeX package.
$ brew cask install basictex

To finalise the installation of BasicTeX and add the missing packages and fonts,

  • Launch the package manager TeX Live Utility to install the following required packages varwidth, multirow, hanging, adjustbox, collectbox, stackengine, wasysym, sectsty, tocloft, newunicodechar, etoc; and fonts helvetic, courier, wasy.

Alternatively, with the Terminal,

  • Add the required packages.
$ sudo tlmgr install varwidth multirow hanging adjustbox collectbox stackengine wasysym sectsty tocloft newunicodechar etoc helvetic courier wasy 

Install Artistic Style

Artistic Style is a utility to indent, format and improve the presentation of the code.

For more information about the options,

  • Please refer to the Documentation page on the Artistic Style website.

It is a good idea to launch this utility before sharing the code.

To install Artistic Style,

  • Open a Terminal window.

  • If Homebrew isn’t installed, launch the following command.

$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
  • Run the following command to install Artistic Style.
$ brew install astyle