 |
SparkFun How To Arduino Library
v0.0.1-22-g91babf1
Example repository for an Arduino Library
|
|
SparkFun How To Arduino Library
v0.0.1-22-g91babf1
Example repository for an Arduino Library
|
GitHub repository that outlines how to build a modern SpakRun Arduino Library, which includes use of the SparkFun Toolkit, and Doxygen generated documentation that is published via GitHub Pages.
NOTE:
Details on how to setup a SparkFun Arduino Library are contained the how to sections further down in this file. This sections contains step-by-step instructions on how to create a SparkFun Arduino Library repository, including how to use the SparkFun Toolkit, and how to setup documentation generation and deployment using GitHub Actions and GitHub Pages.
Enter a description of the library here
This library allows you to:
This product is open source!
This product is licensed using the MIT Open Source License
When creating a repository, the preferred method is to create an empty repository and then copy in desired resources from this HowTo repository as needed.
1) Create a new repository on GitHub with the desired name for the library, following the template SparkFun_<product name>_Arduino_Library. When creating the repository, select the option to create a README.md file and a MIT License file. This will create the initial files for the repository and set up the license for the repository. 2) Once the repository created, the first step is to create branch - specifically a develop branch. This branch is used to stage changes and updates to the library before they are merged into the main branch. All of the initial development is performed on the develop branch, and then a GitHub PR is used to support the initial code review of the repository. 3) Clone the repository to your local machine and switch to the develop branch.
[!NOTE] The HowTo repository is not used as a GitHub template to create a new repository due to how GitHub displays an annoying banner on repository created from a template.
SparkFun Arduino Libraries by default are published using the MIT OpenSource License. To attribute the repository with this license do the following:
At the bottom of the README.md file, include the following text to indicate the license for the repository:
For each source file created, include the following text at the comment header at the top of the file:
Change the date and copyright date value as needed.
To brand the repository for a library, a "splash" image is created and is the first element of the README.md file.
The Splash Image for this repository:
The image uses one of the template image files contained in the docs/images folder. To create a specific image, perform the following steps.
1) Select the image template to use from HowTo - make a local copy of this file 2) Open this file in your desired image editing tool (i.e. Photoshop, Pixelmator, GIMP ...etc). 3) Add the name of the repository item on the left section of the image. 4) Add an image of the target product as well as a tile for the board in the white area of the image 5) Save the image and add it to the "docs/images" folder of the new repository. 6) Set this image name in the linked image at the top of your repo README.md file
Additionally, upload the image as the social image for the new repository. To do this, perform the following:
The file is uploaded and available for the repo.
[!NOTE] The social image is used to create preview tiles on the SparkFun Documentation landing page located at docs.sparkfun.com
The README.md file is the main landing page for the repository and should include the following sections:
SparkFun publishes product documentation using GitHub Pages. For product getting started and overview guides, Docusaurus is used. For Code libraries - like this Arduino Library HowTo - the doxygen system is used.
The first step is adding doxygen comments to the source code files. This is done by adding special comment blocks to the source code files that are then parsed by doxygen to generate the documentation. See doxygen for specific details, or just use your favorite AI to add doxygen enable comments to the library code.
First copy all the contents of the ./docs directory of this repository to the new repository. This includes the doxygen configuration file, HTML custom additions and a custom css (doxygen-awesome).
On a unix/macos system this can be done with the following command:
Next, the doxygen configuration file needs to be updated to reflect the new repository. Open the file Doxyfile, which is located in the docs/doxygen folder and called **doxygen-config***. All updates that are made involve setting the name of this repository and and the name of the library. The following fields need to be updated:
That's it.
The doxygen-awesome-css is a custom CSS sub-repository is used to style the generated documentation. This file is located in the docs/doxygen folder and is called doxygen-awesome.css. To enable proper operation, the current repository is removed and re-linked into this repo. This is done by performing the following steps:
Note - for more details concerning doxygen-awesome-css, see the official repository located at https://github.com/jothepro/doxygen-awesome-css
In the folder docs/doxygen/doxygen-custom, the header.html file is used to add a link to the generated documentation page header. This fancy link points to the github repository for the library.
To update the link and title, the file must be edited, replacing all "SparkFun" entries and links, with titles and links for the new library.
The first step is to enable GitHub Pages support on the new repository. This is done on the Settings > Pages section of the new repository. The following is done:
The documentation is built using the GitHub Action located in the .github/workflows/build-deploy-ghpages.yml file. To enable this action, the following steps are performed:
1.9.5 