On Mon, Oct 25, 2021 at 03:34:16PM +0200, David Sterba wrote:

On Fri, Oct 22, 2021 at 11:42:14AM -0400, Neal Gompa wrote:

quoted

It'd probably be good if we could eventually convert it to
Sphinx-based documentation like the rest of the Linux kernel
documentation. We could use readthedocs or reuse btrfs.kernel.org for
this.

The way sphinx docs are presented is a bit differnt (more linear whan
the wiki pages web), but I think it could improve discoverability of the
deeper pages. I'm not sure it's suitable for all the content that's
currently on the wiki, there are some free-form looking pages, but eg.
manual pages or FAQ are good candidates.

The only thing that bothers me is that spinx needs RST, yet another
markup language. I haven't found convertors asciidoc -> rst, but the
format is simple and some of the sturucture can be scripted.  It does
not conflict with the goal to have the sources in git and we could have
both output formats, wiki and readthedocs. So, thanks for the suggestion.

A preview of the manual pages is here

https://deleteme12545.readthedocs.io/en/latest/

It's a temporary location because btrfs.readthedocs.io was not free but
I'm in the process of claiming it.

The RST is not much different from the asciidoc syntax so I converted
all the manual pages, the RTD is directly from the devel branch in
btrfs-progs. I'll full switch to RST after 5.15 release, there are some
formatting artifacts still to solve but right now the result is
pleasant.