How do I view the "pretty" version of README.rst?

[Will_20241202]

It seems like most or all of the sample code contains README.rst files as their documentation.  What is the preferred/suggested way to view these in rendered (i.e. not raw markup text) form?  I've tried Firefox, Microsoft Edge, VS Code, etc. and they all show the raw markup text instead of what I assume should be nicely formatted pages.

[runsiv]

Hi

You can try some of the restructured text extensions and see if you prefer that view.  

Regards

Runar

[Will_20241202]

Echoing AMarch01, I looked into a handful of the extensions and the ones I tried had all dropped support for "previewing" the RST files and only had support for editing and creating full blown projects.

I consider it a _SERIOUS_ shortcoming to a product line when the documentation for the _EXAMPLES_ requires creation of its own project and build chain to even view it.  Especially when there is no documentation on how to do that!  Turtles all the way down...

in 2024 it should not be asking much for documentation to be provided in one (or more) of the following forms, listed in order of preference:

1. PDF
   1. + easy to access offline (save locally)
   2. + easy to search
   3. + allows for complex formatting and embedded content
   4. + accessible on all major operating systems
2. offline HTML or other _common_ markup language
   1. + doesn't rely on servers staying up/accessible/in the same location
   2. + allows for complex formatting and embedded content
   3. - not always guaranteed to look the same on all platforms
   4.  - may break if viewer's security settings are anything but the most lax
   5. - information usually split across multiple pages so searching is hit or miss
3. offline plain text
   1. + doesn't rely on servers staying up/accessible/in the same location
   2. + guaranteed to look the same on all platforms
   3. - doesn't support fancy formatting or embedded content (pictures, plots, etc.)
4. online HTML or other _common_ markup language
   1. --- relies on servers staying up/accessible/not reorg'ed! Rarely seems to survive more than a year or two in my experience.
   2.  + allows for complex formatting and embedded content
   3.  - not always guaranteed to look the same on all platforms
   4.  - may break if viewer's security settings are anything but the most lax.
   5.  - information usually split across multiple pages so searching is hit or miss

</rant>

Circling back to my original question, how does Nordic Semiconductor recommend/expect/envision their customers access the provided documentation for the example code, etc.?

[runsiv]

Thank you for your input

Just to start with the original question. I think it depends on how people work. Just to use myself as an example I would open it to the side in VScode as text. VScode supports the formatting and the readability is good(in my opinion and embedded links and so on works).  You can also view the the documentation on the our website for all samples. 

RST is a normal format for documentation as is for example used for the Python documentation. In general I would say there is multiple ways of viewing the samples documentation. The readme in the sample itself, our documentation website and if you prefer a pdf it is possible to download from the website. 

I will forward the feedback internally 

Regards

Runar

[AMarch01]

I have VSCode, it shows it and highlights items but doesn't really format it for me. I guess that is some kind of support extension I am reluctant to use. 

All these years working with python, I have never looked at python documentation. I have seen discussions but never used it. How sad is that. Python was always just a thing to create scripts with. Documentation was always a text README next to it.

Looks like the proper way to go is to look into some primers on Python self-documenting code. Guess I will have to dumb all my rust knowledge to make space.

Time to start reading
reStructuredText markup

[AMarch01]

I guess the best way to read these are online - if only the files made html links to these pages.
TF-M Hello World