ellit-org (v0.9)

This file is automatically generated from ellit-org.el by GitHub#ellit-org.el tool. Do not edit manually.

Ultimate tool to document your Emacs Lisp project without much effort.

Generate documentation for your Emacs Lisp package by combining .org files and useful bits from comments in .el files.

Idea is similar to https://github.com/tumashu/el2org

However ellit-org implements more features, such as:

• Easy to use comments extractor from .el, see Commenting files
• Combining multiple files, .org or .el
• GitHub friendly :CUSTOM_ID property generation for headings, so exporting html to GitHub Pages from resulting .org is easy as calling org-html-export-to-html function
• Templating

Why?

Separate files for code and documentation is hard to get in sync. Once changing something in source code files, you might change comments as well and forget about documentation. In other words having documentation in source code is easier to maintain for the developers.

Also many things, useful for documentation, might be automatically extracted from source code. Such as:

• Keybindings
• Customizable options
• Docstrings for commands
• etc

Using ellit-org in your project

Sample Makefile to generate user manual for the project:

EMACS=emacs -Q

manual.org: srcfile.el <list-of-other-files-used-to-generate-manual>
     $(EMACS) -batch -f package-initialize -l ellit-org \
		 --eval '(ellit-org-export "srcfile.el" "manual.org")'

Projects that uses ellit-org

• ellit-org itself, see Makefile
• telega.el uses ellit-org to generate its Manual, see its Makefile
• grammarbot.el, see its Makefile

Commenting .el files

1. Use ;;; ellit-org: [LABEL] as trigger for ellit-org to start processing following comments
2. Processing stops on any non-commentary line
3. When processing stops, newline is emmited to output

Here is the example:

;;; ellit-org:
;; * Heading1                        <--- processing starts here
;; This line is included into output
;;
;; This line also included into output
				     <--- processing stops here
;; This line is NOT included into output
;; * This line also NOT included

;;; ellit-org:
;; - However this line, is included  <--- processing starts here
;;
;;    Since new processing is started, and it will stop only on
;;    non-commentary line below
				     <--- processing stops here
;; This line is *not* included

Combining multiple files

Multiple .org and .el files might be combined forming final result as single .org file.

TODO: Describe labels purpose inside ellit-driven files

TODO: Describe #+ELLIT-INCLUDE: directive, and its properties:

• :eval-p to get include filename by evaluating sexp
• :no-load do not load corresponding .el file
• :label To include only given label from .el or .org file
• :heading To include only given heading

Templates

ellit-org relies on Org mode’s macro system by adding some useful macroses. See https://orgmode.org/manual/Macro-replacement.html

Macro replacement is done after processing comments, so make sure your macroses are in processed part of the comments.

Templates syntax:

{{{macro_name(arguments)}}}

ARGUMENTS are optional string supplied to function which does processing for MACRO_NAME.

Supported templates:

eval(SEXP [, AS-STRING ])

Insert results of the SEXP evaluation. If AS-STRING is non-nil then use “%s” instead of “%S” for formatting SEXP.

as-is(STRING)

Insert STRING as is.

as-is(STRING) filter is equivalent to eval("STRING", t)

ellit-filename([ VERBATIM ])

Insert currently processing filename. If VERBATIM is specified, then outline filename with verbatim markup.

kbd(KEY)

Insert HTML <kbd> tag with KEY contents.

where-is(COMMAND [, KEYMAP [, MENU-ITEMS ]])

Insert list of keys that calls COMMAND. KEYMAP is keymap where to lookup for COMMAND. By default global-map is considered.

If MENU-ITEMS-P is specified, then also insert commands inside menu-items.

vardoc1(VARIABLE)

Insert first line from docstring for the VARIABLE.

vardoc(VARIABLE [, INDENT-LEVEL ])

Insert full docstring for the VARIABLE.

fundoc1(FUNCTION)

Insert first line from docstring for the FUNCTION.

fundoc(FUNCTION [, INDENT-LEVEL ])

Insert full docstring for the FUNCTION.