Severson-Group / Severson-Group/docs.amdc.dev

Document C code API

Open
#13 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Jupyter Notebook
Stars
1
Forks
3
Avg merge
2d 23h
Merged PRs (30d)
1

Description

This issue comes from the AMDC-Firmware repo: https://github.com/Severson-Group/AMDC-Firmware/issues/133


Now that the C code is maturing (i.e. ./drv/foo.c), we should make detailed documents about how to use them from a user perspective.

This should include:

For drivers:

  1. Brief explanation of how the internals of the driver work. Should link to the IP core docs if appropriate.
  2. Index of all available function calls and what they do.
  3. Example code which exercises the driver.

Similar for system code.


I think we should make use of the Sphinx autodocs feature, but this will take a bit of work to figure out how to robustly use... Since the code is in a different repo. So, might have to make a submodule in this repo, docs.amdc.dev, then, on docs build, the build scripts checkout a given release branch of the AMDC-Firmware and then auto-build the API docs...

This will involve a big push in the source C file documentation with lots of comments added, etc.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the existing ./drv/foo.c code and the documentation build setup, then review how Sphinx autodocs could consume C sources from the AMDC-Firmware repository and a selected release branch. Done means drivers and system code have user-facing internals, function indexes, examples, and generated API documentation, with the required source comments documented.

Written by the indexing model from the issue text.

Assessment

Tech stack
c
Domain
build-system, documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.