Sam Price created a merge request:
https://gitlab.rtems.org/rtems/docs/rtems-docs/-/merge_requests/265
Project:Branches: TheSamPrice/rtems-docs:gpio-docs to rtems/docs/rtems-docs:main
Author: Sam Price
Documentation for the generic GPIO API, two commits so the two manuals can
be split into separate MRs on request.
**Companion to rtems!1499** (the API) **and rtems!1500** (four drivers).
Opened as a Draft for the same reason those are: the shape is up for review
before any of it is proposed for merge. If the API changes, these change with
it.
| commit | chapter | shape |
|---|---|---|
| 1 | `c-user/gpio/` | a five-file manager chapter -- index, introduction,
background, operations, directives -- with thirteen directives in the rubric
template. Modelled on `c-user/regulator/`, which is the most recent
hand-written manager chapter in the tree. |
| 2 | `bsp-howto/gpio.md` | the driver-writer half, in `bsp-howto/can.md`'s
shape. Does not repeat the application API; links to the c-user chapter for it.
|
Registration is the one line each needs: `c-user/index.md` and
`bsp-howto/index.md` toctrees. Nothing else has to be edited, since
`common/waf.py` globs `**/*.md`.
## Conventions followed
Measured against the tree rather than assumed, because the README has
drifted from what the sources actually do:
- **MyST Markdown, not reStructuredText.** README item 04 still gives reST
heading underlines, but the tree is 484 `.md` files and 0 `.rst`. ATX
headings, with `{eval-rst}` islands where a directive has no MyST spelling.
- **The rubric directive template**, which is what all 25 `c-user/*/`
chapters use -- `CALLING SEQUENCE`, `PARAMETERS`, `DESCRIPTION`,
`RETURN VALUES`, `NOTES`, `CONSTRAINTS`, in that order. Of 451 directive
subsections in the tree, none have their rubrics out of order, so these do
not either.
- Per-directive `\clearpage`, `{index}` entries and `(Interface*)=` anchors.
- `{ref}` for cross-references, `{c:macro}` for constants and ioctl commands,
`{file}` for paths, `{c:func}` with parentheses for functions.
- reST `list-table` with `:class: rtems-table` for tables.
- 80 columns, SPDX `CC-BY-SA-4.0` header on every page.
- The label on the chapter index is `RTEMSGenericGPIOAPI`, reusing the
Doxygen `@defgroup` name from `cpukit/include/dev/gpio/gpio.h`, the way
`c-user/iodev/` reuses its own. The manual and the generated API reference
then agree.
## Verified
Both manuals build with **exit 0 and no new warnings against upstream's
baseline** -- the same toolchain was run on `main` first and the warning sets
compared, rather than a count being taken in isolation. `c-user` has 61
pre-existing warnings and `bsp-howto` 16; both are unchanged by these
commits.
## A question for the docs maintainers
`c-user` is largely generated from rtems-central spec items. `regulator` and
`iodev` are hand-written, so it has been done by hand before, and that is
what these follow. If spec items are wanted instead, I would rather know
before this goes any further -- the content would carry over, but the form
would not.
--
View it on GitLab:
https://gitlab.rtems.org/rtems/docs/rtems-docs/-/merge_requests/265
You're receiving this email because of your account on gitlab.rtems.org.
Unsubscribe from this thread:
https://gitlab.rtems.org/-/namespace/19/sent_notifications/5-afw6lin5uxeimxg6sysip3sjk-j/unsubscribe
| Manage all notifications: https://gitlab.rtems.org/-/profile/notifications |
Help: https://gitlab.rtems.org/help
_______________________________________________
bugs mailing list
[email protected]
http://lists.rtems.org/mailman/listinfo/bugs
