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:
Manual usage
Put the following dependency into your project's dependences section:
harbored-mod ![CI status](https://travis-ci.org/dlang-community/harbored-mod.svg?branch=master)
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 thebin
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 withdub
projects) and that thehmod
binary is inPATH
, 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 justhmod
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.
- 0.3.0 released 5 years ago
- basile.b/harbored-mod
- BSL-1.0
- Copyright © Brian Schott, Ferdinand Majerech
- Authors:
- Dependencies:
- dmarkdown, libdparse, libddoc
- Versions:
-
0.3.6 2022-Jul-06 0.3.5 2020-May-05 0.3.4 2020-Apr-24 0.3.3 2020-Apr-23 0.3.2 2020-Apr-20 - Download Stats:
-
-
0 downloads today
-
0 downloads this week
-
0 downloads this month
-
73 downloads total
-
- Score:
- 0.0
- Short URL:
- harbored-mod.dub.pm