change docs from Sphinx to something else?

[reidpr]

Since we are working just now on fixing a search bug (#748), I am reminded that I dislike dealing with the documentation and wonder if we should change to something else. What annoys me:

• It's buggy. E.g., it took ages to fix the list spacing bug introduced in 2.x.
• Search is bad. Even after PR #834, search won't work right; e.g., it says "ch-grow" and "ch-run" have no results.
• I dislike ReST. For example, you can't nest markup like monospace (code) within bold or italic. (Note I don't care much better for Markdown, despite its trendiness.)
• It interacts weirdly with Make. For example, it re-builds the docs frequently for reasons I don't understand and seem unnecessary (make install will always rebuild the docs, twice IIRC).
• Even the supposedly top-of-the-line Read-the-Docs theme makes a lot of ugly choices, e.g. monospace for in-line code is bright red and boxed. Other themes don't seem any better.
• In general, Sphinx has been troublesome and a hassle.

Our requirements are something like:

• Decent HTML pages we can put on github.io or similar.
• Decent man pages, because packagers like those.
• Needs to be easy to package even on crusty distros like CentOS 7.
• We don't currently have any need to auto-generate API docs.

Options include:

• Keep Sphinx, and:
  • accept the cruddy search
  • remove the search box, letting users use a general web search e.g. Google
  • replace the search box with a link to Google site search
  • wire up the search box as Google site search somehow
  • use readthedocs.io, which has a better search
• Ditch Sphinx in favor of:
  • LaTeX: real professional tool, very nice PDF output, HTML and man pages less so
  • GNU Texinfo: real professional tool, old/obsolete, plays well with Autotools, PDF works, HTML looks old, no native man output
  • ... ?

[tbugfinder]

Asciidoc & Antora might be another option.

[reidpr]

Doxygen has been recommended.

[reidpr]

Write man pages directly, convert to HTML.

[reidpr]

LilyPond docs have been advertised as having good web output from Texinfo. It's not horrendous.

[reidpr]

@wiene : You're a thoughtful person. Do you have an opinion on this?

[wiene]

@wiene : You're a thoughtful person. Do you have an opinion on this?

I agree with your requirement list but unfortunately I do not have noteworthy expertise in this field. Therefore I cannot contribute anything useful to this topic.