Re: [I] [FEATURE] Nuttx Documentation improvemet [nuttx]
michallenc commented on issue #16432:
URL: https://github.com/apache/nuttx/issues/16432#issuecomment-2907727108
> As far as I remember Gregory was always against cluttering the code with
metadata comments like Doxygen. Personally I agree with this view. The code
should first be readable by users, not generators. Unfortunately this makes
auto-generating API documentation not so easy.
That's a fair point, but we already have comments in the code (include large
blocks for functions). There isn't much difference in readability between,
let's say.
```
begin_packed_struct struct adc_msg_s
{
uint8_t am_channel; /* The 8-bit ADC Channel */
int32_t am_data; /* ADC convert result (4 bytes) */
} end_packed_struct;
```
and
```
begin_packed_struct struct adc_msg_s
{
/*! The 8-bit ADC Channel */
uint8_t am_channel;
/*! ADC convert result (4 bytes) */
int32_t am_data;
} end_packed_struct;
```
Yes, it can get a bit messy when referencing other structures, functions,
members, etc (`@ref xyz` etc). But maybe the public API is not as critical for
automatic generation, because we don't expect it to change.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
Re: [I] [FEATURE] Nuttx Documentation improvemet [nuttx]
raiden00pl commented on issue #16432: URL: https://github.com/apache/nuttx/issues/16432#issuecomment-2907715350 As far as I remember Gregory was always against cluttering the code with metadata comments like Doxygen. Personally I agree with this view. The code should first be readable by users, not generators. Unfortunately this makes auto-generating API documentation not so easy. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
Re: [I] [FEATURE] Nuttx Documentation improvemet [nuttx]
michallenc commented on issue #16432: URL: https://github.com/apache/nuttx/issues/16432#issuecomment-2907701792 Jumping a bit late to the discussion, but where do we stand with autogenerated API documentation? Pages like [this](https://nuttx.apache.org/docs/latest/components/drivers/character/analog/adc/index.html) would benefit from having doxygen (or else) comments for structures, enums, defines, etc. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
Re: [I] [FEATURE] Nuttx Documentation improvemet [nuttx]
raiden00pl commented on issue #16432: URL: https://github.com/apache/nuttx/issues/16432#issuecomment-2907629884 `mySt` is just a workaround to support legacy documentation format that is slowly being migrated to rst. Once everything is migrated, it should be removed. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
Re: [I] [FEATURE] Nuttx Documentation improvemet [nuttx]
abisop commented on issue #16432: URL: https://github.com/apache/nuttx/issues/16432#issuecomment-2907608665 @acassis @raiden00pl Should we add "edit on github" option. this will allow people to edit easily. So if someone finds small typo they will be able to add PR for change with ease -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
Re: [I] [FEATURE] Nuttx Documentation improvemet [nuttx]
abisop commented on issue #16432: URL: https://github.com/apache/nuttx/issues/16432#issuecomment-2907607954 > We currently use several features in Sphinx that are not available by default in Markdown like cross-referencing or TOC generation, so this is not so simple migration even if we agree to this. @raiden00pl sphinx supports using using markdown and rst together. And someone also added this in nuttx provided by mySt parser.(ref -> [conf.py](https://github.com/apache/nuttx/blob/master/Documentation/conf.py)). Usign which we can use all features of rst. (Just did a test also). but it will be awkward to use both so lets got with rst for now.  -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
Re: [I] [FEATURE] Nuttx Documentation improvemet [nuttx]
raiden00pl commented on issue #16432: URL: https://github.com/apache/nuttx/issues/16432#issuecomment-2906951854 @abisop We currently use several features in Sphinx that are not available by default in Markdown like cross-referencing or TOC generation, so this is not so simple migration even if we agree to this. Sphinx is much more useful for creating complex documentation for such large projects like NuttX. If you look at the two functionally closest projects to NuttX, which are Zephyr and Linux, both use Sphinx for documentation. The same for mynewt, rterms and probably more. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
Re: [I] [FEATURE] Nuttx Documentation improvemet [nuttx]
acassis commented on issue #16432: URL: https://github.com/apache/nuttx/issues/16432#issuecomment-2906813197 @abisop I think your intention is good and we need people like you to improve NuttX, buf if you get some way to improve the site design without moving to Markdown it should be better. I agree that Markdown is more used than RST, but as Matteo pointed even old documentation needs to be converted to RST first. So, this way if in the future we decide to move to Markdown it is better to have a uniform and consistent RST documentation to be converted. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
Re: [I] [FEATURE] Nuttx Documentation improvemet [nuttx]
abisop commented on issue #16432: URL: https://github.com/apache/nuttx/issues/16432#issuecomment-2905922852 @raiden00pl @linguini1 I think writing markdown is easy and effective. So that new people can easily edit without fuzz Also js based static site generators use it. I am not here for rst vs markdown. You guys know better what is what... I have done my homework and this was my first assignment to improve docs please let me know... > [source](https://github.com/abisop/nuttx-docs.git) [Experimental Website](https://abisop.github.io/) You can try [edit on github]() on bottom of every page 💯 -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
Re: [I] [FEATURE] Nuttx Documentation improvemet [nuttx]
abisop commented on issue #16432: URL: https://github.com/apache/nuttx/issues/16432#issuecomment-2905875117 > Changing to Markdown doesn't feel like it brings any major advantages over RST, and would come with a ton of work moving over the existing documentation system I have converted .rst files to .md using automation (ref. -> pandoc and sed) some cleanup is needed that i will do > We haven't even managed to convert all the old README.txt files yet Thanks @linguini1 for pointing out this . In this case markdown shines as we can easily convert plain text to markdown Please visit [abisop.github.io](abisop.github.io) -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
Re: [I] [FEATURE] Nuttx Documentation improvemet [nuttx]
abisop commented on issue #16432: URL: https://github.com/apache/nuttx/issues/16432#issuecomment-2905896835 > -1. Spinx was chosen a long time ago and was just a replacement for Markdown and HTML. Going back to Markdown is unnecessary work that adds nothing to this project. Here is the topic on the mailing list: https://lists.apache.org/thread/25fb57pg1kdcjrv4m6vm4qhl8x225hsc @raiden00pl Thanks for pointing... I found that sir @gregory-nutt used to write docs in html which followed by use of reStructuredText. But markdown is different as we all know . We are not going back but with the trend where frameworks of js like vitepress are used for creating modular static websites by consuming markdown files. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
Re: [I] [FEATURE] Nuttx Documentation improvemet [nuttx]
linguini1 commented on issue #16432: URL: https://github.com/apache/nuttx/issues/16432#issuecomment-2905303739 I would also vote -1 on this. Changing to Markdown doesn't feel like it brings any major advantages over RST, and would come with a ton of work moving over the existing documentation system. We haven't even managed to convert all the old README.txt files yet (#11077) -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
Re: [I] [FEATURE] Nuttx Documentation improvemet [nuttx]
raiden00pl commented on issue #16432: URL: https://github.com/apache/nuttx/issues/16432#issuecomment-2905202513 -1. Spinx was chosen a long time ago and was just a replacement for Markdown and HTML. Going back to Markdown is unnecessary work that adds nothing to this project. Here is the topic on the mailing list: https://lists.apache.org/thread/25fb57pg1kdcjrv4m6vm4qhl8x225hsc -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
Re: [I] [FEATURE] Nuttx Documentation improvemet [nuttx]
abisop commented on issue #16432: URL: https://github.com/apache/nuttx/issues/16432#issuecomment-2905187761 @simbit18 I am not a web developer. But the process of static site generator + some custom automation is such that Now we have to write only markdown files and rest is taken care of. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
Re: [I] [FEATURE] Nuttx Documentation improvemet [nuttx]
simbit18 commented on issue #16432: URL: https://github.com/apache/nuttx/issues/16432#issuecomment-2903884057 https://github.com/apache/nuttx/issues/15893 -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
