Add Documentation, Please... with Github Flavoured Markdown

Welcome to ADP-GITHUB!

ADP-GITHUB is an exporter for ADP. It defines some functions and macros to print markdown-styled objects like titles, lists, code blocks and more. It also supports cross references and table of contents. Every symbol is exported from the adp-github package, although you can use the nickname adpgh.

• Installation
• Documentation
• How to use
• Where the files are generated

Installation

• Manual:

cd ~/common-lisp
git clone https://github.com/Hectarea1996/adp-github.git

• Quicklisp:

(ql:quickload "adp-github")

Documentation

• Reference
• User Guide

How to use

Make a subsystem of your project. For example, name it my-project/docs. You need to :defsystem-depends-on the system adp-github. And, lastly, you should specify the system :class to be :adp-github.

(defsystem "my-project"
  ;; ...
  )

(defsystem "my-project/docs"
  :defsystem-depends-on ("adp-github")
  :class :adp-github
  :depends-on ("my-system")
  :components ((:scribble "README")))

After writing some fancy scribble code into the file README.scrbl, just evaluate the following expression:

(asdf:load-system "my-system/docs")

Where the files are generated

There is a simple rule and one expception. The rule says that every file is generated in a mirrored place under the docs directory. For example, the contents of file scribble/myfile.scrbl are printed into the file docs/scribble/myfile.md.

The exception is the use of adpgh:output-file. As the name suggest, you can select the output file. It accpets a pathname. That pathname is always treated as a relative path to the system's root directory.