https://github.com/zevlg/ellit-org.el
Emacs Lisp Literate programming tool
https://github.com/zevlg/ellit-org.el
gnu-emacs
Last synced: 3 months ago
JSON representation
Emacs Lisp Literate programming tool
- Host: GitHub
- URL: https://github.com/zevlg/ellit-org.el
- Owner: zevlg
- License: gpl-3.0
- Created: 2020-01-22T07:30:41.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2022-01-19T22:16:35.000Z (over 4 years ago)
- Last Synced: 2025-03-12T21:49:12.725Z (over 1 year ago)
- Topics: gnu-emacs
- Language: Emacs Lisp
- Size: 243 KB
- Stars: 19
- Watchers: 2
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.org
- License: LICENSE
Awesome Lists containing this project
README
#+OPTIONS: timestamp:nil \n:t
#+TITLE: [[ellit-org-logo64.png]] ellit-org (v0.9)
#+AUTHOR: Zajcev Evgeny
#+startup: showall
[[https://github.com/zevlg/ellit-org.el/actions][https://github.com/zevlg/ellit-org.el/workflows/CI/badge.svg]]
#+begin_quote
This file is automatically generated from =ellit-org.el= by
[[https://github.com/zevlg/ellit-org.el][GitHub#ellit-org.el]] tool.
Do not edit manually.
#+end_quote
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-el-files][Commenting files]]
- [[#combining-multiple-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
- [[#templates][Templating]]
* Why?
:PROPERTIES:
:CUSTOM_ID: why
:END:
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
:PROPERTIES:
:CUSTOM_ID: using-ellit-org-in-your-project
:END:
Sample Makefile to generate user manual for the project:
#+begin_src Makefile
EMACS=emacs -Q
manual.org: srcfile.el
$(EMACS) -batch -f package-initialize -l ellit-org \
--eval '(ellit-org-export "srcfile.el" "manual.org")'
#+end_src
** Projects that uses ellit-org
:PROPERTIES:
:CUSTOM_ID: projects-that-uses-ellit-org
:END:
- =ellit-org= itself, see [[https://github.com/zevlg/ellit-org.el/blob/master/Makefile][Makefile]]
- [[https://github.com/zevlg/telega.el][telega.el]] uses =ellit-org= to generate its [[https://zevlg.github.io/telega.el/][Manual]], see its [[https://github.com/zevlg/telega.el/blob/master/docs/Makefile][Makefile]]
- [[https://github.com/zevlg/grammarbot.el][grammarbot.el]], see its [[https://github.com/zevlg/grammarbot.el/blob/master/Makefile][Makefile]]
* Commenting .el files
:PROPERTIES:
:CUSTOM_ID: commenting-el-files
:END:
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:
#+begin_src emacs-lisp
;;; 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
#+end_src
* Combining multiple files
:PROPERTIES:
:CUSTOM_ID: combining-multiple-files
:END:
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
:PROPERTIES:
:CUSTOM_ID: templates
:END:
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:
#+begin_example
{{{macro_name(arguments)}}}
#+end_example
~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 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~.