Sponsored By Aspose - File Format APIs for .NET

Aspose are the market leader of .NET APIs for file business formats – natively work with DOCX, XLSX, PPT, PDF, MSG, MPP, images formats and many more!

Sphinx – A better way to write your docs

In the cool things I am stealing from the python community, I would like to introduce you to Sphinx. Sphinx is a frigging amazing documentation tool. Its amazing because:

  • it is simple: its just plain text formatted in reStructuredText
  • its easy to check into source control
  • has a build process that is easy to hook into.
  • it has a quick start command line (crap masstransit/dropkick/uppercut/fubumvc could all be a lot more awesome with this kind of support)
  • you can view source doc source
  • its easy to deploy multiple copies
  • it has built in non-server based search
  • Like most things python, it works on *nix and Windows. :)

A sample of reStructuredText

    Conventions
    """""""""""

    Code
    ''''

    Through out this book we will be exposing snippets of code in various languages.
    They should all look something like

    .. sourcecode:: csharp
        public void CodeLooksLikeThis()
        {
        }

Like python, sphinx is ‘white space aware’ meaning that the white space has meaning. So indents in python/sphinx are like { } in C# [which are known as seagulls?]. Which can take a bit to get used to, but I find quite helpful actually. In this sample the “”””” and ””” are what denotes headings or sections (the double meaning h1 the single meaning h2, in this case, and its actually more of an HTML5 kind of heading). If you walk through the sphinx docs you will find lots of examples and an amazing amount of power.

More samples of docs written in Sphinx (don’t forget to click the ‘show source’)

A friend of mine Eric H has also setup a place to host docs should you be in need. It’s called readthedocs.org or as I like to refer to it RTFD :)

Lazy Web: Would someone please take on the challenge of writing a language domain file thingy for C# so that I can pull in snippets of C# like they can for python, ruby, javascript, C, and C++? Here is the source to the ruby domain for any one interested.

So there you go. An excellent way to docs, and it outputs many different styles (HTML,PDF,ePub and more).

-d

About Dru Sellers

Sr. Software Engineer at Dovetail Software.
This entry was posted in python. Bookmark the permalink. Follow any comments here with the RSS feed for this post.
  • Anonymous

    No joke right? But each one has its own approach. Pick one and rock it. I choose this one, because i do a lot of side stuff in python and really enjoy it.

  • Anonymous

    Nice, thanks for sharing.

  • http://murrayon.net/ Mike Murray

    Here’s an interesting way of doing documentation for the NSubstitute project using markdown and Jekyll, and then creating some custom rake tasks that would compile the code samples in the documentation against the current codebase: http://www.davesquared.net/2010/10/interesting-documentation.html

  • http://www.facebook.com/people/Lulu-Gu/100001785608380 Lulu Gu

    Article is very interesting,thanks for your sharing.I will visit this site.And welcome to wedding dresses online shop.We supply supply high quality Cheap bridal gowns,wedding dresses 2011.We have run dress business 20 years and you can trust us completely.Our wedding dresses shop have Evening Dresses,Prom Dresses,mother of the bride dresses,A-Line Wedding Dresses,Empire Wedding Dresses,Bridesmaid Dresses and so on.You can find your dream Beach Wedding Dresses here.We do retail and wholesale wedding dresses business.Choose http://www.bridalgownsstore.com/, get your bridal gowns and Ball Gown Wedding Dresses right now!

  • Olivier

    Cool! I only wish there was a standard in this sort of doc languages (Markdown, RST…)

  • Polite and Reasonable

    “…you should consider consider voting up this post on DZone” Do NOT tell me what to do. Say nothing, or ask politely. Because even if I was already inclined to do what you’re rudely telling me to, of course there’s no way I would after reading something like that is there?