https://jira.whamcloud.com This file is an XML representation of an issue en-us 9.4.14 940014 05-12-2023 https://jira.whamcloud.com/browse/LUDOC-398 Lustre Documentation <p>Per Andreas' comment on <a href="https://jira.whamcloud.com/browse/LUDOC-264" title="New &quot;-o&quot; option for setstripe missing from manpage and usage" class="issue-link" data-issue-key="LUDOC-264"><del>LUDOC-264</del></a>:</p> <p>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.</p> LUDOC-398

Methodology to keep manual in sync with man pages

New Feature Major Open Unresolved Joseph Gmitter Joseph Gmitter Wed, 11 Apr 2018 17:33:59 +0000 Mon, 5 Jul 2021 14:48:19 +0000 0 5 <p>Andreas,</p> <p>I have proposed solutions to this issue.</p> <p>First Solution:</p> <ul class="alternate" type="square"> <li>Host the rendered man pages on readthedocs.org (<a href="https://readthedocs.org" class="external-link" target="_blank" rel="nofollow noopener">https://readthedocs.org</a>) for free. I would create a public GitHub repo that contains the following:</li> <li>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...)</li> <li>Translated artifacts for each man page<br/> 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.</li> </ul> <p>Second Solution:<br/> 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.</p> <p>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.</p> <p>Any thoughts? Just trying to clean this up ahead of 2.13.</p> <p>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. </p> <p>Joseph Gmitter (jgmitter@whamcloud.com) uploaded a new patch: <a href="https://review.whamcloud.com/36120" class="external-link" target="_blank" rel="nofollow noopener">https://review.whamcloud.com/36120</a><br/> Subject: <a href="https://jira.whamcloud.com/browse/LUDOC-398" title="Methodology to keep manual in sync with man pages" class="issue-link" data-issue-key="LUDOC-398">LUDOC-398</a> build: automatically include man pages<br/> Project: doc/manual<br/> Branch: master<br/> Current Patch Set: 1<br/> Commit: c5d4167afa5b5773dd2b74880f6ca23dced4ec23</p> <p>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.</p> <p>.</p> Related LUDOC-264 Development Rank 1|hzzvof: Rank (Obsolete) 9223372036854775807