Migrate wiki.sagemath.org and trac.sagemath.org wiki contents to more suitable places

[Matthias Köppe]

The problem with wiki.sagemath.org:

It excludes new and newish developers who do not have the required legacy Trac account but log in to Trac using their GitHub accounts.

Wikis work because of the principle of crowdsourcing. Without a crowd, the material will just become outdated. New material added is indistinguishable from old material.

There is also a conflict between viewing the Wiki (1) as an archive (as a record of past achievements, and perhaps for the benefit of future software archaeologists); (2) as something that is useful for current users and developers; and (3) a place for discussion and planning actions.

These uses are not compatible. We propose to separate these types of material clearly and move each to a more appropriate system.

Source material on wiki.sagemath.org:

• ​https://wiki.sagemath.org/SageWikiMaintenance%20page
• ​https://wiki.sagemath.org/TitleIndex

---

Proposed targets:

Migration to Trac tickets / GitHub issues

Ticket/issue descriptions can be used for collecting/curating/staging material that eventually should be added to our documentation or to our code.

• #30500 Meta-ticket: document configuring IDEs and text editors
• #31164 Meta-ticket: Add user packages from ​https://wiki.sagemath.org/SageMathExternalPackages as optional/experimental packages

Migration to our documentation

(needs conversion to rst)

• #33649 Developer's Guide: Update reviewer's check list from wiki
• #33663 Developer guide: Check material in ​https://wiki.sagemath.org/TentativeConventions
• #34554 Merge ​https://wiki.sagemath.org/CodeSharingWorkflow into developer manual

Current drawback: The documentation is only updated one every stable release (to be fixed in #33862)

Migration to www.sagemath.org

(needs conversion to html; or website scripts need extension to handle markdown or moinmoin sources; ​https://python-markdown.github.io/reference/; ​https://github.com/github/markup)

• This would be suitable for example for archiving ​https://wiki.sagemath.org/Workshops

• #31533 Migrate old Sage release tours from Sage wiki
• ​Merge info from https://wiki.sagemath.org/CategoryHomepage into contributors.xml

---

Considered but won't be needed:

Migration to GitHub wiki:

"Note: Search engines will not index the contents of wikis. To have your content indexed by search engines, you can use GitHub Pages in a public repository." ​https://docs.github.com/en/communities/documenting-your-project-with-wikis/about-wikis

Migration to GitHub pages:

​https://pages.github.com/

(needs conversion to markdown)

Unclear why we should create a new website when we already have www.sagemath.org

Migration to trac.sagemath.org/wiki:

As proposed in ​https://groups.google.com/g/sage-devel/c/ayOL8_bzOfk/m/wOuVdXwbAgAJ, ​https://groups.google.com/g/sage-devel/c/Acy5nNZWaUA/m/DuqGh3JkCwAJ and ​https://groups.google.com/g/sage-devel/c/4ysVRpYGU_E

The ​Trac wiki markup appears to understand most of the old Sage wiki's markup, except:

• In section headers, CamelCase words need to be escaped with "!"
• edit the markup for included images
  • {{https://patchbot.sagemath.org/svg/Pending||width=48}} changes to [[Image(https://patchbot.sagemath.org/svg/Pending, width=48)]]
• Replace <<TableOfContents>> by [[PageOutline]]

Also we can simplify some markup by replacing links to Trac tickets by just #....

• A command that helps with this:

  sed 's/<<TableOfContents[()]*>>/[[PageOutline]]/;s,\[\ 
  [https://trac.sagemath.org/ticket/\([0-9]*\)|#\1\]\],#\1,g;/^=/s/ \ 
  ([A-Z][a-z][a-z]*[A-Z]\)/ !\1/g;' INPUT > OUTPUT
  

• ​https://trac-hacks.org/wiki/MoinToTracScript (untested)

See, however, #30363 (Proposed migration from Trac to GitHub).

---

Format conversion tools, workflow:

• ​https://github.com/swenson/sagewiki

• Convert directly to Markdown using ​https://github.com/phlash/moin2markdown

• Conversion from Trac wiki to markdown: ​https://github.com/sagemath/trac-to-github/

• To do while migrating: We also audit/update our documentation regarding links to the wiki.

  $ git grep 'wiki[.]sage'
  

References:

• ​http://moinmo.in/HelpOnConfiguration

• ​https://trac.edgewall.org/browser/trunk/trac/wiki/parser.py

[Thierry Monteil]

Please don't. In terms of infrastructure, the wiki is pretty well hosted, while the VM that hosts the trac+wiki is unmaintained, so this looks like a regression to me (at least right now).

[Dima Pasechnik]

I think that trac is better, as it allows contributions with github logins. And the bus factor of the present wiki hosting is rather small.

[Matthias Köppe]

It's critical that we get rid of the old Sage wiki. As Dima says - it excludes new developers.

Trac is maintained because it has to be (thanks to all who keep it running!) The wiki part of it places no additional burden on maintaining Trac.

[git]

Branch pushed to git repo; I updated commit sha1. New commits:

​57fc849

configure.ac: Remove outdated advice regarding exotic platforms

[git]

Branch pushed to git repo; I updated commit sha1. Last 10 new commits:

​b46c953	README: Document --enable-editable and --enable-download-from-upstream-url
​a3ffe84	README.md: Instructions for Apple Silicon
​d7708df	README.md: Restructure macOS prep instructions
​2e1d22d	src/doc/en/installation/source.rst: Remove instructions for Solaris, AIX, HP-UX
​9ca39a2	README.md: Point to developer guide for git details
​f1e1166	src/doc/en/installation/source.rst: Point to README.md for step-by-step instructions
​3f6c6e0	src/doc/en/developer/workspace.rst: Link to Trac #30500
​8716d80	src/doc/en/installation/source.rst: Update required venv Python extension modules from build/pkgs/python3/spkg-configure.m4
​10c9b87	Merge #33088
​45c1a39	src/doc/en/developer/trac.rst: Update wiki URL for patchbot

[Matthias Köppe]

Some pages, for example ​https://wiki.sagemath.org/SageMathExternalPackages, are written in RST.

The Trac wiki also supports RST - ​https://trac.sagemath.org/wiki/WikiRestructuredText - but it looks like it is not activated.

@dimpase, could you install docutils (as per ​https://trac.sagemath.org/wiki/WikiRestructuredText#Requirements)?

[git]

Branch pushed to git repo; I updated commit sha1. New commits:

​da69787

src/doc: Fix 'hardcoded link could be replaced'

[Matthias Köppe]

@tmonteil, would you be able to provide me with a snapshot of the moinmoin wiki data, so I can try out the script ​https://trac-hacks.org/wiki/MoinToTracScript?

[Thierry Monteil]

Replying to Thierry Monteil:

Please don't. In terms of infrastructure, the wiki is pretty well hosted, while the VM that hosts the trac+wiki is unmaintained, so this looks like a regression to me (at least right now).

[Matthias Köppe]

Replying to Matthias Köppe:

@tmonteil, would you be able to provide me with a snapshot of the moinmoin wiki data, so I can try out the script ​https://trac-hacks.org/wiki/MoinToTracScript?

Do you have response to this other than repeating that you're against it?

[Tobias Diez]

What's the reason why a wiki is necessary in addition to the main website and the documentation in the main repo? I think this leads only to possible duplication and confusion on where to put what.

By the way, sphinx accepts also markdown as input: ​https://www.sphinx-doc.org/en/master/usage/markdown.html

[William Stein]

What's the reason why a wiki is necessary in addition to the main website and the documentation in the main repo?

In the past the wiki was very useful for organizing Sage Days and generally doing things that required quick updates by many people. I think there are much better tools for such activities these days.

[Matthias Köppe]

Replying to Tobias Diez:

What's the reason why a wiki is necessary in addition to the main website and the documentation in the main repo? I think this leads only to possible duplication and confusion on where to put what.

Yes, I agree with you. My proposal is that we can move everything to (1) Trac tickets / GitHub issues, (2) our documentation, (3) www.sagemath.org, and nothing else is needed.

[Kwankyu Lee]

Assuming github migration, Github Pages may be used to build a website to host wiki contents. It seems this website may be maintained by our developer community just like our sage repo.

Just an idea, as I have zero experience with all these. What do you think?

[Kwankyu Lee]

Replying to Kwankyu Lee:

Assuming github migration, Github Pages may be used to build a website to host wiki contents. It seems this website may be maintained by our developer community just like our sage repo.

Ah... This is not different using the current sagemath website as this is in github as well.

Sorry for noise.

[Matthias Köppe]

I went through the same steps of thinking. The only thing that's missing is support for .md files in our website scripts.

[Kwankyu Lee]

Replying to Matthias Köppe:

The only thing that's missing is support for .md files in our website scripts.

That is an important point. Together with liberal write permission to developers, that will make a search-engine-indexed website close to a wiki site...

[Dima Pasechnik]

one can hopefully have the content versioned in git (on GitHub), and then updating automatically, via GitHub Actions, is doable (it's not instant WYSIWYG, but OK)

[Matthias Köppe]

Yes, the source code of our website is maintained on github. ​https://github.com/sagemath/website

I agree, it would be good to add GH Actions that runs what Harald currently runs manually after merging PRs, with a preview of the generated HTML on PRs.

[Kwankyu Lee]

If we end up running self-hosted gitlab (for mirroring, archiving, or replacing github) instead of trac, then we can move wiki to the gitlab as it also has wiki system.