Skip to content

A documentation generator for D with support for both DDoc and Markdown.

License

Notifications You must be signed in to change notification settings

dlang-community/harbored-mod

Repository files navigation

harbored-mod CI status

Introduction

Documentation generator for D with Markdown support, based on harbored.

Harbored-mod supports both DDoc and Markdown in documentation comments, but DDoc takes precedence. This means that there are slight differences from standard Markdown.

Getting started

Building

  • using git

    • git clone https://github.com/dlang-community/harbored-mod.git
    • cd harbored-mod
    • dub build
  • using DUB only

    • dub fetch harbored-mod
    • dub build harbored-mod

Setting up

At this point you should have a binary called hmod in the bin directory.

  • Modify your PATH to point to the bin directory or copy the binary into your project.

  • From your project's directory, run hmod. This assumes your source code is in the ./source subdirectory (as is often the case with dub projects) and that the hmod binary is in PATH, prepend with ./ if it's in the project directory).:

    hmod source
    

    This will write generate documentation to the ./doc subdirectory. See ./doc/index.html. Note that the main page will be blank, although you should see a list of all modules on the left.

    To further tweak the documentation, generate the default configuration file:

Features

  • Supports DDoc and (most, see differences) Markdown syntax
  • Sensible defaults (get decent documentation without tweaking any settings)
  • Automatic cross-referencing in code blocks and inline code
  • Very fast
  • All command-line options can be set in a config file (hmod.cfg) so just hmod is enough to generate documentation
  • Generates one file per module/class/struct/enum/etc. by default, as opposed to one file per module (old Phobos documentation) or one file per symbol (ddox).
  • File paths can be made compatible with ddox using the non-default --format=html-simple option
  • Generated HTML enriched by classes to be more tweakable with CSS
  • Customizable main page, table of contents and style (CSS)
  • Can exclude modules/packages from documentation by their name (not file name)
  • Generated docs are usable without JavaScript (e.g. NoScript), JS may used for optional functionality
  • Only generates HTML, and is unlikely to support any other formats

Differences from vanilla Markdown

  • --- will not generate a horizontal line, as it is used for DDoc blocks. Use - - - instead. This is still standard Markdown.

  • emphasis can be denoted by *, but not by _ (this would break snake_case names).

  • This does not work (again because DDoc uses --- to mark code blocks):

    Subheading

Instead, use either (standard Markdown):

## Subheading

Or (non-standard):

Subheading
**********

Directory structure

Directory Contents
./ This README, Makefile, license.
./bin Harbored-mod binaries when compiled.
./src Source code.
./strings Files compiled into Harbored-mod to be used in generated documentation (e.g. the default CSS style).

Credits

Harbored-mod is based on harbored by Brian Schott, with modifications by Ferdinand Majerech aka Kiith-Sa, maintained by the dlang-community.