Ah sorry I just jumped in to reading :-) As Ludovic pointed out it is possible to do a live preview. We use Sphinx for documentation. HTML preview is generated quickly and smoothly :-)
Sphinx is very nice and have tons of features (through plugins/modules). I use it in my projects too. The RST is abit more complex than MD but allows corss-references and has many more features so I learn this RST too :-) https://www.sphinx-doc.org/en/master/index.html It is possible to install plugin to convert MD to RST in case of old documentations to be processed by Sphinx. But I would advise to stick to RST. Even GitHub can render README.rst as a simple preview (tables, lists, code, etc) but refs does not work there. Another thing with Sphinx is that it can also create code documentation like Doxygen.. and in fact it does use Doxygen below to only generate XML and then parse this XML from Doxygen in order to render API documentation. This can be then attached in some place of larger documentation which was not easily possible in pure Doxygen. Another story is about LaTeX.. I want NuttX to have PDF Handbook generated too for offline work and as part of releases.. there was initial prototype created and it works. But local LaTeX setup is complex and heavy and in search for alternatives I found.. ehm Rust written tiny PDF generator called TYPST.. but its not yet integrated with Sphinx and has its own syntax that is not compatible with LaTeX, MD, RST (yet) :-P For people that want to quickly generate any kind of PDF (i.e. automation) this may be good utility though.. and templates generation/application is a lot easier than LaTeX :-) https://typst.app/ -- CeDeROM, SQ7MHZ, http://www.tomek.cedro.info On Wed, Nov 26, 2025 at 9:14 PM Tim Hardisty <[email protected]> wrote: > > Aha - thanks for that :-) > > On 26/11/2025 20:11, Ludovic Vanasse wrote: > > Ah, just the autorebuild part: > > > > DOCUMENTATION — NUTTX LATEST DOCUMENTATION > > https://nuttx.apache.org/docs/latest/contributing/documentation.html#live-rebuild > > > > > > For me, I was doing the work in VSCode also and just having my browser > > on the side where the preview would be. > > > > __ > > > > Ludovic Vanasse > > > > [email protected] > > > > On 2025-11-26T15:09:16.000-05:00, Tim Hardisty > > <[email protected]> wrote: > > > >> I simply follow: > >> https://nuttx.apache.org/docs/latest/contributing/documentation.html > >> > >> This is a PITA as you can't just make a change and expect it to be OK. I > >> started working on a simple documentation mod just the other day - in VS > >> Code - but the RST previewers online or within VS Code failed to render > >> the ^ subsubsection as expected. Can do without that hassle. > >> > >> Maybe there's a better editor for documentation than what I'm using - > >> and not sure, really, what you are referring to here? > >> > >> On 26/11/2025 20:01, Ludovic Vanasse wrote: > >>> Having done a bit of documentation rework in the past. There's a > >>> hot reload function in the documentation generation. It'll start a > >>> rebuild and refresh the page with the new edit. I thought it was > >>> pretty convenient on my machine and we have the Nix devshell for > >>> it also, so no need to install anything else than Nix.. Hope this > >>> helps :). __ Ludovic Vanasse [email protected] On > >>> 2025-11-26T14:06:54.000-05:00, Tim Hardisty > >>> <[email protected]> wrote: > >>> > >>>> This would need only a trivial change to documentation, which > >>>> then doesn't need a full RST build/check I would think. On > >>>> 26/11/2025 19:04, Tim Hardisty wrote: > >>>> > >>>>> Think my message passed yours in the ether...yes; that's what > >>>>> I'm suggesting :-) On 26/11/2025 19:02, Alan C. Assis wrote: > >>>>> > >>>>>> I think what we are calling "Strict Priority" is defined by > >>>>>> POSIX as SCHED_FIFO. SCHED_FIFO: The thread runs until it > >>>>>> blocks itself or it is preempted by a higher priority > >>>>>> thread. (This is what you want). SCHED_RR: The thread runs > >>>>>> until the above happens *OR* its time slice (200ms) expires. > >>>>>> So, we could create a choice in the menuconfig with these > >>>>>> three options: SCHED_FIFO SCHED_RR SCHED_SPORADIC If > >>>>>> SCHED_FIFO is selected, the RR_INTERVAL is set to 0. If > >>>>>> SCHED_RR is selected the option to set RR_INTERVAL value > >>>>>> will show up. What do you think? BR, Alan On Wed, Nov 26, > >>>>>> 2025 at 3:40 PM Alan C. Assis <[email protected]> wrote: > >>>>>> > >>>>>>> Do you suggest moving from RST to Markdown? I think > >>>>>>> SCHED_PRIORITY is not a standard definition, at least I > >>>>>>> didn't find it in POSIX. You can propose using RR slice > >>>>>>> equal 0 by default, but I don't know the side effects (it > >>>>>>> could be considered a breaking change, because some user > >>>>>>> applications could stop working or behave strangely). BR, > >>>>>>> Alan On Wed, Nov 26, 2025 at 3:27 PM Tim Hardisty > >>>>>>> <[email protected]> wrote: > >>>>>>> > >>>>>>>> I don't mind doing documentation - but it does take a > >>>>>>>> lot more effort since RST doesn't have very good > >>>>>>>> previewers that I have found: it is difficult to know if > >>>>>>>> will it render correctly on the website unless you do > >>>>>>>> the whole RST build stuff. Quicker - if agreeable as a > >>>>>>>> short term fix - would be to add a Kconfig option to > >>>>>>>> specifically choose the scheduling option, with an > >>>>>>>> appropriate CONFIG_RR_INTERVAL setting of 0 for > >>>>>>>> SCHED_PRIORITY or 200ms for SCHED_RR? That would mean no > >>>>>>>> code changes as such? Something like that anyway. If it > >>>>>>>> fixes my issue, I can play with this and do a PR On > >>>>>>>> 26/11/2025 18:16, Alan C. Assis wrote: > >>>>>>>> > >>>>>>>>> Guess what? We are still missing a proper > >>>>>>>>> Documentation! :-) BR, Alan On Wed, Nov 26, 2025 at > >>>>>>>>> 3:11 PM Tim Hardisty <[email protected]> wrote: > >>>>>>>>> > >>>>>>>>>> So do we agree the documentation is at best > >>>>>>>>>> misleading? And, to me, simply wrong? On 26/11/2025 > >>>>>>>>>> 18:07, Alan C. Assis wrote: > >>>>>>>>>> > >>>>>>>>>>> Exactly! You can refer to > >>>>>>>>>>> sched/sched/sched_timerexpiration.c line 207 On > >>>>>>>>>>> Wed, Nov 26, 2025 at 3:00 PM Tim Hardisty > >>>>>>>>>>> <[email protected] wrote: > >>>>>>>>>>> > >>>>>>>>>>>> That's what I inferred (yet to try it) - so is > >>>>>>>>>>>> the documentation misleading since the default > >>>>>>>>>>>> CONFIG_RR_INTERVAL=200 forces RR > >>>>>>>> scheduling > >>>>>>>> > >>>>>>>>>>>> rather than the stated "strict priority > >>>>>>>>>>>> scheduling"? On 26/11/2025 17:54, Alan C. Assis > >>>>>>>>>>>> wrote: > >>>>>>>>>>>> > >>>>>>>>>>>>> CONFIG_RR_INTERVAL=0 On Wed, Nov 26, 2025 at > >>>>>>>>>>>>> 2:22 PM Tim Hardisty < > >>>>>>>> [email protected]> > >>>>>>>> > >>>>>>>>>>>>> wrote: > >>>>>>>>>>>>> > >>>>>>>>>>>>>> Apologies if this isn't really a NuttX > >>>>>>>>>>>>>> question... Documentation says "By default, > >>>>>>>>>>>>>> NuttX performs strict priority > >>>>>>>>>>>> scheduling". > >>>>>>>>>>>> > >>>>>>>>>>>>>> Default CONFIG_RR_INTERVAL is 200ms. I have > >>>>>>>>>>>>>> multiple threads, but have not set any > >>>>>>>>>>>>>> scheduling > >>>>>>>> parameters, > >>>>>>>> > >>>>>>>>>> but > >>>>>>>>>> > >>>>>>>>>>>>>> it seems threads are being scheduled every > >>>>>>>>>>>>>> 200ms rather on a > >>>>>>>> priority > >>>>>>>> > >>>>>>>>>>>>>> basis. What *should* I be doing, please, to > >>>>>>>>>>>>>> get all my threads scheduled > >>>>>>>> by > >>>>>>>> > >>>>>>>>>>>>>> priority? Thanks, TimH PS - yes I have > >>>>>>>>>>>>>> thrown myself in the deep end without a life > >>>>>>>>>>>>>> jacket > >>>>>>>>>> with > >>>>>>>>>> > >>>>>>>>>>>>>> my project. And I'm no doubt up ****-creek > >>>>>>>>>>>>>> without a paddle. But I > >>>>>>>> am > >>>>>>>> > >>>>>>>>>>>>>> always learning! > >
