apache
[FEATURE] NuttX Documentation improvement
Is your feature request related to a problem? Please describe.
Documentation improvement
Describe the solution you'd like
I am proposing to use Markdown for documentation.
Why Markdown :
- Its easy to use in daily routine
- Supported by modern js frameworks (In this case -> vitepress)
- We can leverage many graphical UI features using pt. 2 . (Inspiration - PX4-Autopilot)
Here i am attaching source and website link : source Experimental Website - Please visit and give your feedbacks
[Note] : Content is converted from rst to markdown format using automation. It needs some work
Describe alternatives you've considered
No response
Verification
- [x] I have verified before submitting the report.
@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. Also UI can be changed. But I got the minimalistic things done.
-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
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)
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 website
-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.
@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...
You can try edit on github on bottom of every page 💯
@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.
@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.
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). 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.
@acassis @raiden00pl Should we add "edit on github" option. this will allow people to edit easily. So if someone finds evan a small typo they will be able to add PR for change with ease.
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.
Jumping a bit late to the discussion, but where do we stand with autogenerated API documentation? Pages like this would benefit from having doxygen (or else) comments for structures, enums, defines, etc.
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.
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.