Documentation improvement planning

[PhilippHaefele]

Hi together,

i open this issue to plan, discuss, collect things for an improvement of the documentation.

I‘m using an issue because it‘s better for discussion etc.

First of all i collect old issues regarding documentation (please comment if there‘re any missing that are currently not documented in the wiki:

• [ ] https://github.com/Marus/cortex-debug/issues/558#issuecomment-1004173498 -> Add hint for ,x etc
• [ ] #553& #188 -> Add hint on how to debug single core in multi core system
• [ ] #550 -> Add example to description in Wiki and maybe add FAQ entry? Or only FAQ?
• [ ] #549 -> SWO example
• [x] #515
• [ ] #511 -> State dependencies like libncurses somewhere; Maybe also a good example on how to deal with WSL for now?
• [ ] #510 -> State somewhere in the "theory of operations" what to do when user wants to setup GDBServer by himself
• [ ] #461 -> Not sure anymore if we should state something about that as it is very special. Maybe mention that using override commands is needed when using external server type operation
• [ ] #442 -> Describe attach and launch
• [ ] #400 -> FAQ (mention the words SRAM / ITCM RAM)
• [ ] #366 -> runToMain / runToEntryPoint are working after reset/restart now. At least in pre-release 1.1.1 => We just need to document that setting the temporary breakpoint can fail
• [ ] #352 -> add FAQ entry with J-Link Remote Server for that
• [ ] #332 -> Document how to use them -> link to VSCode documentation
• [ ] #323 -> add small entry on how to use different commands from command palette (maybe others too)
• [ ] #283 -> FAQ How to add multiple graphs (from different ITMChannel/ports)?
• [ ] #277 -> check old webpage content and look for any valuable description and example launch configuration
• [ ] #220 -> Has some good description on pitfalls/issues user can have with setting up SWO
• [ ] #200 -> debuggerArgs example in the wiki for using a .gdbinit file with a hint to not use continue in it
• [ ] #192 + #115 -> Check if behavior is already described enough in wiki
• [ ] #173 + #551 => example on how to use gdb console to read and write registers / REPL hint and link is a valuable info; registers moved to variables section in next release
• [ ] #139 => graphing is documented enough in wiki. So only last (some kind of off-topic) comment is relevant which are two feature request. Create two new issues for that?
• [ ] #111 => State somewhere how to handle different OS paths and give a hint that launch.json is much more flexible
• [ ] #105 => add FAQ entry for: Failed to get Stack Trace: Invalid thread id
• [ ] #104 => try to get an example (more easily to start) from somewhere. How is the javascript module supplied/imported? Additional extension?
• [x] #76 => stated enough in wiki? Maybe add to installation guide
• [ ] #59 => FAQ entry
• [ ] #55 => Something to mention as every new user is confused about that
• [ ] #36 => add some hint from here for how to use external server type
• [ ] #12 & #727 => see if all feature work with a Rust example and document it (e.g. the debug info enabling needed which is mentioned in both tickets)
• [ ] #1 => Maybe state current situation (no money) in What's new page and Wiki/README

I‘m also having thoughts about following things:

• [x] Add a "theory of operation" section with some diagrams
• [ ] "teach" users to use intelliSense
• [ ] Use debug_attributes.md as much as possible so we don‘t need to document things twice.
• [ ] extend IntelliSense examples (maybe some with RTT/SWO output/graphing)
• [x] Change Link for prebuild OpenOCD binaries to https://github.com/xpack-dev-tools/openocd-xpack/releases/ (at least for Linux and MacOS)
• [ ] Restructure wiki -> we have a lot of common settings and we most likely only need special hints on single parameters (sets) and maybe some special examples (others should be part of IntelliSense)
• [ ] Cleanup issues and mark open ones with labels, so users and contributors can more easily search trough them
• [x] Move OpenOCD build manual to a separate wiki page
• [ ] Add a what‘s new page to better inform users about changes e.g. https://github.com/alefragnani/vscode-whats-new
• [ ] Update screenshot in README.md
• [ ] Add animated gifs to documentation (e.g. created with https://www.screentogif.com/ + enableing screencast mode in VSCode) for things like command pallet
• [ ] Remove stale/unused branches => at least rtosSupport, serialport-v12.4.0, fix-webpacked-binary-module, fix-webpack-2, mp

That should be my first thoughts. Maybe not complete but i will update this post when working on the documentation.

Happy to receive any feedback or input :smile:

Best regards Philipp

[haneefdm]

@PhilippHaefele That is quite a list. Must have taken quite a bit of work to compile that. Thank you. A couple of comments

I would like to add a "theory of operations" sort of page, where we describe how the extension actually works -- the body parts (gdb, gdb-server, VSCode, etc.) and the process of how launch.json is used (including pre, default/override, post steps), etc. Some users think we interact directly with the HW (like IAR, Keil, etc.). Pictures are needed for this one.

I just pinned this issue

[haneefdm]

There is a problem with reliance on debug_attributes.md. package.json is not a good way of documenting anything in detail. So, a one-line has to do and it does help with IntelliSense. And, its duplicated (have to type it twice for most options).

Btw, I updated #55, #111, #183, #115, closed several

Btw, I don't get notifications on changes in the Wiki. So, when you are done, I will a look at everything.

Btw, if you see in the latest ChangeLog, we now support runToEntryPoint (sp?) for a Restart/Reset if setting a temporary breakpoint succeeds

[hongshui3000]

runToEntryPoint

@haneefdm When I reach the code "runToEntryPoint" position (my reset handler), I press the reset button again, and the code will run instead of still in the runToEntryPoint position

But when I stepinto (one step) and then reset, he can successfully reset and stop

[haneefdm]

@hongshui3000 Maybe I didn't understand your question.

After a reset the debugger may be showing a stale (old) stack-trace. This is what is reported by gdb. We report whatever location your gdb-server/gdb is showing. If you single-step however, things will look fine. We are trying to find a fix for this but it does not work across different types of gdb-servers and hardware.

This thread is not for asking questions like these though. I wish we had a Forum.

[haneefdm]

@PhilippHaefele FYI: I started a new page as I am implementing the feature. So, things are in flux.

https://github.com/Marus/cortex-debug/wiki/Multi-core-debugging

[haneefdm]

@PhilippHaefele Thanks again for all your help. I never imagined seeing such low numbers for open issues. There is now a new topic and I hope people will like it. I will push it out to a preview release soon.

https://github.com/Marus/cortex-debug/wiki/Disassembly-Debugging

Can't go in reverse -- from disassembly to source -- and you are supposed to be able to. Not sure why it is not working. People probably don't even know you can do that.

The UI is still pretty rough -- you will find out as you use it more and more. Sometimes, all of a sudden you get a second disassembly view. But moving through the stack frame and seeing the registers and the disassembly and source all getting updated was cool (for me at least).

[haneefdm]

I am thinking that maybe the Wiki could do with some organization. Right now, it is flat with an alphabetical list of topics. I am thinking we can just number them and they will at least fall into place (but still flat)

[sbixl]

Hi together, maybe it would be a good solution to carry over the wiki contents into ReStructuredText in order to use Sphinx as documentation generator. This has the advantage, that changes in the documentation can be reviewed in parallel to the changes in the code because the documentation ist stored in the same git repository. The generated documentation can then be uploaded at [1]. If required we can use github CI to build and upload the documentation automatically. I already use sphinx for documentation and I am very satisfied with the output. What do you think?

[1] https://readthedocs.org/

[PhilippHaefele]

Hi, didn't got that in mind for Cortex-Debug until now (as wiki was already there). Had a short look and i really like the version feature of Read the Docs, so users are able to get older documentation versions when needed. Also markdown should work as input.

Downside of having the documentation in this (or separate) repo will be that someone needs to review changes made by others. Not that bad, but still something to keep in mind.

I like the idea in general, but i'm not 100% sure if we should do it like this.

@haneefdm @Marus What do you think about the suggestion from sbixl?

@sbixl Thanks for your input

[haneefdm]

Thanks, I will look into Sphinx . @Marus will probably chime in. Where will the resulting docs hosted? Something like github.io?

Feels like stuff like Sphinx is more oriented towards API documentation rather than end-user users' manual kind of thing. Not saying you can't do both.

Caution: I don't own this repo. @Marus does.

[sbixl]

The resulting docs can (if you want) hosted at Read the Docs but you can als host it by using github.io. The benefit of using the first method is the possibility to access different versions of the documentation. If using github.io AFAIK, you only have access to the latest documentation.

Regarding the topic end-users users' manual while using Sphinx, I think it is good to show this with an example:

[1] Hosted documentation: https://bob-build-tool.readthedocs.io/en/latest/index.html [2] Source Repository: https://github.com/BobBuildTool/bob

If you have a look in [2] you will find a "doc" folder where the complete documentation is included.

[haneefdm]

Hi @PhilippHaefele, I added a chapter for an Overview of the debugging process and a pointer to it on the Home page. Let me know what you think. It was large enough that I downloaded I made a clone of the Wiki to edit.

https://github.com/Marus/cortex-debug/wiki/Overview

Let me know what you think, feel free to edit. I know have to cross-reference that page with other topics and there is some content missing.

[haneefdm]

Actually, do not edit the Overiew page yet. SInce everything is long lines, merging can be difficult.

[haneefdm]

About the following

Change Link for prebuild OpenOCD binaries to https://github.com/xpack-dev-tools/openocd-xpack/releases/ (at least for Linux and MacOS)

Initially, I thought that was great. But no. Already had to deal with a couple of users running into xPack version of OpenOCD which is not the same as what ST ships and switching to ST latest made problems go away. But we wasted a day or two trying to figure out why. Unlike any other gdb server, OpenOCD remains a problem. If a chip vendor ships it -- for sure use NOTHING but that.

[haneefdm]

Hi @PhilippHaefele I started on a new page

https://github.com/Marus/cortex-debug/wiki/Toubleshooting

Frankly, I am inundated by a lot of issues related to OpenOCD/gdb installations and, I feel like there is not enough self help or people are not even trying to help themselves.

The page above is not done right, I know. I wanted to get some material in there first. Now I am thinking, I should have done it backwards.

[pwnorbitals]

https://app.bountysource.com/issues/104525752-documentation-improvement-planning