Migrate wiki pages to RST and integrate with front page

[JudgeGregg]

Hello, this PR should be able to integrate the migrated RST pages to the existing front page.
(demo: https://judgegregg.github.io/sphinxwiki/)

How-to build:

• install sphinx, furo and ghp-import
• build docs with SOURDIR=content make html
• copy index.html, assets and images to _build/html (assets and images could be merged to _static, probably)
• run: ghp-import _build/html -nop

Some areas of improvement:

• remove TOC from pages since furo handles it on its own (easy)
• remove links to not yet migrated pages and move them to the RTD page ? (a bit more complicated)

[adiroiban]

Excellent work! Thanks.
I will look to have this merge.

I think that for the real wiki migration we want to use GitHub wiki, so that we can preserve the edit history as an archive.

But for the new presentation site, this should be great.

[adiroiban]

I guess that we will want to have this hosted via Read The Docs or Netlify ... or do our own automation via GitHub Actions and GitHub pages.

I prefer Read The Docs or Netfliy as it has nice PR build preview functionality.

[adiroiban]

Todo for this PR to land:

• update the code to auto-deploy with GitHub Pages on merge
• Have the same links as Trac ROOT/content/pages/Security -> ROOT/wiki/Security or ROOT/content/pages/Twisted/TwistedDevelopment -> ROOT /wiki/TwistedDevelopment

[graingert]

@JudgeGregg @adiroiban is there anything I can do to help land this?

[adiroiban]

I am -1 for merging this as it is.

The wiki has a lot of old info that is no longer relevant.

The wiki content was archived here https://github.com/twisted/trac-wiki-archive and redirection was implemented

I start working at moving any relavant info found in the wiki, into the main documentation site

I have already migrated the "Review process" wiki page, to the main docs site as part of this PR

There is this PR twisted/twisted#11577 to create a root section for development and continue to move more docs from the wiki into the main doc site.

[JudgeGregg]

Hello, I'd like to help too, but I'm a bit confused right now :)

From what I understand:

• we need to convert the old media wiki pages to RST (possibly reusing the content from this PR ?)
• then transfer these RST pages to https://github.com/twisted/twisted/tree/trunk/docs (under a specific directory)
• and ideally link the "new" site (twisted.github.io) to the docs pages once they've been generated

Do you have a an idea of some "secondary page" I could work on just to make sure I understand the whole process ?
"Projects using Twisted" maybe, or "The Python Advantage".

[adiroiban]

we need to convert the old media wiki pages to RST (possibly reusing the content from this PR ?)

We need to convert only some Trac wiki pages.

There is a lot of obsolete, conflicting, confusing content on the wiki.

The idea is to only extract that good / valid information from the wiki and integarate that information into the "official documentation"

then transfer these RST pages to https://github.com/twisted/twisted/tree/trunk/docs (under a specific directory)

I don't think that we want to do an automated conversion, but review the wiki information, see what makes sense and reuse only that.

The idea was that we used the wiki as a draft documentation.
No review process was required for the wiki page.
Once the wiki contains valid content, that content should have been moved to the offical docs after passing the normal review process.

So the wiki contains a lot of pages for which the content was never reveiewd.
It also contains duplicate infos. see for example the "Contributing to Twisted" pages.
There are multiple variants.

For the official docs, we only want one version.

and ideally link the "new" site (twisted.github.io) to the docs pages once they've been generated

We already have a link to the docs from https://twisted.org/

---

So in summary.

Don't do a full conversion.
Don't move the unreviewd junk from wiki to the official docs.
We want to review the content from the wiki, get approval from teams and get that content integrated into the docs pages.

Makes sense?

[JudgeGregg]

Yes that's very clear, thank you.
As an example, I just pushed a RST version of the Community page:
JudgeGregg/twisted@a7ce593 (no PR yet).

• I deprecated some info about mailing lists and IRC chans.
• The link to the "main" ML is dead.
• So far I added the page at the root of the toctree.

I'll open a ticket and a PR if this looks good to you.

[adiroiban]

archives are here https://mail.python.org/archives/list/[email protected]/

The twistedmatrix.com is the legacy site.
Some URL still work as we have some GitHub Pages mapping.

The archive of the archive is here https://github.com/twisted/pipermail

[adiroiban]

Not to forget.

We have a "community summary" info on the new twisted front page.

Once we have the updated "community extended docs" info we can update the link

[JudgeGregg]

Okay, I've updated the page with the archives, and fixed the main ML link.
Final result preview: https://judgegregg.github.io/twisted/community.html

Do you think it's worth adding a few pages in each PR or should a PR relate to only one page ?

[adiroiban]

I think deprecated info can be removed from the page.

I think the documentation should describe the current info, and should not include a whole history of the Twisted dev community.

I you think that is important to keep this out of date info on the page, I think is better to move the info into the "historic" section - https://docs.twisted.org/en/stable/historic/index.html

Please create a PR on the twisted/twisted repo, it should automatically generate a Read The Doc version for preview.

Thanks again for help with the docs.