building the API documentation from source

Posted: 03/09/09 20:58:18

Hmmm, well it looks like some kind of specialized build process is used on the dsource trac server to build the docs. The good news I discovered is that we can build our own with "dsss build --doc". The bad news is that each API page is in a subfolder (like tango/core), and these don't correlate to the depth of the package (for example tango.core.sync.Barrier in just "Barrier.html" in the tango/core folder). Another bad thing is that a handy "Package" tab is in the outline view, but the links are useless because they aren't named properly. On the plus side, the candydoc generation seems to be a little nicer than what's on the actual site.

So to fix this, I wrote a tiny D program that renames each html file to the name corresponding to it's package name, which matches what is online and what the Package tab wants. There are probably lots of better ways to do this, but here it is:

import tango.io.File;
import tango.io.FileScan;
import tango.io.Stdout;
import Text = tango.text.Util;

void main()
{
  auto scan = new FileScan;
  scan(".", ".html");

  foreach(file; scan.files)
  {
    auto content = cast(char[]) File(file.toString()).read;

    foreach(line; Text.lines(content))
      if(Text.containsPattern(line, "<title>"))
      {
        auto dotname = line[7 .. line.length - 8]; 
        Stdout.formatln("Renaming {} to {}.html", file, dotname).newline;
        file.rename(dotname ~ ".html");
        break;
      }
  }
}

This should be place in and run from the dsss_docs folder that is created when the "dsss build --doc" command is used. One other thing that should be done after it's finished is to go into one of the subfolders, like dsss_docs/tango/core, and copy the candydoc folder into the top dsss_docs folder. Without that step the pages will look awful, and you won't get the nice outline and package tree. I should probably add that into the program, along with an index page. Anyway, the result is pretty and handy (and pretty handy :)

Posted: 03/11/09 23:38:13

Hi obijohn,

You wrote in my channel, but I noticed that only on the next day, sorry.

Regarding compiling dil and Tango: I haven't upgraded to Tango 0.9.8 yet, because I'm not motivated enough to compile Tango myself atm. However, I will try to make the code compilable with .7 and .8. I don't know why you have problems with isUniAlpha. Do you get compiler or linker errors?

Regarding Python: Sounds like I should upgrade to 2.6. I'm not sure but the scripts should work with 2.6 as well.

Posted: 03/16/09 02:19:29

  File "scripts/tango_doc.py", line 32
    revision = "?rev=" + revision if revision != None else ''
                                   ^
SyntaxError: invalid syntax

I suspect that you have multiple Python installations on your Mac, and you are somehow using one older than 2.5. (The ternary operator is added in Python 2.5.) With Python 2.2.2, I get the same SyntaxError: invalid syntax error.

-- MIURA Masahiro echochamber@gmail.com