doc: move wiki to Doxygen documentation (second attempt) by jia200x · Pull Request #8516 · RIOT-OS/RIOT

jia200x · 2018-02-05T13:03:38Z

Contribution description

This is a second attempt of moving Board specifications from Wiki to Doxygen. Replaces the work in #8508 .

Wiki entries were copied "as it" and referenced to the corresponding group, with the same format as existing Doxygen entries like Arduino MKRFOX1200
As said in the previous PR, the motivation is to help developers keeping an up-to-date End User documentation for each board without adding too much overhead, and help the End User to find all the documentation in the same place.

deduplicate @defgroup and @brief
remove tabs
split lines to fit 80 chars

NB tables doesn't work if splitted => NR > 80. Also, this PR doesn't intend to update information for each entry.

Some other issues addressed by this PR

Fix mulle todo block

Entries with broken imgs (addressed in further PRs)

arduino-mega2560
samd21-xpro
saml21-xpro
stm32f3discovery
z1

Following steps (PRs coming soon)

Add "Family" documentation (ARM, MSP430, etc).
Unify the current board documentation structure, so all boards have the same content (Hardware Description, Pin Mapping, Toolchain, etc).

Issues/PRs references

#8508

aabadie · 2018-02-05T13:37:41Z

Very nice ! I like it.

Unfortunately, with this PR, I think each board group definition (using @defgroup) is duplicated between the doc.txt and the board.h files: the board.h should be updated as well... for each board !

jia200x · 2018-02-05T14:18:49Z

@aabadie I think I found a way to automate that. I will try :)

kaspar030 · 2018-02-05T14:37:56Z

boards/airfy-beacon/doc.txt

+ * 
+ * ![airfy-beacon](https://raw.githubusercontent.com/wiki/RIOT-OS/RIOT/images/airfy-beacon.jpg)
+ * 
+ * | MCU 		| NRF51822QFAA 		|


should use spaces instead of tabs...

The original file in the wiki already contains the tabs, maybe the automatic script could also handle that. What do you think @jia200x ?

Bash magic may do the trick :)

expand may help here

aabadie

The board.h should be adapted as well (remove the @defgroup and @brief at the very beginning of the doxygen block.
Is your automatic script able to do that ?

aabadie · 2018-02-09T09:07:26Z

boards/airfy-beacon/doc.txt

+ * ## Overview
+ * 
+ * The Airfy Beacon is utilizing a Nordics NRF51822QFAA SoC.
+ * The SoC features 16Kb of RAM, 256Kb of flash ROM and comes on top of the usual micro-controller peripherals with a 2.4GHz radio that supports both Nordics proprietary ShockBurst as well as Bluetooth Low Energy (BLE).


It would be great to split the line so that they fit in the 80 characters maximum length. Do you think it's possible to adapt your script for this ?

yes, I think so

jia200x · 2018-02-09T09:55:29Z

@aabadie thanks a lot for reviewing!

jia200x · 2018-03-02T16:44:49Z

@aabadie @gebart could you help me with the review of this?

aabadie · 2018-03-02T17:03:40Z

boards/acd52832/doc.txt

@@ -0,0 +1 @@
+ */


Looks like a bug: your script is creating a doc.txt when the board is not documented in the code base and not present in the wiki. I saw a few others like this.

Yes, it's a bug. I will fix it when I'm back

aabadie · 2018-03-07T09:11:41Z

boards/iotlab-a8-m3/doc.txt

@@ -0,0 +1,4 @@
+/**
+ * @ingroup     boards_iotlab-m3


There is a problem here, the group should be boards_iotlaba-a8-m3. This is because the initial group of the A8 was invalid.

aabadie · 2018-03-07T09:14:01Z

boards/mulle/include/board.h

- *
- * @todo Work around missing RESET pin on Mulle v0.6x
+ * @{
+ */


Don't need to close the doxygen block here

I will try again, but I strange error on make doc without splitting this block. I will paste the results here

this is my output when I don't split the block:

( cat riot.doxyfile ; echo "GENERATE_HTML = yes" ) | doxygen - todo:17: warning: Unexpected character `b' todo:17: warning: Unexpected character `o' todo:17: warning: Unexpected character `a' todo:17: warning: Unexpected character `r' todo:17: warning: Unexpected character `d' todo:17: warning: Unexpected character `s' todo:17: warning: Unexpected character `/' todo:17: warning: Unexpected character `m' todo:17: warning: Unexpected character `u' todo:17: warning: Unexpected character `l' todo:17: warning: Unexpected character `l' todo:17: warning: Unexpected character `e' todo:17: warning: Unexpected character `/' todo:17: warning: Unexpected character `i' todo:17: warning: Unexpected character `n' todo:17: warning: Unexpected character `c' todo:17: warning: Unexpected character `l' todo:17: warning: Unexpected character `u' todo:17: warning: Unexpected character `d' todo:17: warning: Unexpected character `e' todo:17: warning: Unexpected character `/' sh: latex: no se encontró la orden error: Problems running latex. Check your installation or look for typos in _formulas.tex and check _formulas.log! sh: dvips: no se encontró la orden error: Problems running dvips. Check your installation! make[1]: se sale del directorio '/home/jialamos/Development/RIOT/doc/doxygen

Maybe a Doxygen bug?

What about moving the @todo before the @{ ?

same results. Does it work for you? Maybe my Doxygen version has a bug

You can drop the todo. It's not important

I also have the issue, but it works with the actual version of your branch. So let's keep it like this

or maybe I just drop the @todo as @gebart proposed, so the change is minimal

aabadie · 2018-03-07T09:14:12Z

boards/mulle/include/board.h

+ * @{
+ */
+
+ /** @todo Work around missing RESET pin on Mulle v0.6x


and repoen it here

aabadie · 2018-03-07T09:16:32Z

boards/nucleo144-f413/include/periph_conf.h

- * @defgroup    boards_nucleo144-f413 STM32 Nucleo144-F413
- * @ingroup     boards_common_nucleo144
- * @brief       Support for the STM32 Nucleo144-F413
+ * @ingroup     boards__nucleo144-f413common_nucleo144


Looks like a bug here

thanks for pointing it out

aabadie · 2018-03-07T09:17:00Z

boards/nucleo144-f429/include/periph_conf.h

- * @defgroup    boards_nucleo144-f429 STM32 Nucleo144-F429
- * @ingroup     boards_common_nucleo144
- * @brief       Support for the STM32 Nucleo144-F429
+ * @ingroup     boards__nucleo144-f429common_nucleo144


here as well

aabadie · 2018-03-07T09:18:12Z

boards/nz32-sc151/include/periph_conf.h


 /**
- * @ingroup     nz32-sc151
+ * @ingroup     boards_nz32-sc151


Wasn't this fixed already in master ?

yes, forgot to rebase

aabadie · 2018-03-07T09:20:03Z

boards/remote-reva/include/board.h

- * @defgroup    boards_reva RE-Mote Revision A
- * @ingroup     boards
- * @brief       Support for the RE-Mote board Revision A
+ * @ingroup     boards_reva


The original group name of this board could have been more specific and then consistent with other remote boards: boards_remote-reva

aabadie · 2018-03-07T09:20:55Z

boards/spark-core/doc.txt

@@ -0,0 +1,121 @@
+pause/*2


I was suffering this bug in my local vim.

aabadie · 2018-03-07T09:34:22Z

@jia200x, I opened #8748 and #8749 for the problem found with doxygen groups.

Otherwise, this PR is getting close from being merged I think. Unfortunately (for me), it will conflict a lot with #8649 #8650 and #8651 since they touch the same parts of the code. But we should merge your PR first because mines are changing the doxygen group names of the boards and I think your automatic script will not work anymore if we merge them first.

jia200x · 2018-03-07T10:32:26Z

@jia200x, I opened #8748 and #8749 for the problem found with doxygen groups. Otherwise, this PR is getting close from being merged I think. Unfortunately (for me), it will conflict a lot with #8649 #8650 and #8651 since they touch the same parts of the code. But we should merge your PR first because mines are changing the doxygen group names of the boards and I think your automatic script will not work anymore if we merge them first.

Great. OK, I will try to fix these issues asap and contribute to merge the other PRs.

Regarding the changes of ST platforms, it seems the problem would be solved with a small script that moves @defgroup and @brief from periph_conf.h to doc.txt. Not sure if there are any other files to update.
What do you think?

aabadie · 2018-03-07T12:37:36Z

I built locally the documentation to have a look at the result. My first impression is that the board documentation is making a big step forward.

Some problems:

some table cells are missing sometimes
the size of some images could be adjusted (maybe in follow-up PRs)
some links to board images are broken (stm32f3disco)
doxygen groups are invalid for some Nucleo boards

jcarrano

Ok. Code is not changed, should not break anything. If we don't merge this people will continue to modify the wiki and this PR will drag on forever.

jia200x · 2018-07-26T14:06:14Z

@miri64 @smlng are you ok with the actual state?

smlng · 2018-07-30T12:16:47Z

side note: images for samd21 and saml21 are not working anymore (broken in wiki, too) because microchip overtook atmel. I fixed in the wiki, so you might want to update this here too?

jia200x · 2018-07-30T12:17:39Z

side note: images for samd21 and saml21 are not working anymore (broken in wiki, too) because microchip overtook atmel. I fixed in the wiki, so you might want to update this here too?

Good catch. Thanks

Sure, no problem

jcarrano · 2018-07-30T12:21:56Z

images for samd21 and saml21 are not working anymore

We should not be deep-linking content.

smlng · 2018-07-30T12:42:48Z

@jcarrano I agree, but currently we have no common strategy where to put or link images to/from - I guess copyright might be an issue, so putting them into the repo is not an option I guess.

Hence, for now it was the easiest (and quickest) to fix the links by replacing the URLs.

jia200x · 2018-08-01T13:27:53Z

@smlng alles gut. Fixed SAML21 and SAMD21 entries.

jia200x · 2018-08-02T16:27:11Z

ping @miri64

As I only asked for a community discussion that wasn't really picked up on, I won't block this PR (sorry for doing this earlier).

jia200x · 2018-08-07T11:19:42Z

As I only asked for a community discussion that wasn't really picked up on, I won't block this PR (sorry for doing this earlier).

No problem! :) Then, let's merge

aabadie · 2018-08-07T11:28:30Z

Finally !!!

smlng · 2018-08-07T11:33:54Z

Nice works, congrats @jia200x

jia200x · 2018-08-07T11:49:22Z

Thank you to all people involved! I will put deprecation warnings in the wiki's board entries

miri64 · 2018-08-07T11:51:47Z

I will put deprecation warnings in the wiki's board entries

But please with link to knew place ;-) (I think http://doc.riot-os.org/group__boards.html should suffice).

jia200x mentioned this pull request Feb 5, 2018

[RFC-WIP] docs: move wiki's Board documentation to Doxygen #8508

Closed

3 tasks

jia200x requested review from aabadie and smlng February 5, 2018 13:06

jia200x added Area: doc Area: Documentation Type: enhancement The issue suggests enhanceable parts / The PR enhances parts of the codebase / documentation labels Feb 5, 2018

jia200x mentioned this pull request Feb 5, 2018

documentation: better end-user documentation and learning resources #8479

Open

20 tasks

kaspar030 requested changes Feb 5, 2018

View reviewed changes

aabadie requested changes Feb 9, 2018

View reviewed changes

PeterKietzmann mentioned this pull request Feb 19, 2018

boards: jiminy-mega256rfr2: initial support #7738

Closed

jia200x added Community: Hack'n'ACK candidate This PR is a candidate for review and discussion during one of RIOT's monthly Hack'n'ACK parties CI: needs squashing Commits in this PR need to be squashed; If set, CI systems will mark this PR as unmergable labels Feb 27, 2018

aabadie reviewed Mar 2, 2018

View reviewed changes

aabadie reviewed Mar 7, 2018

View reviewed changes

boards/mulle/include/board.h

* @{

*/

/** @todo Work around missing RESET pin on Mulle v0.6x

Copy link
Copy Markdown

Contributor

aabadie Mar 7, 2018

Choose a reason for hiding this comment

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

and repoen it here

aabadie reviewed Mar 7, 2018

View reviewed changes

This was referenced Mar 7, 2018

boards/remote*: fix doxygen grouping #8748

Merged

boards/iotlab-a8-m3: fix doxygen grouping #8749

Merged

jia200x force-pushed the wiki_dox_convertion branch from 4a4f8ab to f5e73b9 Compare March 7, 2018 10:41

jia200x force-pushed the wiki_dox_convertion branch 4 times, most recently from 879244d to b3516a2 Compare July 26, 2018 13:32

jcarrano approved these changes Jul 26, 2018

View reviewed changes

smlng approved these changes Jul 30, 2018

View reviewed changes

jia200x added 3 commits August 1, 2018 15:24

doc: add wiki documentation to Doxygen files

a1e17ab

boards: fix Doxygen group directives

7b28fbf

boards/periph_conf: fix Doxygen group directives

2531487

jia200x force-pushed the wiki_dox_convertion branch from b3516a2 to 2531487 Compare August 1, 2018 13:27

miri64 added CI: ready for build If set, CI server will compile all applications for all available boards for the labeled PR and removed CI: ready for build If set, CI server will compile all applications for all available boards for the labeled PR labels Aug 2, 2018

MrKevinWeiss merged commit 8468fe1 into RIOT-OS:master Aug 7, 2018

aabadie mentioned this pull request Aug 10, 2018

boards*: documentation cleanup #9757

Merged

basilfx mentioned this pull request Aug 16, 2018

boards: slstk3402a: add docs #9791

Merged

aabadie mentioned this pull request Jul 7, 2019

boards/nucleo*: move doxygen group definition to doc.txt #11812

Merged

jia200x mentioned this pull request Jan 26, 2023

treewide: rename doc.txt -> doc.md #19114

Closed

Conversation

jia200x commented Feb 5, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Contribution description

Some other issues addressed by this PR

Entries with broken imgs (addressed in further PRs)

Following steps (PRs coming soon)

Issues/PRs references

Uh oh!

aabadie commented Feb 5, 2018

Uh oh!

jia200x commented Feb 5, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aabadie left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jia200x commented Feb 9, 2018

Uh oh!

jia200x commented Mar 2, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aabadie commented Mar 7, 2018

Uh oh!

jia200x commented Mar 7, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jia200x commented Feb 5, 2018 •

edited

Loading

jia200x commented Mar 2, 2018 •

edited

Loading

jia200x commented Mar 7, 2018 •

edited

Loading

aabadie commented Mar 7, 2018 •

edited

Loading