Project

General

Profile

Use sphinx + read the doc for documentation?

Added by Skoll RC 10 months ago

Hi everyone!

Most of popular opensource projects use shpinx + read the doc for documentation. It's clear (much more than redmine's wiki), and version/code related.
What about using this for Replicant?

The actual documentation is a mess (it exists and it's a good start). Maybe it could help to improve the visibility and usability of Replicant.

https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html


Replies (7)

RE: Use sphinx + read the doc for documentation? - Added by Kurtis Hanna 10 months ago

We are looking to leave Redmine for a number of reasons, including limitations we have experienced with its wiki.

One idea we have is to move to MediaWiki. We talk about that here: https://redmine.replicant.us/projects/replicant-infrastructure/wiki/MediawikiMigration

RE: Use sphinx + read the doc for documentation? - Added by Skoll RC 10 months ago

It is also hard to have clear and structured infos with mediawiki. But at least any could export data from mediawiki.

RE: Use sphinx + read the doc for documentation? - Added by Daniel Kulesz 9 months ago

Personally, I am in favor of OP's suggestion and recommend switching to Sphinx as well. I find working on documentation and approving changes using git much more "floss-natural" than giving permission to "trusted" authors only when using a system like mediawiki. Imho, the latter puts up a significantly higher hurdle for new docs contributors.

RE: Use sphinx + read the doc for documentation? - Added by Fil Lupin 8 months ago

Hi,
I wonder if mediawiki would not be easier to use with wikidata, especially it could help include wikidata elements for hardware by using SPARQL requests.
But my hope is only based on the fact that this tool is close to the ones used by wikidata.

RE: Use sphinx + read the doc for documentation? - Added by Denis 'GNUtoo' Carikli 3 months ago

The issue with sphinx is that it would automatically exclude people who don't know programming from contributing.

Learning programming seems hard for many people.

The idea behind Mediawiki is also to be able to mix within the same wiki contributions from people that want to program and from people that don't know how to program.

This can be done through inclusion of sub-pages, templates and so on.

It also has some advantages that you find in git too, like the ability to export the content for offline view with some tools, and it's probably doable to contribute to it with git directly with the git-mediawiki package that is available in Trisquel 8. I probably need to find a way to package that in Parabola as well at some point.

Enabling non programmers to contribute has many advantages:
  • Not being able to contribute to a project under a free license (for instance if you don't know how to program) is a practical freedom issue. So it's best to avoid it whenever possible.
  • Excluding non programmers would mean that the current Replicant developers would have even more work to do at the beginning. With a wiki we can do the transition at the speed we want.

The mess is also due to the type of documentation we use.

Having a comprehensive documentation like the Guix manual avoid such mess but I don't see how we could use something like that for Replicant yet. Here the structure of such documentation is very well suited for Guix as everything is tightly integrated together and well separated too. As far as I know this is not really the case with Replicant.

For instance we have a lot of work in progress documentation that is written in a hurry and that is still extremely useful as-is.

So I hope that with Mediawiki we could take advantage of its features to better organize the content and maybe one day be able to produce more compressive documentation.

RE: Use sphinx + read the doc for documentation? - Added by Denis 'GNUtoo' Carikli 3 months ago

Also. so far no one had the time to do the actual migration or even start looking if there is some software that could preserve the history while doing the migration.

RE: Use sphinx + read the doc for documentation? - Added by dl lud 20 days ago

I and _I3^ RELATIVISM just found out that git-mediawiki is already available on Parabola, albeit through a different name.

TL;DR

pacman -S git perl-mediawiki-api perl-datetime-format-iso8601 perl-lwp-protocol-https

That's all you need to get the MediaWiki remote for git working. You can then run stuff such as:

git clone -c remote.origin.pages='Replicant_(operating_system)' mediawiki::https://en.wikipedia.org/w/

Details

The MediaWiki remote for git was once a separate project, on it's own repo: https://github.com/Git-Mediawiki/Git-Mediawiki
But is is now merged into git: https://github.com/git/git/tree/master/contrib/mw-to-git
Debian still has a split package for git-mediawiki, probably due to compatibility reasons. Whereas Arch just packages everything inside the git package and then lists the optional dependencies needed to get the MediaWiki remote working:

perl-mediawiki-api: git mediawiki support
perl-datetime-format-iso8601: git mediawiki support
perl-lwp-protocol-https: git mediawiki https support

    (1-7/7)