[LUDOC-398] Methodology to keep manual in sync with man pages

• Status: Open
• Project: Lustre Documentation
• Type: New Feature
• Priority: Major
• Reporter: Joseph Gmitter (Inactive)
• Assignee: Joseph Gmitter (Inactive)
• Resolution: Unresolved

Description

Per Andreas' comment on LUDOC-264:

We should make some kind of automated process to import man pages from the Lustre source into the manual, or just remove them from the manual and reference some website that will do man page rendering for us. Keeping the manual up-to-date by hand is bound to be a losing battle, it is hard enough to keep the actual man pages in sync.

Issue Links

• is related to: LUDOC-264 New "-o" option for setstripe missing...

Comments

[Joseph Gmitter (Inactive)]

Andreas,

I have proposed solutions to this issue.

First Solution:

• Host the rendered man pages on readthedocs.org (https://readthedocs.org) for free. I would create a public GitHub repo that contains the following:
• A script that regularly polls the lustre source tree and performs a conversation from a man format to a standard, web-ready rendering language (such as markdown, restructredtext, etc...)
• Translated artifacts for each man page
  Those translated artifacts will then automatically be picked up by ReadTheDocs.org and displayed in a very user friendly format with search functionality, etc... already built-in.

Second Solution:
An alternative solution would be to use a script to generate man to html conversion from every man page in the lustre tree and put them somewhere for lustre.org to grab them and put them into a directory that one could navigate from a browser and see each individual html file.

The benefit of the first solution is the 'extras' you get for no effort, such as search functionality across all man pages, ability to download in pdf, etc... The benefit of the second solution would be it stays within lustre.org.

Any thoughts? Just trying to clean this up ahead of 2.13.

[Andreas Dilger]

I'm fine with either approach. I guess one benefit of hosting them on Lustre.org is that it makes users more aware of that site. However, I don't know how easily content is added there, so I leave it to you to decide based on which solution is the least effort.

[Gerrit Updater]

Joseph Gmitter ([e-mail]) uploaded a new patch: https://review.whamcloud.com/36120
Subject: LUDOC-398 build: automatically include man pages
Project: doc/manual
Branch: master
Current Patch Set: 1
Commit: c5d4167afa5b5773dd2b74880f6ca23dced4ec23

[Joseph Gmitter (Inactive)]

It is still in testing, but I have a solution for this that keeps the man page conversions local to the manual and does not require any external hosting at all. I have verified that it works locally for html building of the manual, but need to get it working in Jenkins and see how it does with the PDF conversion.

[Gerrit Updater]

.