Migrating parisc.wiki.kernel.org to RTD

Migrating parisc.wiki.kernel.org to RTD

[Konstantin Ryabitsev]

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,
-- 
Konstantin Ryabitsev
kernel.org

Re: Migrating parisc.wiki.kernel.org to RTD

[Helge Deller]

Hi Konstantin,

On 10/11/24 16:31, Konstantin Ryabitsev wrote:
> 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.

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

> # 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.

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?

> # 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

Re: Migrating parisc.wiki.kernel.org to RTD

[Konstantin Ryabitsev]

On Mon, Oct 14, 2024 at 10:57:02PM +0200, Helge Deller wrote:
> 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.

> 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.

> 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

Re: Migrating parisc.wiki.kernel.org to RTD

[Helge Deller]

Hi Konstantin,

On 10/15/24 18:32, Konstantin Ryabitsev wrote:
>> 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

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

> 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

Re: Migrating parisc.wiki.kernel.org to RTD

[Konstantin Ryabitsev]

On Wed, Oct 16, 2024 at 05:00:51PM +0200, Helge Deller wrote:
> Ok so far.
> https://readthedocs.org/projects/parisc/
> https://parisc.readthedocs.io/en/latest/

Nice, I'm happy it's working.

> source from here:
> https://github.com/hdeller/parisc-website.git
> 
> > 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

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

Migration of parisc.wiki.kernel.org to RTD

[Helge Deller]

Dear PA-RISC Linux users,

On 10/11/24 16:31, Konstantin Ryabitsev wrote:
> 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