Update Documentation

[AlvinSchiller]

I started to update / harmonise the documentation.
This includes the source and the wiki repo.
Renamings have been made in both (if existing).

As the wiki repo does not support Branches or PullRequest the dev state can be seen here:
Git: https://github.com/AlvinSchiller/RPi-Jukebox-RFID.wiki.git
Wiki: https://github.com/AlvinSchiller/RPi-Jukebox-RFID/wiki

The change includes:

• Move docs from source repo to wiki
• Update deprecated RPi OS distro names (and even remove in places where not neccessary -> see Question 'file renaming')
• Harmonise installation guide (e.g. links to RPi OS Images, Image flashing, etc...)
• Fix / remove links to deprecated docs / installscripts

Questions

• Some files will better be renamed, but this would break links in existing issues / discussions / branches (e.g. master).
  Should the old files persist and only link to the new ones, or is this acceptable?

[AlvinSchiller]

@s-martin Before i continue and deep dive is this desirable? And are there maybe other edge cases that have to be considered?

[s-martin]

Hi, sorry for the late reply.

Thanks for making the effort. From my point of view it absolutely makes sense.

Future3 already has a thorough Sphinx / readthedocs documentation, but I think V2 needs some polishing!

Nevertheless I would keep the components docs in the repo as this is often installed optionally and it’s important to keep the source code and the docs in sync.

But the general docs could reside in the wiki.

[AlvinSchiller]

Nevertheless I would keep the components docs in the repo as this is often installed optionally and it’s important to keep the source code and the docs in sync.

Totally agree. I didn't want to move the component docs at all (or others directly bound to some elements). Helped me a few times already :)

Questions
* Some files will better be renamed, but this would break links in existing issues / discussions / branches (e.g. master).
Should the old files persist and only link to the new ones, or is this acceptable?

What would be your prefered way with the general docs? Delete the files or keep it and redirect?

[AlvinSchiller]

To merge the changes in the wiki repo:

a. Simple commandline:

• clone the original wiki from: https://github.com/MiczFlor/RPi-Jukebox-RFID.wiki.git
• pull changes from my wiki repo directly (fast forward possible): git pull https://github.com/AlvinSchiller/RPi-Jukebox-RFID.wiki.git master
• push to "origin"

b. To Merge with a prefered tool (like VS Code, ...):

• clone the original wiki from: https://github.com/MiczFlor/RPi-Jukebox-RFID.wiki.git
• add my wiki repo as a new remote 'AlvinSchiller': git remote add AlvinSchiller https://github.com/AlvinSchiller/RPi-Jukebox-RFID.wiki.git
• git fetch --all
• use the tool to pull / merge / rebase the changes from my wiki repo master branch
• push to "origin"

[AlvinSchiller]

@s-martin @pabera
I saw that the gitter links are not valid anymore (404).
As gitter seems to be transformed to matrix should the links be deleted? Or create a matrix channel alternatively?

[pabera]

As gitter seems to be transformed to matrix should the links be deleted? Or create a matrix channel alternatively?

Sounds like a good idea. We already have a Matrix Channel

• https://matrix.to/#/#phoniebox_smalltalk:matrix.org

[AlvinSchiller]

Ok, I looked a little further and apparently the gitter room is still available at https://matrix.to/#/#phoniebox_community:gitter.im

So the URL should probably just be updated.

[coveralls]

Pull Request Test Coverage Report for Build 6804771841

• 0 of 0 changed or added relevant lines in 0 files are covered.
• 7 unchanged lines in 1 file lost coverage.
• Overall coverage remained the same at 76.82%

---

Files with Coverage Reduction	New Missed Lines	%
GPIODevices/rotary_encoder.py	7	86.59%

Totals
Change from base Build 6804326855:	0.0%
Covered Lines:	633
Relevant Lines:	824

---

💛 - Coveralls

[pabera]

Should this be merged at some point?

[AlvinSchiller]

My wiki repo has been rebased on the latest changes.

[AlvinSchiller]

Raspberry Pi OS Bookworm was released a few days ago, which brings buster in oldoldstable state and also updates the imager software, so new flashes will most likely use bullseye (as the last issues/questions also show).

As there seem to be no bigger issues with bullseye, I would update the docs again to strip out Debian version names as much as possible, and would replace the bullseye warning on the installation page, with a warning that bookworm is currently not supported (#2084).

Any concerns about breaking links with renaming wiki headers or the like?

[AlvinSchiller]

Also are there any known issues with 64bit in 2.x?
This is currently stated as unsupported in the docs but a lot users seem to use it.

[s-martin]

I think it’s ok to update the names and the links.

I remember some issues reported, which were supposedly caused by 64bit, but right now I’m not sure, if 64 bit is really unsupported.
@pabera were the 64 bit issues regarding future3?

[pabera]

I think it’s ok to update the names and the links.

I remember some issues reported, which were supposedly caused by 64bit, but right now I’m not sure, if 64 bit is really unsupported. @pabera were the 64 bit issues regarding future3?

It's not super supported at the moment. At the other side, I have not really tested it either. with 32bit, we are safe for now.

pabera@99a5536

[s-martin]

I think we could merge this, after the conflicts have been solved.

[AlvinSchiller]

@s-martin I rebased the wiki repo with the latest changes as well. Should i push it now or are you on it?

[s-martin]

Please push it

[AlvinSchiller]

Please push it

@s-martin I dont have the needed write rights to push to the wiki :(

[s-martin]

I assume you mean this way https://docs.github.com/en/communities/documenting-your-project-with-wikis/adding-or-editing-wiki-pages#adding-or-editing-wiki-pages-locally to push your changes?

I’ll look into it and then I will do it tonight or @MiczFlor grants you the rights and you can do it yourself - whatever happens first :)

N.B. I was today years old, when I learned that the wiki is just another git repo ;)

[AlvinSchiller]

HowTo is also here -> #2008 (comment)
;)

Just a note: due to some files containing invalid characters the checkout (and therefor the push) is currently not possible on Windows. After the changes have been applied this is not a problem anymore.

[s-martin]

ok, looks like i pushed the wiki successfully : )

[AlvinSchiller]

Yes, looks good :)