Skip to content

doc: Make bootloaders visible in modules#16025

Merged
miri64 merged 2 commits intoRIOT-OS:masterfrom
chrysn-pull-requests:bootloader-docs
Feb 18, 2021
Merged

doc: Make bootloaders visible in modules#16025
miri64 merged 2 commits intoRIOT-OS:masterfrom
chrysn-pull-requests:bootloader-docs

Conversation

@chrysn
Copy link
Copy Markdown
Member

@chrysn chrysn commented Feb 16, 2021

Contribution description

Currently, documentation about the bootloaders is only accessible through the source tree and not through the API documentation.

This adds the bootloaders/ directory to the list of starting points for doxygen, and moves the riotboot documentation into a place where doxygen can pick it up. Some metadata is added to make it fit nicely.

Testing procedure

  • Open the documentation search for "bootloader".
  • Since this change, a section shows up (also in the modules list) that currently contains only riotboot

Issues/PRs references

  • The current form of riotboot: Mode selection for boards #16011 adds board defines that influence how the bootloader is used; until this is merged, they are not visibly documented.
  • Further work seems indicated to document the DFU based bootloader (currently blank), and to make the riotboot docs more newcomer friendly in general. (They describe how it works, but not why it's done (to enable further modules like SUIT to do the actual uploads, or DFU uploads), or how to use it when one does not already have a progammer attached anyway)

@chrysn chrysn added Type: enhancement The issue suggests enhanceable parts / The PR enhances parts of the codebase / documentation Area: doc Area: Documentation CI: ready for build If set, CI server will compile all applications for all available boards for the labeled PR CI: skip compile test If set, CI server will run only non-compile jobs, but no compile jobs or their dependent jobs labels Feb 16, 2021
@kaspar030 kaspar030 removed the CI: ready for build If set, CI server will compile all applications for all available boards for the labeled PR label Feb 16, 2021
chrysn added a commit to chrysn-pull-requests/RIOT that referenced this pull request Feb 16, 2021
@chrysn
fixup! riotboot_dfu: Stay in DFU mode if button is pressed
1a54d45 
... now that with RIOT-OS#16025 it can actually be rendered to the docs, a few
shortcomings got visible.
@chrysn chrysn mentioned this pull request Feb 16, 2021
Merged
jeandudey
jeandudey reviewed Feb 17, 2021
View reviewed changes
Copy link
Copy Markdown
Contributor

@jeandudey jeandudey left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On doxygen 1.8.3 gives the following warning (don't know if this is present on a recent release):

"make" -BC doc/doxygen
make[1]: Entering directory '/home/jeandudey/Dev/RIOT/doc/doxygen'
( cat riot.doxyfile ; echo "GENERATE_HTML = yes" ) | doxygen -
/home/jeandudey/Dev/RIOT/bootloaders/riotboot/doc.txt:110: warning: unable to resolve reference to `https:' for \ref command
*make[1]: Leaving directory '/home/jeandudey/Dev/RIOT/doc/doxygen'

It may be a bug on the Doxygen parser, I've got to silence it by using an a tag instead :-)

diff --git a/bootloaders/riotboot/doc.txt b/bootloaders/riotboot/doc.txt
index c3845fef9f..caa3d29e33 100644
--- a/bootloaders/riotboot/doc.txt
+++ b/bootloaders/riotboot/doc.txt
@@ -107,7 +107,7 @@ flash` if the `riotboot` feature is used.
 
 ## Testing riotboot
 
-See [tests/riotboot/README.md](https://github.com/RIOT-OS/RIOT/blob/master/tests/riotboot/README.md).
+See <a href="https://github.com/RIOT-OS/RIOT/blob/master/tests/riotboot/README.md">tests/riotboot/README.md</a>
 
 # Quick riotboot porting guide

@chrysn
Copy link
Copy Markdown
Member Author

chrysn commented Feb 17, 2021

I feel reaffirmed in my distinct dislike for all the tools that use markdown with its sloppy specification(s), especially when they try to use links in a way that they are not only URI references but possibly something different.

The misbehavior does not occur with the Doxygen 1.9 I'm using (which also does a better job at not making headings into an auto-brief).

I'm adding a commit with the necessary changes to work around it, and keeping it separate so that when RIOT-OS/riotdocker#104 is done, it can be reverted.

chrysn added a commit to chrysn-pull-requests/RIOT that referenced this pull request Feb 17, 2021
@chrysn
doc: Workarounds for Doxygen 1.8
a1e4b41 
See-Also: RIOT-OS#16025 (review)
Workaround-For: RIOT-OS/riotdocker#104
jeandudey
jeandudey approved these changes Feb 17, 2021
View reviewed changes
Copy link
Copy Markdown
Contributor

@jeandudey jeandudey left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tested building the documentation, bootloaders show up :-)

Docs preview

Screenshot from 2021-02-17 10-04-54

chrysn added a commit to chrysn-pull-requests/RIOT that referenced this pull request Feb 18, 2021
@chrysn
doc: Workaround for Doxygen 1.8
9304467 
See-Also: RIOT-OS#16025 (review)
Workaround-For: RIOT-OS/riotdocker#104
@chrysn chrysn added the CI: ready for build If set, CI server will compile all applications for all available boards for the labeled PR label Feb 18, 2021
@chrysn
Copy link
Copy Markdown
Member Author

chrysn commented Feb 18, 2021

During squashing and test runs I found that riotboot/main.c had a conflicting defgroup; removed that as while we can have documentation in .c files, it's not the most intuitive place to find high-level groups in.

@miri64 miri64 merged commit 6b8cb2a into RIOT-OS:master Feb 18, 2021
@chrysn chrysn deleted the bootloader-docs branch February 19, 2021 10:59
@kaspar030 kaspar030 added this to the Release 2021.04 milestone Apr 23, 2021
@chrysn chrysn added the Release notes: added Set on PRs that have been processed into the release notes for the current release. label Apr 28, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@jeandudey jeandudey jeandudey approved these changes

@aabadie aabadie Awaiting requested review from aabadie aabadie is a code owner

@jia200x jia200x Awaiting requested review from jia200x jia200x is a code owner

Assignees

No one assigned

Labels

Area: doc Area: Documentation CI: ready for build If set, CI server will compile all applications for all available boards for the labeled PR CI: skip compile test If set, CI server will run only non-compile jobs, but no compile jobs or their dependent jobs Release notes: added Set on PRs that have been processed into the release notes for the current release. Type: enhancement The issue suggests enhanceable parts / The PR enhances parts of the codebase / documentation

Projects

None yet

Milestone

Release 2021.04

Development

Successfully merging this pull request may close these issues.

4 participants

@chrysn @jeandudey @miri64 @kaspar030