Documentation fixes

[mikee47]

General review and update to documentation

Smart quotes

These are the 'pretty' versions of regular quotes which can infect code and documentation due to a 'smart quote' virus embedded into many modern editors.
Their purpose is to make documentation (e.g. web pages) look pretty. That's it.

Their presence in C/C++ code is a syntax errror. In documentation, not so much.
However, if they appear in quoted code snippets then these won't work when pasted.

I think it best therefore to avoid them completely, so have all been converted to standard 'dumb' quotes.

Note that Sphinx will automatically convert regular quotes into their curly equivalents so there is no need whatsoever to have these in the source.

TODO (please comment if you have any thoughts on these!):

• Is espconn still unsupported by lwip2? Don't know: just add note.
• Windows .cmd install scripts are quite useable, just needs an export.cmd and documenting. We then don't need the custom sming choco scripts: we should remove those from documentation. Bit more than that: separate PR.
• Is there a way to check/fix use of smart quotes automatically? Nope. I'll write one.
• Add notes on debugging in vscode - already there, just not as involved as Eclipse
• Is eclipse still a good development environment? I always found it slow, complicated and clunky, but maybe that's changed? Is the documentation still correct for current versions?
• Lots of duplication in eclipse debugging pages, merge this into single document

[mikee47]

@slaff Maybe leave this one open for general documentation fixes until we're ready for release?

[mikee47]

Test build for review https://smingdev.readthedocs.io/en/fix-documentation-fixes/

[slaff]

@mikee47 I am planning to create the new 5.2.0 release at the end of next week. Do you need more time to make all changes that you have planned or this works for you?

[mikee47]

@slaff That'll be fine. I'm aiming to finish this PR today sometime. Also got some rework for CI build caching due shortly.

[mikee47]

@slaff OK so documentation is almost there but still keep finding stuff. If I find anything which needs a bit of research I'll add it as a TODO but otherwise it's fixing errors, inconsistencies and duplication.

[slaff]

@mikee47 thank you for your hard work. This release is going to have the best, for now, documentation and code improvements. Mainly thanks to you :)

[mikee47]

It surprises me how much I (didn't) know: clang, llvm, lldb, macos, timezones, ccache, CI caching/artifacts,.... I've learned a load in the past while!

[slaff]

We then don't need the custom sming choco scripts: we should remove those from documentation.

Lets keep it for this release, and announce that choco is deprecated. We will remove it for release v.6.0

Is eclipse still a good development environment? I always found it slow, complicated and clunky, but maybe that's changed? Is the documentation still correct for current versions?

Old guys like me are still using it :) I will look at the documentation but the last time it was still ok and Eclipse hasn't changed much in the last years.

[mikee47]

We then don't need the custom sming choco scripts: we should remove those from documentation.

Lets keep it for this release, and announce that choco is deprecated. We will remove it for release v.6.0

Spoke too soon... Forgotten what a PITA Windows was. Path lengths, etc, etc, etc. Also having attempted a scripted winget installation the experience is much better with choco, so thankfully we can stick with that.

To recap, at present choco.sming does this, in order:

• Install git
• Install python (version 3.9.1 or 3.10)
• Install cmake
• Unpack mingw from SmingTools repo. and update system path
• Install esp8266 toolchain ***
• Clone sming (master branch)

The item *** is out of date now so I'm thinking we remove that and update python to include 3.12.
The user then runs sming\Tools\install.cmd to install architecture-specific toolchains as required,
none of which requires updating the system path so is much easier to handle.

We could go further actually, reducing choco.sming only to this:

• Install git
• Clone sming (master branch)

i.e. just a bare bootstrap. Everything else can go in the install script.

I'll have a play.

[slaff]

Looks great! Noticed only one small typo.

[slaff]

I guess "Lost of popular" should be "Lots of popular"

[mikee47]

Eeek. Can't believe I wrote that! Many popular... :-)