From 4b40e083428b06b881fc5d5970a564ca55701ab1 Mon Sep 17 00:00:00 2001 From: per1234 Date: Fri, 9 Apr 2021 07:55:39 -0700 Subject: [PATCH] Add table of contents to documentation It will be helpful to the reader to be able to get an overview of the documentation content and quickly navigate to the section of interest. The table of contents are automatically generated using the markdown-toc tool. Because it can be easy to forget to update the table of contents when the documentation content is changed, I have added a CI workflow to check for missed updates to readme ToC. On every push or pull request that affects the repository's documentation, it will check whether the table of contents matches the content. --- .github/workflows/check-toc.yml | 58 +++++++++++++++++++++++++++++++++ FAQ.md | 27 +++++++++++++++ README.md | 15 +++++++++ 3 files changed, 100 insertions(+) create mode 100644 .github/workflows/check-toc.yml diff --git a/.github/workflows/check-toc.yml b/.github/workflows/check-toc.yml new file mode 100644 index 00000000..30d2765b --- /dev/null +++ b/.github/workflows/check-toc.yml @@ -0,0 +1,58 @@ +name: Check ToC + +# See: https://docs.github.com/en/free-pro-team@latest/actions/reference/events-that-trigger-workflows +on: + push: + paths: + - ".github/workflows/check-toc.yml" + - "README.md" + - "FAQ.md" + pull_request: + paths: + - ".github/workflows/check-toc.yml" + - "README.md" + - "FAQ.md" + workflow_dispatch: + repository_dispatch: + +jobs: + check: + name: ${{ matrix.file.name }} + runs-on: ubuntu-latest + + strategy: + fail-fast: false + + matrix: + file: + - name: README.md + # Max ToC depth, for use with the markdown-toc --maxdepth flag. + maxdepth: 4 + - name: FAQ.md + maxdepth: 3 + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Get week number for use in cache key + id: get-date + run: | + echo "::set-output name=week-number::$(date --utc '+%V')" + + - name: Load dependencies cache + uses: actions/cache@v2 + with: + path: ~/.npm + key: ${{ runner.os }}-node-markdown-toc-${{ steps.get-date.outputs.week-number }} + restore-keys: | + ${{ runner.os }}-node-markdown-toc- + + - name: Install markdown-toc + run: sudo npm install --global markdown-toc + + - name: Rebuild ToC + run: markdown-toc --bullets=- --maxdepth=${{ matrix.file.maxdepth }} -i "${{ github.workspace }}/${{ matrix.file.name }}" + + - name: Check ToC + run: git diff --color --exit-code diff --git a/FAQ.md b/FAQ.md index 923712e0..b81c67c8 100644 --- a/FAQ.md +++ b/FAQ.md @@ -1,5 +1,32 @@ # Arduino Library Manager FAQ +## Table of Contents + + + +- [General](#general) + - [What is the Arduino Library Manager?](#what-is-the-arduino-library-manager) + - [How is the Library Manager index generated?](#how-is-the-library-manager-index-generated) +- [Submission](#submission) + - [How can I add my library to Library Manager?](#how-can-i-add-my-library-to-library-manager) + - [What are the requirements for a library to be added to Library Manager?](#what-are-the-requirements-for-a-library-to-be-added-to-library-manager) +- [Updates](#updates) + - [How can I publish a new release once my library is in the list?](#how-can-i-publish-a-new-release-once-my-library-is-in-the-list) + - [What are the requirements for publishing new releases of libraries already in the Library Manager list?](#what-are-the-requirements-for-publishing-new-releases-of-libraries-already-in-the-library-manager-list) + - [Why aren't releases of my library being picked up by Library Manager?](#why-arent-releases-of-my-library-being-picked-up-by-library-manager) + - [I did something wrong! How can I change or unpublish an already published library?](#i-did-something-wrong-how-can-i-change-or-unpublish-an-already-published-library) + - [How can I change my library's name?](#how-can-i-change-my-librarys-name) +- [Limitations](#limitations) + - [Is my Git repository OK?](#is-my-git-repository-ok) + - [Are Git submodules supported?](#are-git-submodules-supported) +- [Usage](#usage) + - [Can I add my own URL with my own library index?](#can-i-add-my-own-url-with-my-own-library-index) + - [When I install a library that I know depends on another library, will this other library be installed as well?](#when-i-install-a-library-that-i-know-depends-on-another-library-will-this-other-library-be-installed-as-well) + - [Can I install multiple versions of one library and use the proper one in my sketches?](#can-i-install-multiple-versions-of-one-library-and-use-the-proper-one-in-my-sketches) + - [How can I remove a library I installed via Library Manager?](#how-can-i-remove-a-library-i-installed-via-library-manager) + + + ## General ### What is the Arduino Library Manager? diff --git a/README.md b/README.md index 3d66f1dc..efbf66f9 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,21 @@ This repository contains the list of libraries in the [Arduino Library Manager](https://www.arduino.cc/en/guide/libraries#toc3) index. +## Table of Contents + + + +- [Frequently asked questions](#frequently-asked-questions) +- [Adding a library to Library Manager](#adding-a-library-to-library-manager) + - [Instructions](#instructions) + - [If the problem is with the pull request:](#if-the-problem-is-with-the-pull-request) + - [If the problem is with the library:](#if-the-problem-is-with-the-library) +- [Changing the URL of a library already in Library Manager](#changing-the-url-of-a-library-already-in-library-manager) +- [Removing the URL of a library already in Library Manager](#removing-the-url-of-a-library-already-in-library-manager) +- [Report a problem with Library Manager](#report-a-problem-with-library-manager) + + + ## Frequently asked questions For more information about Arduino Library Manager and how the index is maintained, please see [the FAQ](FAQ.md).