CMake comments to HTML? (PR #9947 CMake build architecture documentation)


Marc Herbert
 

I tried the “moderncmakedomain” sphinx extension to prototype extracting CMake comments into html and it seems to work, see screenshot and PR below.


Dave (cc:) seems to like it.

Just a quick hack for now, Linux only. Two questions:
- Is the approach generally acceptable? Notably: is sphinx-moderncmakedomain acceptable as an additional pip3 requirement?
- If yes then is Sebastian's PR #9947 the correct place for this? I asked him privately but he’s either off or busy. If yes then let’s discuss there and not on the mailing-list.


Cheers,

Marc


Begin forwarded message:

Subject: Re: [zephyrproject-rtos/zephyr] CMake build architecture documentation (#9947)
Date: 11 February 2019 at 16:21:45 GMT-8


This is what the above commit produces:


You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub, or mute the thread.



Nashif, Anas
 

I think this looks great.

 

9947 is not a PR, it is an enhancement issue, got me confused for a second. So it is an open enhancement issue with not PR associated with it, if you have something , send a PR please.

 

Anas

 

From: devel@... [mailto:devel@...] On Behalf Of Marc Herbert
Sent: Monday, February 11, 2019 7:45 PM
To: devel@...
Cc: Kinder, David B <david.b.kinder@...>
Subject: [Zephyr-devel] CMake comments to HTML? (PR #9947 CMake build architecture documentation)

 

I tried the “moderncmakedomain” sphinx extension to prototype extracting CMake comments into html and it seems to work, see screenshot and PR below.

 

 

Dave (cc:) seems to like it.

 

Just a quick hack for now, Linux only. Two questions:

- Is the approach generally acceptable? Notably: is sphinx-moderncmakedomain acceptable as an additional pip3 requirement?

- If yes then is Sebastian's PR #9947 the correct place for this? I asked him privately but he’s either off or busy. If yes then let’s discuss there and not on the mailing-list.

 

 

Cheers,

 

Marc

 



Begin forwarded message:

 

Subject: Re: [zephyrproject-rtos/zephyr] CMake build architecture documentation (#9947)

Date: 11 February 2019 at 16:21:45 GMT-8

 

 

This is what the above commit produces:


You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub, or mute the thread.

 


Marc Herbert
 

Thanks Anas!

 

Correct no PR yet, sorry for the confusion. This is still at the early prototype stage however there's already a demo git commit - the one that produced the screenshot - linked from https://github.com/zephyrproject-rtos/zephyr/issues/9947 and it should work "out of the box" on Linux. Ideas, suggestions and any other kind of feedback from anyone somewhat familiar with CMake or Sphinx and brave enough to review a few TODOs, FIXMEs and other question marks would be great already, thanks in advance. Github supports commenting on volatile commits for implementation details but higher level discussions are probably best "centralized" in an issue: 9947 or some (new?) other?

 

Cheers,

 

Marc

 

 

From: "Nashif, Anas" <anas.nashif@...>
Date: Monday, 11 February 2019 at 16:50
To: Marc Herbert <marc.herbert@...>, "devel@..." <devel@...>
Cc: "Kinder, David B" <david.b.kinder@...>
Subject: RE: CMake comments to HTML? (PR #9947 CMake build architecture documentation)

 

I think this looks great.

 

9947 is not a PR, it is an enhancement issue, got me confused for a second. So it is an open enhancement issue with not PR associated with it, if you have something , send a PR please.

 

Anas

 

From: devel@... [mailto:devel@...] On Behalf Of Marc Herbert
Sent: Monday, February 11, 2019 7:45 PM
To: devel@...
Cc: Kinder, David B <david.b.kinder@...>
Subject: [Zephyr-devel] CMake comments to HTML? (PR #9947 CMake build architecture documentation)

 

I tried the “moderncmakedomain” sphinx extension to prototype extracting CMake comments into html and it seems to work, see screenshot and PR below.

 

 

Dave (cc:) seems to like it.

 

Just a quick hack for now, Linux only. Two questions:

- Is the approach generally acceptable? Notably: is sphinx-moderncmakedomain acceptable as an additional pip3 requirement?

- If yes then is Sebastian's PR #9947 the correct place for this? I asked him privately but he’s either off or busy. If yes then let’s discuss there and not on the mailing-list.

 

 

Cheers,

 

Marc

 




Begin forwarded message:

 

Subject: Re: [zephyrproject-rtos/zephyr] CMake build architecture documentation (#9947)

Date: 11 February 2019 at 16:21:45 GMT-8

 

 

This is what the above commit produces:


You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub, or mute the thread.

 


Marc Herbert
 

There's an actual (and draft) PR now in case anyone else is interested in following this: https://github.com/zephyrproject-rtos/zephyr/pull/13805

 

Still just a demo.

 

Off the list now.

 

From: <devel@...> on behalf of Marc Herbert <marc.herbert@...>
Date: Monday, 11 February 2019 at 20:46
To: "Nashif, Anas" <anas.nashif@...>, "devel@..." <devel@...>
Cc: "Kinder, David B" <david.b.kinder@...>
Subject: Re: [Zephyr-devel] CMake comments to HTML? (PR #9947 CMake build architecture documentation)

 

Thanks Anas!

 

Correct no PR yet, sorry for the confusion. This is still at the early prototype stage however there's already a demo git commit - the one that produced the screenshot - linked from https://github.com/zephyrproject-rtos/zephyr/issues/9947 and it should work "out of the box" on Linux. Ideas, suggestions and any other kind of feedback from anyone somewhat familiar with CMake or Sphinx and brave enough to review a few TODOs, FIXMEs and other question marks would be great already, thanks in advance. Github supports commenting on volatile commits for implementation details but higher level discussions are probably best "centralized" in an issue: 9947 or some (new?) other?

 

Cheers,

 

Marc

 

 

From: "Nashif, Anas" <anas.nashif@...>
Date: Monday, 11 February 2019 at 16:50
To: Marc Herbert <marc.herbert@...>, "devel@..." <devel@...>
Cc: "Kinder, David B" <david.b.kinder@...>
Subject: RE: CMake comments to HTML? (PR #9947 CMake build architecture documentation)

 

I think this looks great.

 

9947 is not a PR, it is an enhancement issue, got me confused for a second. So it is an open enhancement issue with not PR associated with it, if you have something , send a PR please.

 

Anas

 

From: devel@... [mailto:devel@...] On Behalf Of Marc Herbert
Sent: Monday, February 11, 2019 7:45 PM
To: devel@...
Cc: Kinder, David B <david.b.kinder@...>
Subject: [Zephyr-devel] CMake comments to HTML? (PR #9947 CMake build architecture documentation)

 

I tried the “moderncmakedomain” sphinx extension to prototype extracting CMake comments into html and it seems to work, see screenshot and PR below.

 

 

Dave (cc:) seems to like it.

 

Just a quick hack for now, Linux only. Two questions:

- Is the approach generally acceptable? Notably: is sphinx-moderncmakedomain acceptable as an additional pip3 requirement?

- If yes then is Sebastian's PR #9947 the correct place for this? I asked him privately but he’s either off or busy. If yes then let’s discuss there and not on the mailing-list.

 

 

Cheers,

 

Marc

 





Begin forwarded message:

 

Subject: Re: [zephyrproject-rtos/zephyr] CMake build architecture documentation (#9947)

Date: 11 February 2019 at 16:21:45 GMT-8

 

 

This is what the above commit produces:


You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub, or mute the thread.