We currently write our docs in Mallard XML and generate HTML from it with yelp-build, and man pages with a homemade Python script. This has disadvantages:

• Ungainly and verbose format to write
• Restrictive: documents must link to each other in a certain way
• Hard to customize or extend, even if you know XSLT
• We must convert to man pages with our own very buggy script
• Tiny community, little documentation, no ecosystem

Let's switch to something easy to write, flexible, customizable, and extensible, with a big community. Our new documentation format of choice should officially support both HTML and man page output.

Jesse evaluated MkDocs, ASCIIDoc, Doxygen, and Sphinx, and settled on Sphinx. Sphinx is a Python package that renders ReStructured Text (RST) to a number of formats including HTML and man. It's one of the most widely-used documentation generators, and it has a huge ecosystem of documentation, examples, themes, and extensions.

Steps:

• Write a script to bulk-convert XML to RST for Sphinx.
• Check the generated RST and fix up by hand.
• Extend Sphinx to style links to C symbols with fixed-width font.
• Choose an HTML theme and customize it for the C Driver.
• Use Intersphinx to link from libmongoc's docs to libbson's.
• Update the libbson and mongo-c-driver Autotools build scripts to use Sphinx instead of yelp-build.
• Update Evergreen configuration.