Thread: Framework to write documentation

  1. #1
    Informer -Adrian's Avatar
    Join Date
    Jan 2013
    Posts
    830

    Post Framework to write documentation

    I have made it a habit to self-document the configuration settings (and idiosyncrasies) of programs I use, so that I can quickly reinstate them in case of a new OS installation, without having to chase manuals.

    Currently, I do this in plain text format with a few symbols like brackets for special meaning. As the texts grow larger, I feel a need to switch to a more pleasant way to read and navigate them.

    My current idea is to switch to "markdown" notation (or a fork of it) for the docs and then have a script build a tree of HTML pages from that. This way I could edit my files as before, but have something nicer for reading.

    If you guys have any better suggestions, I'd love to hear them.

  2. #2
    (?<!re)tired Mario F.'s Avatar
    Join Date
    May 2006
    Location
    Ireland
    Posts
    8,446
    Well, I have been using Sphinx for a few years and don't plan to change for any reason. reStructuredText is better adapted to this type of work on which you want your technical documentation to follow a program structure and is a de facto documentation generator tool, the likes of Doxygen. Markdown is better suited as writing tool for vertical reading manuals, not documentation. Although once you get used to reStructuredText, you can (and you probably will want) to use it also for vertical writing material of any sorts, since the sphinx toolset offers tremendous ability in creating very nice looking reading material for the web or in offline formats. At the expense of a little more verbosity in the material source, but nothing to cry about.
    Originally Posted by brewbuck:
    Reimplementing a large system in another language to get a 25% performance boost is nonsense. It would be cheaper to just get a computer which is 25% faster.

  3. #3
    Informer -Adrian's Avatar
    Join Date
    Jan 2013
    Posts
    830
    Sphinx looks really good Mario, specifically these bullets:

    • Output formats: HTML (including Windows HTML Help), LaTeX (for printable PDF versions), ePub, Texinfo, manual pages, plain text
    • Hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents and children
    • Code handling: automatic highlighting using the Pygments highlighter

    I'll give it a test run with some dummy data.

  4. #4
    Registered User MutantJohn's Avatar
    Join Date
    Feb 2013
    Posts
    2,665
    As someone who's seen markdown used for documentation, I must agree with Mario, don't use markdown for actual documentation.

    Granted, I know the documentation for something like the V8 API is generated with Doxygen but it sorely lacks an entry point if you're unfamiliar with the library. It's just lists things like all the classes, namespaces, etc. without any sort of helper info.

  5. #5
    Informer -Adrian's Avatar
    Join Date
    Jan 2013
    Posts
    830
    I just want to report back that I'm pretty satisfied with Sphinx, that was a good recommendation. It's not too difficult to set up and have version control on the user-written documents. Cheers!

Popular pages Recent additions subscribe to a feed

Similar Threads

  1. C# without .NET framework
    By heisel in forum C# Programming
    Replies: 2
    Last Post: 10-04-2009, 01:37 PM
  2. C++ API Documentation
    By Ari.Patrick in forum C++ Programming
    Replies: 4
    Last Post: 06-12-2006, 05:08 AM
  3. How to write source code documentation?
    By loobian in forum C++ Programming
    Replies: 2
    Last Post: 06-07-2005, 11:49 AM
  4. A C++ GUI Framework
    By jinhao in forum Projects and Job Recruitment
    Replies: 0
    Last Post: 05-11-2005, 06:34 AM
  5. Documentation Help!
    By WinAmp in forum C Programming
    Replies: 8
    Last Post: 05-19-2002, 03:21 AM

Tags for this Thread