search

SmingHub / Sming

Sming - powerful open source framework simplifying the creation of embedded C++ applications.
https://sming.readthedocs.io
GNU Lesser General Public License v3.0
1.47k stars 348 forks source link

Documentation fixes #2841

Closed mikee47 closed 2 months ago

mikee47 commented 3 months ago

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!):

mikee47 commented 3 months ago

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

mikee47 commented 3 months ago

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

slaff commented 2 months ago

@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 commented 2 months ago

@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 commented 2 months ago

@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 commented 2 months ago

@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 commented 2 months ago

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 commented 2 months ago

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 commented 2 months ago

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:

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:

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

I'll have a play.