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

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

AMarch01 — Wed, 18 Dec 2024 13:23:39 GMT

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

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

AMarch01 — Tue, 17 Dec 2024 14:01:46 GMT

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

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

runsiv — Tue, 17 Dec 2024 09:20:23 GMT

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

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

Will_20241202 — Mon, 16 Dec 2024 14:18:04 GMT

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:

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
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
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.)
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.?

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

AMarch01 — Mon, 16 Dec 2024 13:46:25 GMT

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

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

runsiv — Mon, 16 Dec 2024 06:45:31 GMT

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

Regards

Runar

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

AMarch01 — Fri, 13 Dec 2024 16:12:34 GMT

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.