From 0b97a3794261d648f0d62f166943925409315889 Mon Sep 17 00:00:00 2001 From: Khalil Estell Date: Sun, 23 Mar 2025 09:12:02 -0700 Subject: [PATCH] :memo: Add "How To" instructions to README The "How To" instructions tell you how to add another libhal package to the API docs. --- README.md | 154 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 153 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 8f257fb..61a1bc0 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,154 @@ # api -Stores and makes available API docs for all libhal packages + +Stores and makes available API docs for all libhal packages and their various +versions. + +## 📂 File Layout + +```plaintext +. +├── LICENSE +├── README.md +├── libhal +│ ├── 4.10.0 +│ ├── main +│ └── switcher.json +├── +│ ├── +│ ├── +│ └── switcher.json +└── libhal-util + ├── 5.4.3 + ├── main + └── switcher.json +``` + +Each directory corresponds to package or repo in the organization. The +subdirectories are named for each version (or branch) that API docs are made +for. Contained within are the static HTML, JS, and CSS files generated from +Doxygen and Sphinx. The `switcher.json` file is used to provide a mapping from +"version" to a URL which will appear on a drop down in the rendered +documentation. The URL for the switcher MUST be absolute and is hard coded at +documentation build time. + +## 🚀 Adding API doc support for a package + +### ⚙️ Deploy API Action + +> [!NOTE] +> This is for libhal project only. At some later time I will document how +> general C++ projects can use this same setup to deploy API docs for +> themselves. + +Add the following file to your github workflow `/.github/workflow/api.yml`: + +```yaml +name: 📚 Deploy APIs + +on: + release: + types: + - published + push: + branches: + - main + workflow_dispatch: + +permissions: + contents: write + +jobs: + deploy_api_docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-python@v4 + with: + python-version: 3.x + - run: sudo apt update + - run: sudo apt install -y doxygen + - run: pip install -r docs/requirements.txt gitpython requests + - run: wget https://raw.githubusercontent.com/libhal/ci/5.x.y/scripts/api.py + - run: python api.py build --version ${{ github.ref_name }} + - run: python api.py deploy --version ${{ github.ref_name }} --repo-name ${{ github.event.repository.name }} + env: + GITHUB_TOKEN: ${{ secrets.API_PUSH_TOKEN }} +``` + +> [!info] +> Notice the `api.py` file. This file is the program that makes all of the +> magic happen. The script above downloads the latest `5.x.y` version of the +> script from the `libhal/ci` directory in order to build and deploy the API +> docs. If there is something wrong, its likely to have to do with the `api.py` +> script. + +### 🔑 Generating PAT token + +Notice the line `GITHUB_TOKEN: ${{ secrets.API_PUSH_TOKEN }}`. This is a PAT +(Personal API Token). The default `GITHUB_TOKEN` only provides limited access +to other repos. You cannot push to repos within an organization without a token +with higher permissions. You need a token that has the permissions to update +this repo and we'd like to limit that token to only being capable of updating +this repo. + +1. To generate a PAT token follow the instructions in this page: +[🔗 Creating a fine-grained personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token). +1. When you get to the point where you can choose the **Repository access** + Select: `Only select repositories`. + 1. In the dropdown select: Select `/api` +1. Set **Repository Permissions** access to: + 1. Set `Contents` ➡️ Access: "Read and Write" + 1. Set `Pull Requests` ➡️ Access: "Read and Write" +1. Press **Save** +1. You should be presented with a token, copy the token value and paste to a + text editor for safe keeping. +1. Go to your organization's secrets page using the URL: + `https://github.com/organizations//settings/secrets/actions`. +1. Click the button `new organization secret` +1. Set the name to `API_PUSH_TOKEN` and the value to the token you copied + earlier. If you have no further use for the token, you can delete from your + text editor. + +### 📑 Copy `docs/` from `libhal` + +The contents of `libhal`'s `docs/` directory has all of the doxygen and sphinx +files needed to generate the API docs like `libhal`. Our docs use doxygen to +generate XML docs based on the C++ code in the `include/` (the public API) +directory. This is fed into `Sphinx` using the `Breathe` plugin to combine +`doxygen` with `Sphinx`. The theme we use is the +[`PyData` theme](https://pydata-sphinx-theme.readthedocs.io/en/stable/). + +Within the `docs/libhal` directory you will find `.md` files and a `index.rst` +file. The `index.rst` file organizes all of the markdown files and the markdown +files are used to manually type out how you want the docs for a particular class +or source file to be rendered. Change these to fit your package. + +Update the `json_url` for the switcher to the following and update the +`` and `` templates to the correct value: + +```python +html_theme_options = { + "switcher": { + "json_url": "https://.github.io///switcher.json", + }, +} +``` + +Update these lines and replace `` with the name of your package: + +```python +breathe_projects = {"": "../build/xml"} +breathe_default_project = "" +breathe_default_members = ('members',) +project = "" +``` + +Update `docs/index.rst` to fit what you'd like to show as the front page of your +package. + +### 🎉 Done + +And you are done! The next time you push to main, make a release, OR manually +run the `api.yml` workflow, your API docs will be generated, a new branch, +commit, and PR will be made to `organization/api` that you can later decide to +pull into the repo or decline.