share/man/nitdoc.md

   1 % NITDOC(1)
   2
   3 # NAME
   4
   5 nitdoc - generates HTML pages of API documentation from Nit source files.
   6
   7 # SYNOPSIS
   8
   9 nitdoc [*options*]... FILE...
  10
  11 # DESCRIPTION
  12
  13 `nitdoc` takes one or more modules and generate HTML pages of API documentation for these modules and their imported modules.
  14
  15 The documentation is extracted from the comments found above the definition of modules, classes, and properties.
  16
  17 Internally, `nitdoc` relies on the presence of the `dot` command from the [graphviz] project.
  18 If the dot program is not present or not found, no image of hierarchies are generated.
  19 See option `--no-dot`.
  20
  21 The documentation of the Nit [standard library] is generated with this tool.
  22
  23   [graphviz]: http://www.graphviz.org
  24   [standard library]: http://nitlanguage.org/doc/stdlib
  25
  26 # DOCUMENTATION FORMAT
  27
  28 The format of the documentation is a dialect of [markdown] that allows GitHub fences (`~~~`).
  29
  30 Code blocks are interpreted as snippets of Nit programs and intended to be used as examples of code.
  31 When these code snippets are valid, executable and contain at least and `assert` clause, they could be automatically executed and verified.
  32 See niunit(1) for details.
  33
  34   [markdown]: http://daringfireball.net/projects/markdown
  35
  36 # OPTIONS
  37
  38 `-d`, `--dir`
  39 :   output directory.
  40
  41     Where the HTML files are generated.
  42
  43     By default, the directory is named `doc`.
  44
  45 `--source`
  46 :   Format to link source code.
  47
  48     The format string is used to generated links to some parts of the source-code.
  49     Use `%f` for filename, `%l` for first line, and `%L` for last line.
  50
  51     For instance, the [standard library] use the following value to link to files in GitHub:
  52
  53         "https://github.com/privat/nit/blob/$(git rev-parse HEAD)/%f#L%l-%L"
  54
  55     Here, the `git rev-parse HEAD` is used to link to the current snapshot revision of the file.
  56
  57 `--no-attribute`
  58 :   Ignore the attributes.
  59
  60     Note: In Nit, attributes are private. Therefore, this option is only useful
  61     when combined with `--private`.
  62
  63 `--no-dot`
  64 :   do not generate graphs with graphviz.
  65
  66 `--private`
  67 :   also generate private API.
  68
  69 ## CUSTOMIZATION
  70
  71 `--sharedir`
  72 :   directory containing nitdoc assets.
  73
  74     By default `$NIT_DIR/share/nitdoc/` is used.
  75
  76 `--shareurl`
  77 :   use shareurl instead of copy shared files.
  78
  79     By default, assets from the sharedir a copied into the output directory and refered with a relative path in the generated files.
  80     Whith this option, the assets are not copied and the given URL of path is used in the generated files to locate assets.
  81
  82 `--custom-title`
  83 :   custom title for homepage.
  84
  85 `--custom-footer-text`
  86 :   custom footer text.
  87
  88 `--custom-overview-text`
  89 :   custom intro text for homepage
  90
  91 `--custom-brand`
  92 :   custom link to external site
  93
  94 ## SERVICES
  95
  96 `--github-upstream`
  97 :   Git branch where edited commits will be pulled into (ex: user:repo:branch)
  98
  99 `--github-base-sha1`
 100 :   Git sha1 of base commit used to create pull request
 101
 102 `--github-gitdir`
 103 :   Git working directory used to resolve path name (ex: /home/me/myproject/)
 104
 105 `--piwik-tracker`
 106 :   Piwik tracker URL (ex: `"nitlanguage.org/piwik/"`)
 107
 108 `--piwik-site-id`
 109 :   Piwik site ID
 110
 111 # SEE ALSO
 112
 113 The Nit language documentation and the source code of its tools and libraries may be downloaded from <http://nitlanguage.org>