Overall Structure

In this guide we'll watch as I transform Adafruit_TSL2561, one of our first libraries, spruce it up and automate it. This guide doesn't talk about how to write code - just how to make it fancy!

We'll be using the 'classic' Arduino library structure. In this case, we make a new repo, with no spaces or dashes, on GitHub: Adafruit_TSL2561 and git clone it into our ArduinoSketches/libraries folder. This makes it easy to test in Arduino and commit in the same folder

Inside the folder you'll need these 4 parts:

Adafruit_TSL2561.cpp - the main cpp file that contains your code
Adafruit_TSL2561.h - the main header file that has macros, enums, classes, etc!
library.properties - the file that lets Arduino IDE and library manager know what's inside your library
README.md - Appears in the front of the GitHub repo, a good place to put descriptions, images, instructions and a Travis tag

You may also have optional parts like

.gitignore (see below) - helps keep your git commits from accidentally including temporary files
.github folder with ISSUE_TEMPLATE.md and PULL_REQUEST_TEMPLATE.md - see our examples here if you like you can adapt and reuse them.

library.properties is very particular about its formatting, see here for a guide on how to make sure you get this in the right formatting! We won't cover it in detail here

For README.md we do recommend adding a Travis tag and you might as well do that now. Open it up in a text editor and after the first heading add text like this:

[![Build Status](https://travis-ci.com/adafruit/Adafruit_TSL2561.svg?branch=master)](https://travis-ci.com/adafruit/Adafruit_TSL2561)

Except change the two sub-URLs to match your repository

When it renders for now it will say Build Unknown - we'll get that going later!

Create Empty gh-pages Branch

Rather than storing the documentation in your master branch, cluttering your repo, we'll have TravisCI put the files into the gh-pages branch. GitHub can be informed that documentation is there and it will host the webpages for you, it's very slick!

Make sure you've committed and pushed all your code before you continue, since you will be deleting from a branch and it can be scary!

Download File

Copy Code

cd /path/to/repository
git checkout --orphan gh-pages && \
rm -rf * .github .travis.yml .gitignore && \
echo "My gh-pages branch" > README.md && \
git add . && \
git commit -a -m "Clean gh-pages branch" && \
git push origin gh-pages && \
git checkout main

cd /path/to/repository
git checkout --orphan gh-pages && \
rm -rf * .github .travis.yml .gitignore && \
echo "My gh-pages branch" > README.md && \
git add . && \
git commit -a -m "Clean gh-pages branch" && \
git push origin gh-pages && \
git checkout main

On GitHub you can verify the gh-pages branch is empty

Enable GitHub Pages on gh-pages

Now you've created gh-pages you can set it up so GitHub will automatically create a website with our auto-generated documentation

Go to the Settings for the repository

And scroll down to GitHub Pages. From the drop-down select gh-pages as the source and hit Save

Save and you'll get notification of your new github.io URL. Note that nothing will be there at this time - that's OK! We'll get that going soon.

Optional: .gitignore

Put the following into your master branch's .gitignore, it will help you avoid committing doxygen files later

Download File

Copy Code

# Our handy .gitignore for automation ease
Doxyfile*
doxygen_sqlite3.db
html

# Our handy .gitignore for automation ease
Doxyfile*
doxygen_sqlite3.db
html

Optional (For Adafruit Only!) Add Adafruit Librarians group

If you're working on an official Adafruit library, add the Arduino Librarians group to your repository with write access, which will let adafruit-adabot push pages on your behalf!