[CDRIVER-1979] Port docs from Mallard XML to RST Created: 04/Jan/17  Updated: 28/Jan/17  Resolved: 23/Jan/17

Status: Closed
Project: C Driver
Component/s: docs
Affects Version/s: None
Fix Version/s: 1.6.0

Type: Improvement Priority: Major - P3
Reporter: A. Jesse Jiryu Davis Assignee: A. Jesse Jiryu Davis
Resolution: Done Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Related

 Description   

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.


 Comments   
Comment by Githook User [ 28/Jan/17 ]

Author:

{u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}

Message: CDRIVER-1979 simpler RST markup

Now :symbol:`function()` and :symbol:`function` work the same, but let
you choose whether to include parentheses.
Branch: master
https://github.com/mongodb/mongo-c-driver/commit/09f2b423fdbeab49c4c51a8a5b38b949bee850d6

Comment by Githook User [ 28/Jan/17 ]

Author:

{u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}

Message: CDRIVER-1979 simpler RST markup

Now :symbol:`function()` and :symbol:`function` work the same, but let
you choose whether to display parentheses.
Branch: master
https://github.com/mongodb/libbson/commit/5dd827c2a7724cbbb37374912a59561ab873c55f

Comment by Githook User [ 24/Jan/17 ]

Author:

{u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}

Message: CDRIVER-1979 use modern sphinx on evergreen
Branch: master
https://github.com/mongodb/mongo-c-driver/commit/8aed18295b10f0b6a1665b0627ac0f9ee01c125c

Comment by Githook User [ 23/Jan/17 ]

Author:

{u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}

Message: CDRIVER-1979 fix "make dist"
Branch: master
https://github.com/mongodb/mongo-c-driver/commit/16e0b4040aaa66f58fb6ad2e5621593f87c0ad88

Comment by Githook User [ 23/Jan/17 ]

Author:

{u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}

Message: CDRIVER-1979 fix "make dist"
Branch: master
https://github.com/mongodb/libbson/commit/e83e9d833c8a8fae269404567b00561eb42404fd

Comment by Githook User [ 23/Jan/17 ]

Author:

{u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}

Message: CDRIVER-1979 simpler config, copyrights
Branch: master
https://github.com/mongodb/mongo-c-driver/commit/81b3a1fb0f1f27a3294e986e25a6342b51527590

Comment by Githook User [ 23/Jan/17 ]

Author:

{u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}

Message: CDRIVER-1979 fix "make distcheck"
Branch: master
https://github.com/mongodb/mongo-c-driver/commit/5feaf3ed535759001eeb418e83c46b2f5009cf60

Comment by Githook User [ 23/Jan/17 ]

Author:

{u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}

Message: CDRIVER-1979 build docs with sphinx-build
Branch: master
https://github.com/mongodb/mongo-c-driver/commit/1640c4ee1bd9dbbca3ad0c41505ea1e34168b9ef

Comment by Githook User [ 23/Jan/17 ]

Author:

{u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}

Message: CDRIVER-1979 manual fixes for some RST files
Branch: master
https://github.com/mongodb/mongo-c-driver/commit/e348980eb710c561e04794371c823599c4480713

Comment by Githook User [ 23/Jan/17 ]

Author:

{u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}

Message: CDRIVER-1979 convert docs from XML to RST
Branch: master
https://github.com/mongodb/mongo-c-driver/commit/7eac27de507a1f94a5432967fe612b85cc54a3ac

Comment by Githook User [ 23/Jan/17 ]

Author:

{u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}

Message: CDRIVER-1979 sphinx documentation config and theme
Branch: master
https://github.com/mongodb/mongo-c-driver/commit/c63a60e2f611f30a71afc6c30b20f652ed42b960

Comment by Githook User [ 23/Jan/17 ]

Author:

{u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}

Message: CDRIVER-1979 XML fixes to aid RST conversion
Branch: master
https://github.com/mongodb/mongo-c-driver/commit/6564d4684ca34a065609aba0d28ce6ff4950868c

Comment by Githook User [ 23/Jan/17 ]

Author:

{u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}

Message: CDRIVER-1979 sphinx docs cleanups
Branch: master
https://github.com/mongodb/libbson/commit/9e5b5e484bd55ca936ed5ace52545b32a67c3bf6

Comment by Githook User [ 21/Jan/17 ]

Author:

{u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}

Message: CDRIVER-1979 upload docs despite awscli bug
Branch: master
https://github.com/mongodb/libbson/commit/edda1d2ac2981f333f30545e158fdc5b8d905b84

Comment by Githook User [ 21/Jan/17 ]

Author:

{u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}

Message: CDRIVER-1979 don't show "see also" in man pages
Branch: master
https://github.com/mongodb/libbson/commit/f037885371744b3d9fba6bd1b9b43d1c3a9a7eb7

Comment by Githook User [ 21/Jan/17 ]

Author:

{u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}

Message: CDRIVER-1979 fix "make distcheck" for RST files
Branch: master
https://github.com/mongodb/libbson/commit/e78fac5e0b3cae9d467c871dde87babd3fb8ac7d

Comment by Githook User [ 20/Jan/17 ]

Author:

{u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}

Message: CDRIVER-1979 install latest sphinx-build
Branch: master
https://github.com/mongodb/libbson/commit/caa5c1218b6526f73ab71ead89f47ed1d76ff2c7

Comment by A. Jesse Jiryu Davis [ 20/Jan/17 ]

libbson is done, I'm going to do libmongoc now

Comment by Githook User [ 20/Jan/17 ]

Author:

{u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}

Message: CDRIVER-1979 "see also" links in docs
Branch: master
https://github.com/mongodb/libbson/commit/f6104752b9879d5ae3b243bf3330c4a1158166f4

Comment by Githook User [ 18/Jan/17 ]

Author:

{u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}

Message: CDRIVER-1979 build docs with sphinx-build
Branch: master
https://github.com/mongodb/libbson/commit/6a42bf9d59c5454b8539e82e4147dc3825117394

Comment by Githook User [ 18/Jan/17 ]

Author:

{u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}

Message: CDRIVER-1979 convert docs from XML to RST
Branch: master
https://github.com/mongodb/libbson/commit/5b95b6e9fdbd69eea9a283f59fd8bc14436b823e

Comment by Githook User [ 18/Jan/17 ]

Author:

{u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}

Message: CDRIVER-1979 sphinx 1.3 compatibility

Sphinx 1.4 comes with sphinx.ext.githubpages extension, whose sole
feature is to put a .nojekyll file in the root directory of the built
HTML so that GitHub Pages doesn't make bad assumptions.

Sphinx 1.3 is packaged in Ubuntu 14, however, and doesn't ship with the
extension, so vendor it.
Branch: master
https://github.com/mongodb/libbson/commit/4a52f8af01988049d06c9121a5074a87bee9cc41

Comment by Githook User [ 18/Jan/17 ]

Author:

{u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}

Message: CDRIVER-1979 sphinx documentation config and theme
Branch: master
https://github.com/mongodb/libbson/commit/c7f5221cd2b885be4bd6036127701f64f495a907

Comment by Githook User [ 18/Jan/17 ]

Author:

{u'username': u'ajdavis', u'name': u'A. Jesse Jiryu Davis', u'email': u'jesse@mongodb.com'}

Message: CDRIVER-1979 XML fixes to aid RST conversion
Branch: master
https://github.com/mongodb/libbson/commit/3d70c28f908ad2919e96ed8538f1234c2c69400e

Generated at Wed Feb 07 21:13:47 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.