How do I document my style files?

Question

I have many style files (and one or two class files) that I've written in my local texmf tree. Most were simple things that got me out of some trouble and which I put in to a style file in case I needed them again. One or two are quite complicated (probably unnecessarily).

My thinking is that I should add some documentation to these files. Mainly for myself: although my reasoning for defining stuff the way I did was perfectly clear when I did it, it may not be so clear next year when I try to use it again (or, worse, try to modify it again). Also for others since I do sometimes share these files, either with collaborators or with anyone who says, "Hey, that's neat! How did you do that?". But definitely not for uploading to CTAN.

So I'd like to add some basic documentation to these files. As it is just for myself, I don't feel that I want to do too much, so what I'd like is a system that is as close to the following parameters as possible:

1. It should be "in file": I want to be able to add the documentation for a command right where the command is defined.
2. The format should be readable when not compiled: this is a corollary of the above, since if I want to be able to read it there and then, I don't want to have to compile it first.
3. But it should be compilable so that I can send it to someone else if I want to and they don't have to wade through the style/class file to find the documentation.
4. However, the compiled form doesn't have to be all that pretty.

Is there such a system? Searching for 'documentation' on CTAN is like searching for snow in Norway - there's plenty of it but, to an outsider, it's hard to figure out what is the right type of snow. If there isn't a system that does what I describe, I'd be happy to hear of others' experiences in trying to do this (I'd be happy to hear them anyway, in fact).

Answer 1

The standard is the DTX format where you put the documentation as comments around your code. Normally in the comment all code is wrapped in macrocode environments and macros again in macro environment. It is then compiled using the ltxdoc class which uses the doc package.

See more information about DTX at the TeX FAQ: https://texfaq.org/FAQ-dtx

Example:

% \begin{macro}{\mymacro}
% Some explanation
%   \begin{macrocode}
\def\mymacro#1#2{%
  \relax
  \dosomething
%   \end{macrocode}
% Explain the next part of the macro
%   \begin{macrocode}
  \domore
  \expandafter\some\code
}
%   \end{macrocode}
% \end{macro

Note that you can autogenerate a DTX file from any package or other code file using the sty2dtx script.