Search Unity

Writting a pretty documention

Discussion in 'General Discussion' started by Estecka, Aug 23, 2018.

  1. Estecka

    Estecka

    Joined:
    Oct 11, 2013
    Posts:
    62
    I'm looking into writting some documentation for some of my C# code, not only the XML comments inlined within the code itself (that I do already), but something more similar to unity's Manual and API websites. (If I could have the exact same look as this, I would take it.)

    Considering I'm completely new to this, what are the tools and means commonly used to write this kind of documentation ?

    After having a look at the existing tools; I liked the look of Read the Docs but couldn't figure out how it even work; Right now my best bet is on GitBook.
     
  2. Antypodish

    Antypodish

    Joined:
    Apr 29, 2014
    Posts:
    10,778
    Often such are made, based on some form of wiki templates. But not only.
    Firstly you would have to have some form of server. For starter you could grab local PC server, which you install on your own machine. Or grab any online web provider. Advising avoid GoDaddy, as you can loose ownership, to what you store there, if you not careful.
    Personally I like x10hosting.com, but there is plenty other choices.
    You need server with DB of course.
    There are ways without DB. But you are loosing on functionality and flexibility.

    Since I don't use similar features for strictly scripts, I used simpler way with Wikimedia (not wikipedia), which you can install on any server. Is relatively lightweight version of wiki. You can tailor look, to your need with css.
    The biggest part is to find right and suitable template. Or make it for your self.

    Also, lot of people are using wordpress. But I never came close to use it. Neither I want to. So I will not be able to advise.

    And also many other ways too.

    Once you have set up you server with a page, you can start inserting data. Then just periodically need do backup, for safe keeping.
     
  3. angrypenguin

    angrypenguin

    Joined:
    Dec 29, 2011
    Posts:
    15,620
    Are you talking about writing the docs pages manually? There are definitely tools to automate this process.

    One of them is called SandCastle, though I've not used it personally to know what output formats it supports. Here's some people talking about this stuff.
     
    Antypodish likes this.
  4. TonyLi

    TonyLi

    Joined:
    Apr 10, 2012
    Posts:
    12,697
    Of the free generators that you can host on your own server/locally, I think Sphinx generates the prettiest documentation. (See their Examples page for some good examples of various themes.)

    If you customize the CSS, Doxygen can also generate very nice, very usable API documentation. It's one of the easiest to get working, and it works out of the box with your existing inline XML.

    There's also an older forum discussion here about generating documentation and help links that might offer some useful info.
     
    Billy4184 and Antypodish like this.