move Wiki from Github

[cdbzb]

Proposal

Move the SuperCollider Wiki from GitHub and use Sphinx to generate static site.

Motivation

A wiki is hopefully a permanent reference.
But in the history of SC, there has already been (at least?) one abandoned wiki that was migrated to the GitHub wiki, and while GitHub is a convenient place, it is not a place to support.
I therefore advocate, in support of #6114, to move the current wiki https://github.com/supercollider/supercollider/wiki to https://wiki.supercollider.online and making it a repository that creates a static website, which serves as the new wiki.
This would allow to take ownership of the wiki URL and be independent of the code hosting platform, making it a permanent location for the precious information.

This would also prepare the community/wiki in case GitHub needs to be evacuated.

Description of the proposed feature

I first thought about making a real wiki, but I think a static website is easier to maintain and has a longer lifespan.
A small wiki like SC should be suitable for a static site generator.

I decided to use Sphinx as a static website generator because it is an established tool and has a pretty stable API (compared to NodeJS based tools).

I also don't have a clue how to contribute to the existing wiki (fork the wiki-repo and do a PR?) as I don't have editor privileges, but making it a repo would allow anyone with access to git to edit it via a PR workflow.

Sphinx would also allow to create indices, references, glossary, build local tocs, provide a search and also verify that all internal links are working during build time.

The main advantages I see

• independence of any hosting platform - hosting a static website can be easily done these days
• searching the wiki
• editing can be performed offline
• internal references can be checked for dead links at build time
• custom styling
• Clear PR workflow (how can the current wiki be edited? It has a git repo but how do I make a PR on it?)
• website structure is independent of folder structure, which allows to improve the organization of files

Implementation plan

I cloned the existing wiki and converted it to a Sphinx website - this means that the history of most pages is untouched, preserving valuable git history (see https://github.com/capital-G/supercollider-wiki/blame/main/docs/contributing/workflow/Unit-Testing-Guide.md)

Repo: https://github.com/capital-G/supercollider-wiki
Website: https://capital-g.github.io/supercollider-wiki/

Currently hosted on GitHub pages - although this PR is motivated to evacuate GitHub, I think it is still okay to use their CI for now. The build step and serving of static content can easily be moved to e.g. GitLab.

I would be happy to take up some styling suggestions or commits, as this wiki would allow us to style and modify in such a way we want, and not how GitHub thinks it should be done.

[telephon]

I like the idea. One thing that might have to be addressed in the rfc more explicitly is in how far a wiki can be still a wiki if it is not editable directly. Can you edit it in a wiki-way offline and then sync the changes? How would the workflow be?

[mtmccrea]

I've updated the top post to include points raised by @capital-G in the original Issue.

More implementation details from that thread:

Editing the Wiki - PR process

I think having a low barrier to contributions (aside from initial access) will be important to keep the wikis up to date and with good coverage — plenty of engaged people will spot and want to fix/update little things but may not bother if there's too much process.

In the current status quo I don't know how to obtain access as there it is nowhere stated on how to obtain edit rights, and therefore I think it is not very welcoming at all and one becomes a bit paranoid - why do some people who contribute have access, others not? It feels like ones contributions are not regarded trustworthy, therefore one has no rights to edit the wiki?
The PR workflow wouldn't change this per se, but at least I can request something and make it public for other people to see as well, and this would be to me much more welcoming as everyone is welcomed to contribute.
...
I added an edit button on each site which will redirect to the source code within the repo from where one can spawn a PR via the visual editor of GitHub. For example, clicking on the pink pencil [top right] redirects to https://github.com/capital-g/supercollider-wiki/blob/main/docs/contributing/style/Style-Guidelines:-Cpp.md

How the TOC gets built

Internally, Sphinx can handle two ways, either referencing other files in a TOC like this https://github.com/capital-G/supercollider-wiki/blob/344aa489f381f3d8d849076eea08e0c5939bdec9/docs/index.rst?plain=1#L43-L51 or use glob to "just include everything in this folder in the order of the filenames" https://github.com/capital-G/supercollider-wiki/blob/344aa489f381f3d8d849076eea08e0c5939bdec9/docs/community/index.rst?plain=1#L13-L18

Resolving dead links:

It's very helpful that dead links can be spotted automatically, that's already a bit help. I wonder if we can do anything about dead links in the wild.... it would be great if addresses persisted through page name changes (as they do on scsynth.org, for example).

This would be possible, see https://www.sphinx-doc.org/en/master/usage/builders/index.html#sphinx.builders.linkcheck.CheckExternalLinksBuilder

Themes:

There are also some different themes which can be changed really easily and also change the clickflow, but I stayed with the default one for now - but take a look at https://sphinx-themes.org/ (but I'd like avoid discussions about styling/aesthetics for now).

[capital-G]

An alternative approach could be to transfer the wiki to our discourse forum as discourse also offer posts which can be edited by a multiple users via a group, see https://meta.discourse.org/t/what-is-a-wiki-post/30801 and https://meta.discourse.org/t/create-a-wiki-post/30802

Pro:

• We also reach a non-dev audience for reading and editing
• no proprietary GitHub account is necessary for contributing
• Uses on an open platform that the community owns
• There can also be discussions about Wiki posts, e.g. "is this outdated?"

Con:

• Is limited to the features of discourse
• URLs are not too nice (although post such as https://scsynth.org/t/activating-chat-on-scsynth-org/9618 can be abbreviated as https://scsynth.org/t/activating-chat-on-scsynth-org/) which looks like a nicer URL to me?
• We would loose the git history (but we could archive the wiki and discourse has a post-version history!)

I think I'd actually favor this approach.

[telephon]

So the history lost would be the edit history only of the wiki, right?

[capital-G]

So the history lost would be the edit history only of the wiki, right?

We could do a "bulk import" of the existing wiki into the forum and transfer and archive the github wiki as an actual git repo, so the history of it would be accessible (e.g. blame looks like this https://github.com/capital-G/supercollider-wiki/blame/main/docs/contributing/style/Style-Guidelines%3A-Cpp.md )

[mtmccrea]

What does "bulk import" entail?

[capital-G]

What does "bulk import" entail?

We could write a script which imports the current wiki into discourse. But it may be faster to do just manually, as the wiki is not too big currently.

[capital-G]

Any way to move forward here? @scztt do you think the forum would be a viable place for the wiki?

[mtmccrea]

I was quite convinced by you static site generator approach, it addressed all the questions I raised initially and it seems like a quite comprehensive solution with numerous improvements over the current setup, with additional customizability. That said, I'm not the best judge of maintenance and longevity aspects of that solution.

One of the sticking points seemed to be the PR process. After thinking about it more, I think it could actually be a good thing to have more eyes on the updates, and content in general, on the wiki. I have a feeling it's kind of "back of mind" for most contributors. A review stage will only improve the content, and trivial changes are easy to approve. (Though having roles that can just immediately merge trivial changes would be helpful.)

Also, what happens if we leave Discourse? Having full control over the wiki, with history, seems more robust (though with maintenance cost).