# NAME
-Generates HTML pages of API documentation from Nit source files.
+nitdoc - generates HTML pages of API documentation from Nit source files.
-# SYNOPSYS
+# SYNOPSIS
-nitdoc [*options*]...
+nitdoc [*options*]... FILE...
-# OPTIONS
+# DESCRIPTION
-`-W`, `--warn`
-: Show more warnings
+`nitdoc` takes one or more modules and generate HTML pages of API documentation for these modules and their imported modules.
-`-w`, `--warning`
-: Show/hide a specific warning
+The documentation is extracted from the comments found above the definition of modules, classes, and properties.
-`-q`, `--quiet`
-: Do not show warnings
+Internally, `nitdoc` relies on the presence of the `dot` command from the [graphviz] project.
+If the dot program is not present or not found, no image of hierarchies are generated.
+See option `--no-dot`.
-`--stop-on-first-error`
-: Stop on first error
+The documentation of the Nit [standard library] is generated with this tool.
-`--no-color`
-: Do not use color to display errors and warnings
+ [graphviz]: http://www.graphviz.org
+ [standard library]: http://nitlanguage.org/doc/stdlib
-`--log`
-: Generate various log files
+# DOCUMENTATION FORMAT
-`--log-dir`
-: Directory where to generate log files
+The format of the documentation is a dialect of [markdown] that allows GitHub fences (`~~~`).
-`-h`, `-?`, `--help`
-: Show Help (This screen)
+Code blocks are interpreted as snippets of Nit programs and intended to be used as examples of code.
+When these code snippets are valid, executable and contain at least and `assert` clause, they could be automatically executed and verified.
+See niunit(1) for details.
-`--version`
-: Show version and exit
+ [markdown]: http://daringfireball.net/projects/markdown
-`--set-dummy-tool`
-: Set toolname and version to DUMMY. Useful for testing
+# OPTIONS
-`-v`, `--verbose`
-: Verbose
+`-d`, `--dir`
+: output directory.
-`--bash-completion`
-: Generate bash_completion file for this program
+ Where the HTML files are generated.
-`--stub-man`
-: Generate a stub manpage in pandoc markdown format
+ By default, the directory is named `doc`.
-`--disable-phase`
-: DEBUG: Disable a specific phase; use `list` to get the list.
+`--source`
+: Format to link source code.
-`-I`, `--path`
-: Set include path for loaders (may be used more than once)
+ The format string is used to generated links to some parts of the source-code.
+ Use `%f` for filename, `%l` for first line, and `%L` for last line.
-`--only-parse`
-: Only proceed to parse step of loaders
+ For instance, the [standard library] use the following value to link to files in GitHub:
-`--only-metamodel`
-: Stop after meta-model processing
+ "https://github.com/privat/nit/blob/$(git rev-parse HEAD)/%f#L%l-%L"
-`--ignore-visibility`
-: Do not check, and produce errors, on visibility issues.
+ Here, the `git rev-parse HEAD` is used to link to the current snapshot revision of the file.
-`-d`, `--dir`
-: output directory
+`--no-dot`
+: do not generate graphs with graphviz.
-`--source`
-: link for source (%f for filename, %l for first line, %L for last line)
+`--private`
+: also generate private API.
+
+## CUSTOMIZATION
`--sharedir`
-: directory containing nitdoc assets
+: directory containing nitdoc assets.
-`--shareurl`
-: use shareurl instead of copy shared files
+ By default `$NIT_DIR/share/nitdoc/` is used.
-`--no-dot`
-: do not generate graphes with graphviz
+`--shareurl`
+: use shareurl instead of copy shared files.
-`--private`
-: also generate private API
+ By default, assets from the sharedir a copied into the output directory and refered with a relative path in the generated files.
+ Whith this option, the assets are not copied and the given URL of path is used in the generated files to locate assets.
`--custom-title`
-: custom title for homepage
+: custom title for homepage.
`--custom-footer-text`
-: custom footer text
+: custom footer text.
`--custom-overview-text`
: custom intro text for homepage
`--custom-brand`
: custom link to external site
+## SERVICES
+
`--github-upstream`
: Git branch where edited commits will be pulled into (ex: user:repo:branch)
: Git working directory used to resolve path name (ex: /home/me/myproject/)
`--piwik-tracker`
-: Piwik tracker URL (ex: nitlanguage.org/piwik/)
+: Piwik tracker URL (ex: `"nitlanguage.org/piwik/"`)
`--piwik-site-id`
: Piwik site ID
nitlanguage / nit.git / blobdiff