Are you asking about the old FAQ at https://www.open-mpi.org/faq/?
Or are you asking about the new docs for the upcoming v5.0.x (and beyond) at https://docs.open-mpi.org/? The old FAQ is basically hand-written PHP. When we started the FAQ, we couldn't find any suitable tools/libraries to do a FAQ in the context of our existing web site, so we wrote a handful of helper PHP functions to render all the FAQ questions/answers. It supports a fairly primitive / limited wiki-style markup for the answers. Over time, it has definitely shown its age and lack of features. It has no Open MPI version separation for the answers, which makes organization difficult, especially if the answer to a given FAQ topic changes with different versions of Open MPI. It has other unattractive aspects, too, in that Open MPI's docs are spread across multiple sources: the README, INSTALL, HACKING files, nroff (!!) man pages, the FAQ, the "Getting help" page on the web site, ... (and possibly some other places I'm not remembering off the top of my head). That being said, you're welcome to steal the PHP from the current web site and adapt it to your needs. For >= v5.0.0, we consolidated all​ the docs into a tree of ReStructuredText (RST) files under docs/ in the main git repo. RST is like Markdown on steroids. It's nowhere near as complicated (or powerful) as LaTeX, for example, but it's definitely more capable that Markdown (e.g., you can include files, have actual cross-references, use macros, etc.). See https://docs.open-mpi.org/en/v5.0.x/developers/rst-for-markdown-expats.html for the RST guide we provide to the OMPI developers. These RST docs are rendered by the Sphinx tool into HTML and nroff for the man pages. The HTML is self-contained, so it can be hosted on a web site or viewed locally in a web browser with no web server (and is therefore included in the v5.0.x tarballs). The ReadTheDocs.io site does free hosting of RST/Sphinx docs, and has excellent integration with Github (e.g., it renders pull requests into sandbox areas, supports per-branch and tag [i.e., per version and series] docs, and automatically re-renders a branch's HTML whenever a PR is merged). We're not 100% complete in converting all the old content to RST yet -- there's still a few FAQ sections still in "FAQ" format (that content will eventually be folded into the same style as the rest of the documentation), and we still need some formal documentation of PRRTE and PMIx, but PR's for the beginnings of those docs are pending. If you're looking at doing documentation for some project (FAQ-style or otherwise), I would recommend using RST/Springs/ReadTheDocs.io (vs. hand-coding some janky PHP solution on your own). I've been very happy with it. -- Jeff Squyres jsquy...@cisco.com ________________________________ From: devel <devel-boun...@lists.open-mpi.org> on behalf of Paul H. Hargrove via devel <devel@lists.open-mpi.org> Sent: Tuesday, December 20, 2022 7:09 PM To: Open MPI Developers <devel@lists.open-mpi.org> Cc: Paul H. Hargrove <phhargr...@lbl.gov>; Dan Bonachea <dobonac...@lbl.gov> Subject: [OMPI devel] How do you generate your FAQ pages? Sorry for the somewhat off-topic question: What tool(s) are you using to generate web pages for your wonderfully organized FAQ? -Paul -- Paul H. Hargrove <phhargr...@lbl.gov<mailto:phhargr...@lbl.gov>> Pronouns: he, him, his Computer Languages & Systems Software (CLaSS) Group Computer Science Department Lawrence Berkeley National Laboratory
