ryuslash/edocs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Update docstrings

Browse source
This commit is contained in:
Tom Willemse 2013-12-29 01:15:25 +01:00
parent 9a62394a42
commit ed6341fff0
1 changed files with 49 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

54
edocs.el
View file

@ -27,6 +27,15 @@
;; : emacs -batch -l edocs.el -f edocs-generate-batch file.el
;; Each paragraph of text is exported using `org-mode', currently
;; requiring at least org version 8.
;; There is `edocs-generate' which can be used to generate a buffer of
;; the HTML output of the module it's run in interactively, but it is
;; not meant as the main entry-point for edocs. The function
;; `edocs-generate-batch' is the main entry-point of edocs, it is
;; supposed to be run as a batch procedure as shown above.
;;; Code:
(require 'help-fns)
@ -38,13 +47,29 @@
(require 'cl-macs))
(defvar edocs-stylesheet-location "style.css"
"Where to find the Cascading Style Sheet for the exported docs.")
"The location of the CSS used by the exported HTML.
By default it uses `style.css'. This can be changed to any value
which can be used as the `href' attribute of a `style' tag as it
is placed verbatim in one.")
(defvar edocs-generate-only-body nil
"Whether to genereate only the body and no header/footer info.")
"Whether to generate only the body and no header/footer info.
In case the output of edocs is to be embedded into some other
HTML or similar file this option can be changed so that no HTML
header of footer tags are output. Any non-nil value will
suppress these tags. The default is nil.")
(defvar edocs-private-regexp "--"
"Regular expression to identify private parts of a module's API.")
"Regular expression to identify private parts of a module's API.
Some modules (such as this one) differentiate between public and
private parts of the API. This regular expression is used to
identify symbols that are supposed to be private to the module,
and are not meant to be used outside the module. The default is
`--', which matches any symbol with two hyphens such as
`edocs--symbol-type-map'.")
(defconst edocs--symbol-type-map
#s(hash-table size 8 test equal
@ -232,7 +257,13 @@ parts of the module."
(edocs--normalize docs))))
(defun edocs-generate ()
"Generate nice-looking documentation for a module or file."
"Generate nice-looking documentation for a module or file.
Markup is handled by `org-mode' exporting functions. This
command is used both as an interactive command to test the output
of this module and called by the `edocs-generate-batch' function
to generate the actual output. This command outputs its result
into a buffer called `*edocs*' and switches to that buffer."
(interactive)
(let* ((buffer (get-buffer-create "*edocs*"))
(binfo (package-buffer-info))
@ -261,7 +292,20 @@ parts of the module."
(write-file (concat (file-name-sans-extension file) ".html"))))
(defun edocs-generate-batch ()
"Generate module docs using batch operations."
"Generate module docs as a batch operation.
This function maps over `command-line-args-left' and tries to
export the documentation for each file to a file with the same
name, except for the extension replaced with `.html'. This
function uses the `edocs-generate' command to actually generate
the HTML.
Options which affect the export of module documentation (such as
`edocs-stylesheet-location') can be changed using the `-eval'
command line argument to Emacs. For example:
: emacs -batch -l edocs.el -eval \"(setq edocs-generate-only-body t)\" \\
: -f edocs-generate-batch file.el"
(mapc #'edocs--generate-batch-1 command-line-args-left))
(provide 'edocs)