DebugMenu docs do not mention PD Debug menu is only on later versions of firmware

[An-GG]

The PD Debug menu has been added to the firmware in recent versions, and it is not clear to users of the docs that they will likely need to update their iron to use this feature.

I have a Pinecil v1 from Aug 2021 with factory, pretty old, firmware. I used the commit history to verify this feature wasn't in the firmware at that time, but that was a blind guess and many hobbyists will not know to do this. I think a quick update to the DebugMenu docs alone is probably sufficient.

It might be neat to be able to see some basic git blame style last-edited info directly in the docs so we don't need to throw up disclaimers every time we add a feature. Update: Enabling the flyout menu would solve this problem.

[River-Mochi]

@Ralim Flyout menu looks cool see above. something with the documents to explain which version of firmware it is related to is a good idea (either at the top or something) Is there a way to Tag a document so it's flagged with the minimum version you need to have the things in the document?

or if just one section changed, like several new settings - then those settings should have firmware number so people can see it's for 2.19 (and they have 2.18 where it's not included)

1. I saw a few complaints already that the Calibration of CJC temperature in the instructions does not match what people see on on-screen since it has changed. They complained that the instructions were "out-dated" but I think it may be the opposite, the instructions represent the new way for a firmware that is not available yet.
2. updating the Pinecil did not help as this appears to be some instructions for calibration for a version that has not been released yet?
3. Some method of alerting readers to the version of the Firmware that the document refers to would help.
4. Or if it's just one setting that was added - then that setting should have a note as to the firmware it is in (if it's 2.19, 2.20) - it would reduce confusion.
5. Or somehow Hold Back new instructions on Documents until the actual firmware is released which matches the Documents would also reduce confusion. I'm not clear on how this could be best implemented.

[River-Mochi]

@An-GG check this out, Ralim is actively moving documents over to here https://ralim.github.io/IronOS/ to make it more user friendly for non-developers.

maybe some features could be added. with the large user base of IronOS, it is important to know which firmware version the Document or setting inside the document relates to , otherwise users think they are doing something wrong until they realize they need to upgrade or in some cases , the item mentioned is part of a Beta that has not been released yet.

[An-GG]

@An-GG check this out, Ralim is actively moving documents over to here https://ralim.github.io/IronOS/ to make it more user friendly for non-developers.

Oh I didn't know that was a work in progress. I assumed these were already the official docs, since that's what the Getting Started Guide links to from the README, and the readthedocs is what I was referencing in my issue as that is what I have been using.

Or somehow Hold Back new instructions on Documents until the actual firmware is released which matches the Documents would also reduce confusion. I'm not clear on how this could be best implemented.

Yes this is a good idea, and not that hard to implement. Most projects will have their master branch be their default/release branch, (we already do this), but when users land on the github they see the master branch, which is untouched until a dev is merged. We just need to change default branch on github + add note in developer guide to switch to dev branch. This, alongside the flyout menu will fix 90% of complaints.

or if just one section changed, like several new settings - then those settings should have firmware number so people can see it's for 2.19 (and they have 2.18 where it's not included)

Yeah this would be platonically ideal but I didn't push for this in my original issue description since readthedocs doesn't seem to have a good solution for this problem. The best I can think of is a preprocessor that looks for changes across our git history and prepends version labels next to changes in the docs, but then you get into a situation where your built docs aren't necessarily exactly the same for the same commitid if the preprocessor doesn't work just right, so you can't commit fully built docs alongside the rest of the code, not to mention the fact that tagging every little change between versions probably not even that accurate and kinda unneces..... you get the point, a big hairy mess lol.

To be fair, a preprocessor could work, maybe even well, but I've never seen it done that way. We could also implement documenting versioned changes as part of PR policy, but I've never liked that idea much. Default master branch + flyout menu + disclaimer asking users to switch to the version of firmware that applies to their iron at the top of the docs is probably more than enough.

[Ralim]

Yes this is a good idea, and not that hard to implement. Most projects will have their master branch be their default/release branch, (we already do this), but when users land on the github they see the master branch, which is untouched until a dev is merged. We just need to change default branch on github + add note in developer guide to switch to dev branch. This, alongside the flyout menu will fix 90% of complaints.

This is coming after next release 😁

Yeah this would be platonically ideal but I didn't push for this in my original issue description since readthedocs doesn't seem to have a good solution for this problem. The best I can think of is a preprocessor that looks for changes across our git history and prepends version labels next to changes in the docs, but then you get into a situation where your built docs aren't necessarily exactly the same for the same commitid if the preprocessor doesn't work just right, so you can't commit fully built docs alongside the rest of the code, not to mention the fact that tagging every little change between versions probably not even that accurate and kinda unneces..... you get the point, a big hairy mess lol.

To be fair, a preprocessor could work, maybe even well, but I've never seen it done that way. We could also implement documenting versioned changes as part of PR policy, but I've never liked that idea much. Default master branch + flyout menu + disclaimer asking users to switch to the version of firmware that applies to their iron at the top of the docs is probably more than enough.

If I moved to actual read the docs, they have a version selector that can make this easier. But I am currently just using mkdocs with the read the docs theme. This is mostly to host it for free on Github pages with no ads.

I think we can cover this mostly by having the main release be the public instance and dev not publish; but also very open to any good preprocessor solutions. One thing I've thought about is abstracting out the settings to be done by a preprocessor and then coupling in their docs to that spec; so we can create per-device settings references.

[humitos]

Hi 👋🏼 . I found this issue while searching for Read the Docs issues and I wanted to comment some things 😄

or if just one section changed, like several new settings - then those settings should have firmware number so people can see it's for 2.19 (and they have 2.18 where it's not included)

Yeah this would be platonically ideal but I didn't push for this in my original issue description since readthedocs doesn't seem to have a good solution for this problem

Since you are using Sphinx, you can use .. versionadded:: directive for this (https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-versionadded) or .. deprecated:: (https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-deprecated)

The best I can think of is a preprocessor that looks for changes across our git history and prepends version labels next to changes in the docs, but then you get into a situation where your built docs aren't necessarily exactly the same for the same commitid if the preprocessor doesn't work just right, so you can't commit fully built docs alongside the rest of the code, not to mention the fact that tagging every little change between versions probably not even that accurate and kinda unneces..... you get the point, a big hairy mess lol.

I, personally, recommend release documentation from branches (e.g. 3.2.x) instead of tags (e.g. 3.2.0) to avoid these particular issues. This allows you to solve documentation issues, like typos or misunderstood sentences/paragraphs, that don't need a package release.

---

If I moved to actual read the docs, they have a version selector that can make this easier. But I am currently just using mkdocs with the read the docs theme. This is mostly to host it for free on Github pages with no ads.

I think the version selector will help you a lot with this problem 👍🏼 . Regarding the "no ads", you can opt-out by becoming a gold member, but it's not free, tho:

For small businesses or personal projects, we ask for $5 per month to remove ads from a project.

(from https://beta.readthedocs.org/accounts/gold/)

I think we can cover this mostly by having the main release be the public instance and dev not publish; but also very open to any good preprocessor solutions. One thing I've thought about is abstracting out the settings to be done by a preprocessor and then coupling in their docs to that spec; so we can create per-device settings references.

Read the Docs could also help you with this. When users are reading the latest version (matching your dev branch) they will be warn about this with a notification like the following:

You can test this behavior on my test-builds project at https://test-builds.readthedocs.io/en/latest/

Let me know if this information is useful for you.

[Ralim]

Hello,

Good point on the version added style tags, I'll have to look into these in the future, could be a very neat solution to the problem. Though I'm not sure how well they work with markdown (we don't generate any documentation from the code itself; its all just from the markdown files).

At this point in time, there is not the budget to be paying for readthedocs's hosted solution. While it would be great there just isn't any consistent income stream; (nor is there any consistent time I can spend on the project - so I don't expect one). I'm trying really hard to not turn this project into a money-sink 😓

I really want to say that this is not to reflect badly on the hosted option; it is a great option and readthedocs does great work. Just that subscription model is realistically a risk that is not quite worth it for just versioning. If we come across a need for other features; or ideally it could generate the output to push back to github to host then it would be easier to change to.