Maintainable Documentation with Sphinx

Maintainable Documentation with Sphinx

If you’re going to do it you should do it well.

About Stacy Vicknair

Technical Product Manager for Prime Occupational Medicine Over 10 years in software development and design Certifications:

Professional Scrum Master (PSM-I) Distinguished Toastmaster (DTM) Numerous Microsoft certifications in .NET development and ALM

Awards: Microsoft MVP, 2009 - 2014

Agenda

What is Sphinx? Sphinx versus DocFX Demo Resources

What is Sphinx?

Python based documentation generator Uses reStructuredText (ReST) and can also be used with Markdown Can output to a variety of formats:

HTML PDF ePub

Even Microsoft uses used it for their documentation!

Microsoft stopped using it…

because they rolled their own solution.

So how do they compare?

Sphinx Python-based Favors ReST, supports

Markdown Supports document generation

for object models (Python, C, C++, C#)

Out of the box support for numerous output formats, supports custom renderers

DocFX .NET-based, requires Node.js Markdown only Supports document generation

for object models (C# or VB.NET)

Outputs as HTML, does not currently support custom renderers

Demo

Resources

GitHub Examplegithub.com/svickn/SphinxExample

Sphinx Documentationsphinx-doc.org