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.

[AMarch01]

If you do find a viewer, I would be interested. Something about the data tags in them leads me to suspect that they need compiled in some way.

[runsiv]

Hi

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

Regards

Runar

[AMarch01]

Yeah, I looked at one .... the reviews were not good. The whole thing seemed like it was too much effort to put into this level of text viewing. The whole thing seems geared to a web site engines and encodings. There is probably a reasonable answer to this level of effort put into the documents, but it would be nice if they would add a compiled pdf or some kind of easily readable text version for people who work mostly from the command line.
Maybe I am just too old.
AM

[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