Skip to contentSkip to conversation

Migrating parisc.wiki.kernel.org to RTD

DISCUSSION Konstantin Ryabitsev 2 participants 6 messages Oct 11, 2024 – Oct 21, 2024

lore
Share & tools
lore
#0 lore raw

Greetings:

We are trying to sunset the last few wikis that we are hosting and convert them all to git-backed sphinx documentation. The PARISC wiki is one of the last MediaWikis that we have, and I have prepared a migration path for you that I hope you will find suitable.

# Preliminary build

I have the preliminary conversion build available here:

https://www.kernel.org/doc/projects/parisc/index.html

The underlying repository for it can be found here:

https://git.kernel.org/pub/scm/docs/docsko/parisc.git/

The git repository includes the entire mediawiki history (excluding media), plus the new source tree with the conversion results.

# Multiple RTD hosting options

If you would like to switch to the new sphinx-backed site, there are multiple ways to host it:

1. You can clone that git repository and host it on github. This would allow for a quick readthedocs.org integration and allow you to edit the files directly via the github interface. This is a very wiki-like workflow and would allow you to grant access to the repository to anyone with a github account, plus accept pull requests with modifications. Once you have readthedocs.org integration working, we can configure it to be under the docs.kernel.org domain, which will allow you to remove the ads from the site.

2. Continue to host it in the current location and edit it with your kernel.org account credentials, plus accept edits via patches sent to this mailing list.

# Staying with mediawiki

I believe switching to sphinx-style documentation is the right way forward, because wikis are increasingly problematic to host due to spam and hostile scraper bots. By switching to RTD you also gain a lot more independence in your hosting options, as the statically generated site can be put anywhere capable of serving files.

However, if you're absolutely sure you want to stay with MediaWiki, we can arrange hosting with OSUOSL, but it would need to be under a non-kernel-org domain.

# What next?

Please let me know which way you would like to proceed in the next few days, as I am hoping to sunset our last wikis by the end of October.

Best regards,

Signature · 2 lines
Konstantin Ryabitsev
kernel.org
#1 lore raw

Hi Konstantin,

Quoted 9 lines · Konstantin Ryabitsev

We are trying to sunset the last few wikis that we are hosting and convert them all to git-backed sphinx documentation. The PARISC wiki is one of the last MediaWikis that we have, and I have prepared a migration path for you that I hope you will find suitable.

# Preliminary build

I have the preliminary conversion build available here:

Quoted 8 lines

https://www.kernel.org/doc/projects/parisc/index.html

The underlying repository for it can be found here:

https://git.kernel.org/pub/scm/docs/docsko/parisc.git/

The git repository includes the entire mediawiki history (excluding media), plus the new source tree with the conversion results.

You've have done a good job in converting it.
Thanks!

Quoted 26 lines

# Multiple RTD hosting options

If you would like to switch to the new sphinx-backed site, there are multiple ways to host it:

1. You can clone that git repository and host it on github. This would allow for a quick readthedocs.org integration and allow you to edit the files directly via the github interface. This is a very wiki-like workflow and would allow you to grant access to the repository to anyone with a github account, plus accept pull requests with modifications. Once you have readthedocs.org integration working, we can configure it to be under the docs.kernel.org domain, which will allow you to remove the ads from the site.

2. Continue to host it in the current location and edit it with your kernel.org account credentials, plus accept edits via patches sent to this mailing list.

# Staying with mediawiki

I believe switching to sphinx-style documentation is the right way forward, because wikis are increasingly problematic to host due to spam and hostile scraper bots. By switching to RTD you also gain a lot more independence in your hosting options, as the statically generated site can be put anywhere capable of serving files.

Quoted 3 lines

However, if you're absolutely sure you want to stay with MediaWiki, we can arrange hosting with OSUOSL, but it would need to be under a non-kernel-org domain.

It's really sad.
I was quite happy with mediawiki and the output was quite nice, at least nicer than what RTD currently generates.
I have not used RTD yet, so maybe someone here on the mailing list has some knowledge and want to help?

Quoted 4 lines

# What next?

Please let me know which way you would like to proceed in the next few days, as I am hoping to sunset our last wikis by the end of October.

Unless someone else steps up and want to work on the website, I think I will go with RTD and choose either option 1 or 2. Do you have some more docs what steps have to be done then?

Helge

#2 lore raw
Quoted 1 line · Helge Deller

It's really sad.

Unfortunately, I believe that the time of wikis has passed. They have to be seriously locked down to avoid having to constantly fight spam, and this largely defeats the purpose of having a wiki at all, as opposed to any other publishing platform. In addition, in the past year we've seen more and more aggressive AI training bots descend on public resources and try to grab as much content as quickly as possible, which is both expensive in bandwidth and tends to result in poor performance for everyone. I am strongly convinced that going back to statically rendered sites is the way to go to avoid a lot of modern-day problems.

Quoted 2 lines

I was quite happy with mediawiki and the output was quite nice, at least nicer than what RTD currently generates.

Note, that the RTD output can be tweaked quite a bit -- I'm just using one of the stock themes with no customizations. I also noticed that the light theme looks much nicer on the front page than the dark theme due to all the logos.

Quoted 2 lines

I have not used RTD yet, so maybe someone here on the mailing list has some knowledge and want to help?

I'm happy to guide you along. I've added a readthedocs.yml and requirements.txt files to the repo:

https://git.kernel.org/pub/scm/docs/docsko/parisc.git

You can clone it and then push to your github or gitlab repo. After that, generating a readthedocs build is very easy:

https://docs.readthedocs.io/en/stable/tutorial/index.html

If you follow that, you should be able to get a build of the repository in 20-30 minutes. After that, you can even edit the documents directly on github and have them automatically rendered.

Once you have it working on the readthedocs site, I can help you configure a docs.kernel.org domain and set the redirects from the old wiki.

Let me know if that helps.

-K

#3 lore raw

Hi Konstantin,

Quoted 11 lines · Konstantin Ryabitsev
Quoted 2 lines

I have not used RTD yet, so maybe someone here on the mailing list has some knowledge and want to help?

I'm happy to guide you along. I've added a readthedocs.yml and requirements.txt files to the repo:

https://git.kernel.org/pub/scm/docs/docsko/parisc.git

You can clone it and then push to your github or gitlab repo. After that, generating a readthedocs build is very easy:

Quoted 8 lines

https://docs.readthedocs.io/en/stable/tutorial/index.html

If you follow that, you should be able to get a build of the repository in 20-30 minutes. After that, you can even edit the documents directly on github and have them automatically rendered.

Once you have it working on the readthedocs site, I can help you configure a docs.kernel.org domain

Ok so far.
https://readthedocs.org/projects/parisc/
https://parisc.readthedocs.io/en/latest/
source from here:
https://github.com/hdeller/parisc-website.git

Quoted 1 line

and set the redirects from the old wiki.

Before setting up redirects, can you help me with this error:

deller@carbonx1:/home/cvs/LINUX/parisc-website$ make html
Running Sphinx v8.1.3
loading translations [en]... done
Extension error:
Could not import extension sphinxcontrib.applehelp (exception: cannot import name 'SkipProgressMessage' from 'sphinx.util' (/home/deller/.local/lib/python3.12/site-packages/sphinx/util/__init__.py))
make: *** [Makefile:20: html] Error 2

Helge

#4 lore raw
Quoted 3 lines · Helge Deller

Ok so far.
https://readthedocs.org/projects/parisc/
https://parisc.readthedocs.io/en/latest/

Nice, I'm happy it's working.

Quoted 5 lines

source from here:
https://github.com/hdeller/parisc-website.git

Quoted 1 line

and set the redirects from the old wiki.

Quoted 8 lines

Before setting up redirects, can you help me with this error:

deller@carbonx1:/home/cvs/LINUX/parisc-website$ make html
Running Sphinx v8.1.3
loading translations [en]... done
Extension error:
Could not import extension sphinxcontrib.applehelp (exception: cannot import name 'SkipProgressMessage' from 'sphinx.util' (/home/deller/.local/lib/python3.12/site-packages/sphinx/util/__init__.py))
make: *** [Makefile:20: html] Error 2

I suggest that instead of using the system-wide sphinx package, that you install a venv to build the site locally. E.g., inside the parisc-website repository:

python3 -mvenv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install Sphinx furo
make html

You can add .venv to .gitignore so it doesn't interfere with the rest of the repo. To deactivate the venv, just do "deactivate".

Let me know if that helps.

-K

#5 lore raw

Migration of parisc.wiki.kernel.org to RTD

In reply to Konstantin Ryabitsev

Dear PA-RISC Linux users,

Quoted 4 lines · Konstantin Ryabitsev

We are trying to sunset the last few wikis that we are hosting and convert them all to git-backed sphinx documentation. The PARISC wiki is one of the last MediaWikis that we have, and I have prepared a migration path for you [...]

In the meantime, Konstantin and myself moved the PA-RISC Wiki to become a "ReadTheDocs" static website.

It's now hosted at

https://parisc.docs.kernel.org

and the source is available at

https://github.com/hdeller/parisc-website

https://wiki.parisc-linux.org redirects to the new website.

Helge