Add man pages

[gmelikov]

• original pages are converting into HTML by mandoc itself
• script integrates resulting HTML into rst structure
• special CSS file added for a pretty view
• sphinx static search works for man pages too in this case
• interesting side effect: HTML preview of man pages can show flaws in original syntax, so any non-CSS problems with man pages should be fixed in original file

Preview: https://gmelikov.github.io/openzfs-docs/man/

[rlaager]

I haven't looked at the output, but the idea is great. I made a few comments on minor things.

[rlaager]

I see you linked to the output. Yeah, at first glance, the output looks great too!

[behlendorf]

The pages look great!

[behlendorf]

Always generating the man page from master is the right first step. But I think we should consider early on how we're going to handle generating documentation for multiple versions of OpenZFS. Adding a "Docs by version" section to the sidebar as was done for the Python documentation would be a nice way to handle this. Let's make sure to leave ourselves some options since I'm not sure how difficult it would be to add this kind of thing latter.

[gmelikov]

You're right, I thought about it too. Looks like it would be pretty easy, because now we generate docs. We may use one of sphinx modules for that, for ex. https://github.com/sphinx-contrib/sphinxcontrib-versioning to get versioned docs + man pages via script addtions.

Worst thing that may get us is different links and the need to manage redirects. In this case I prefer some 404 links from other sites but we get faster publication -> better docs now.

[ahrens]

It looks like there's a rendering issue where this appears to say zfssetproperty=value when it should be zfs set property=value. Seems that all similar places have the same issue.

Looks like most of the blue-text-chunks have this issue:

[ahrens]

This looks great! Could we consider highlighting the "main" manpages, e.g. zfsconcepts, zfs, zpool? They kind of get lost among the subcommands and things that are not as relevant to sysadmins (e.g. fsck.zfs, zdb).

[ahrens]

I noticed that when another manpage is mentioned, it is a HTML link, but clicking on it doesn't seem to do anything. Is that just an issue with the preview, or do we need to fix something so that it will work? (This is on Safari 13.1.1 on OSX.)

[gmelikov]

Thanks everybody for the feedback, i'll address it soon!

@ahrens making links active is in my plan, you can see it in issue #2 and comment what we might see there too.

[gmelikov]

It looks like there's a rendering issue where this appears to say zfssetproperty=value when it should be zfs set property=value. Seems that all similar places have the same issue.

It was chrome-specific, fixed, thank you for catching that!