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 to 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 package.

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

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.

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.

To install the MacTeX bundle with other utilities and fonts.

  • Download the MacTeX full distribution.

embedXcode supports the 2017, 2018 and 2019 distributions of MacTeX. All mentioned releases generate the HTML website.

Warning

Release 2017 of MacTeX succeeds in generating PDF, while more recent releases 2018 and 2019 fail.

  • Launch the installation package and follow the instructions.

As a lighter alternative, install TeXShop and the pdflatex LaTeX-to-PDF converter manually.

  • Download TeXShop as a standalone application, or

To install the LaTeX-to-PDF converter,

  • 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 pdflatex utility.
$ brew cask install basictex

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

Note

Albeit lighter than the mactex-20170524.pkg package (more than 3 GB), the mactex-basictex-20170607.pkg package (less than 100 MB) doesn't include some of the required utilities and none of the GUI applications, of which TeXShop.

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