Hectarea1996 / adp-github

ADP extension to generate github-markdown files.

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 headers, 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.

• Add Documentation, Please... with Github Flavoured Markdown
  • 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 (Ultralisp):

(ql-dist:install-dist "http://dist.ultralisp.org/" :prompt nil)
(ql:quickload "adp-github")

Documentation

• Reference
• User Guide

How to use

In your asd file, you need to :defsystem-depends-on the system adp-github. Also, is really recommended to make a separate system only for documentation generation. And, lastly, you should specify :build-operation to be "adp-github-op".

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

(defsystem "my-system/docs"
  :defsystem-depends-on ("adp-github")
  :build-operation "adp-github-op"
  :depends-on ("my-system")
  :components ((:scribble "README")))

Now, from the REPL, just evaluate the following expression:

(asdf:make "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:select-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.