harbor

docs made simple

Harbor

1. (noun) A place of shelter
2. (noun) An area for ships to dock
3. (noun) An elegant documentation generator

What

Harbor aims to be a minimalist generator of fine Markdown documentation.

Why

There are plenty of powerful documentation generators out there, but I wanted something nice and simple for small projects, that reads straight from the source code, makes as few assumptions as possible, and outputs plain Markdown files.

It's designed to be simple enough to be used manually to generate a doc skeleton for manual tweaking, but also modular enough to be used in an automated build pipeline.

Philosophy

• Have no opinions: Don't enforce any particular style. Just allow the definition of arbitrary macros for text modification. With the correct .harbor file, this could conceivably generate HTML.

• Favor flexibility over power: The small convenience gained by auto-detecting which class or function definitions a given docs section is near is far outweighed by the loss of potential layout options or non-standard formatting choices

• Favor clarity over speed: The purpose here is mainly to provide ease of use. Simple rules, easily remembered, beat clever tricks that squeeze a few microseconds out of compile time. At least in this use case. Harbor is for when you value your own time above the computer's.

How

Generating documentation with Harbor requires a single file, plus tagged comments in your existing source code. The file is a .harbor file, which specifies both the structure of the output file and any text macros to be applied to the output. An example:

OUTLINE 
readme: README.md 
  badges 
  what 
  why 
  how 
    intro 
    outline 
    patterns 
 
  todo 
 
PATTERNS 
title: 
    # {title} 
section: 
    ### {section} 

The outline section of the .harbor file must be preceded by OUTLINE. This section specifies the names of the files to be generated, and their internal structure

Each line in the OUTLINE section without indentation denotes a file. The form is aaa: bbb, where aaa is the nickname for the file, and bbb is the actual filename to use when saving the generated documentation.

Basic outline indentation rules apply, with regard to how nesting works. The sections can have arbitrary names, excluding spaces. Best practice for multi-word sections is Lisp-style naming: another-section or this-is-a-wordy-label.

Once the outline is specified, comments can be written into the source code. An example comment:

''' 
harbor: readme
 
 
Markdown 
*Markdown* 
[link](google.com) 
''' 

TODO

• Allow multiple inputs to text replacement macros
• Clean output to be even more human- readable/editable
• Handle multi-line inputs to macros
• REFACTOR
• Implement a 'trace' function to print an outline of the docs' origins (file name and line number)
• Experiment with supporting project languages other than Python
  
  

This documentation generated by harbor