Munge internal docstrings into texinfo

Jelle Licht 6457a25aab notabug org-mode rendering issues? 6 years ago
COPYING 6c1c72ddbd Add license information 6 years ago
README.org 6457a25aab notabug org-mode rendering issues? 6 years ago
guix.scm e3eba78761 Add packaging information. 6 years ago
texi-docstring-magic-geiser.el ee90a32f1d Add some documentation. 6 years ago
texi-docstring-magic.el 6c1c72ddbd Add license information 6 years ago

README.org

texi-docstring-magic allows you to keep your docstrings in one place, and have your texinfo documentation be kept in sync semi-automatically.

It properly supports Emacs lisp, and half baked support for Guile is in the works.

How to use?

Install via guix, or simply place in your load-path and simply add


  (use-package texi-docstring-magic
    :defer t
    :load-path "/path/to/texi-docstring-magic")

  (use-package texi-docstring-magic-geiser
    :defer t
    :load-path "/path/to/texi-docstring-magic")

... to your Emacs init file.

After loading all relevant Guile-symbols and namespaces, make sure to register the active Geiser buffer using geiser/register-buffer while visiting the Geiser buffer. In your texi-file-visiting buffer, make sure to have something like:

@c TEXI DOCSTRING MAGIC:GEISER:guile: myfn

Then, simply invoke M-x texi-docstring-magic-geiser and watch the magic unfold.

Roadmap

TODO Add `interactive?' argument

It would be lovely to not overwrite thing inadvertently by asking for confirmation if we are replacing existing content. I think Spacemacs' * -> replace in project is a good example of this behavior.

TODO Allow custom magic markers

Instead of using a defconst, it might make sense to move to defcustom.

TODO Support namespaces/modules

Add modules/namespaces/prefixes to the magic docstring to distinguish between symbols from different namespaces.

TODO Automatic Geiser discovery

Geiser already has built-in support for finding active REPL's. We should adapt/re-use this logic to deprecate geiser/register-buffer.

TODO Support all geiser implementations

Currently only 'guile is supported as a Geiser backend. Depending on how docstrings might be represented in the other backends, some low-hanging fruit might be to also support other Geiser backends.