harbored-mod 0.3.0

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


To use this package, run the following command in your project's root directory:

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

DirectoryContents
./This README, Makefile, license.
./binHarbored-mod binaries when compiled.
./srcSource code.
./stringsFiles 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.

Authors:
  • Brian Schott
  • Ferdinand Majerech
Dependencies:
dmarkdown, libdparse, libddoc
Versions:
0.3.0 2019-Feb-10
0.2.1 2017-May-16
~master 2019-Feb-10
Show all 3 versions
Download Stats:
  • 0 downloads today

  • 1 downloads this week

  • 3 downloads this month

  • 11 downloads total

Score:
0.0
Short URL:
harbored-mod.dub.pm