texi-docstring-magic

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.