~ushin/ushin#125: Ideas for improving documentation generation

Some ideas we discussed today, recording here for future reference:

Consider using Org macros to reduce boilerplate, e.g. for the case of

#+vindex: hyperdrive-persist-location
- ~hyperdrive-persist-location~ :: Location where ~persist~ will store
  data, currently ~hyperdrive-hyperdrives~ and ~hyperdrive-version-ranges~.
  By default, uses the default ~persist~ location.

Consider automating the generation of function/command/variable documentation directly from their docstrings. Some of these functions in unpackaged.el might be helpful.

Status: RESOLVED IMPLEMENTED
Submitter: ~alphapapa
Assigned to: ~alphapapa
Submitted: 1 year, 7 months ago
Updated: 1 year, 4 months ago
Labels: 0.3.0 hyperdrive.el

~alphapapa added hyperdrive.el 1 year, 7 months ago

~ushin added 0.3.0 1 year, 6 months ago

~ushin 1 year, 6 months ago*

I'll need to also merge the info manual descriptions into the docstrings.

~alphapapa assigned ~alphapapa 1 year, 5 months ago

~tarsius 1 year, 5 months ago

Consider automating the generation of function/command/variable documentation directly from their docstrings.

That might not be possible because the convention is to use the imperative mood in docstrings, while info manuals it is not. We seem to be following the respective conventions in both places already.

The extensions to ox-texinfo.el, which produce the above texi output, have been merged into org, and are documented in its manual. If you want to look at more examples, I suggest the transient manual.

However we don't use commands such as @defopt and @deffn, and we use free form lists to list key bindings.

Here is a short excerpt from magit's info manual, that shows what a key binding and an option is supposed to look like, when (more or less) following the conventions:
‘U’ (‘magit-unstage-all’)
     Remove all changes from the staging area.

 -- User Option: magit-unstage-committed
     This option controls whether ‘magit-unstage’ "unstages" committed
     changes by reversing them in the index but not the working tree.
     The alternative is to raise an error.
Writing even such simple definitions in texinfo is IMO unbearable:
@table @asis

[...]

@item @kbd{U} (@code{magit-unstage-all})
@kindex U
@findex magit-unstage-all
Remove all changes from the staging area.
@end table

@defopt magit-unstage-committed
This option controls whether @code{magit-unstage} "unstages" committed
changes by reversing them in the index but not the working tree.
The alternative is to raise an error.
@end defopt
which is why I use org instead. But writing it using the same constructs that are being used for org's own manual itself, is not much better.

So I have written an extension to ox-texinfo that accept some special formatting that looks very close to the eventual output in the info file, instead of like the intermediate mess in the texi file. The org source for the above info output is just this:
- Key: U (magit-unstage-all) ::

  Remove all changes from the staging area.

- User Option: magit-unstage-committed ::

  This option controls whether ~magit-unstage~ "unstages" committed
  changes by reversing them in the index but not the working tree.
  The alternative is to raise an error.

~ushin 1 year, 4 months ago

This obviates the need to manually insert #vindex: foobar all over the place! Thank you!!

~tarsius 1 year, 4 months ago

By the way, the mentioned "extension to ox-texinfo" has been merged into Org a few releases ago.

~ushin REPORTED IMPLEMENTED 1 year, 4 months ago

Implemented in 056cf071. Thank you!!

~ushin 1 year, 4 months ago

Also 195a1a01 and 28c81e2d