 |
SparkFun How To Arduino Library
v0.0.1-26-g33f5720
Example repository for an Arduino Library
|
|
SparkFun How To Arduino Library
v0.0.1-26-g33f5720
Example repository for an Arduino Library
|
This repository is a template and guide for creating SparkFun Arduino Libraries. It contains the necessary files and structure to create a new Arduino library repository that follows the SparkFun standards and practices for Arduino libraries.
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.
The How To Repository (this repository) contains an example README.md file - README_Example.md. This provides a easily modified file to build a repository README around.
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:
On the main code page of the repository, the "About" section (upper right side of the page) contains meta information about the repository and also sets the topics/tags that are used to automatically add the repository to the sparkfun documentation landing page (docs.sparkfun.com).
The set About information, select the gear icon in the section. From here, the following sections are updated
Add a detailed, one sentence description for the repository. This is often the same sentence used in the libraries.properties file.
Select the Use your GitHub Pages Website option for the repository website. NOTE: If the website is not https enabled, check your GitHub pages settings for the repository and ensure the enforce HTTPS option is checked.
The topics section should be setup to match what is needed for the SparkFun documentation landing page. For the specifics, consult the documentation landing page readme file.
Also add the topic, sparkfun-tutorial , which is used to indicate this library GitHub pages content and used by the system that builds the docs.sparkun.com landing page.
1.9.5