Doc command and directive

[rejeep]

Add doc command and directive that generates documentation.

spec

• Use files directive
• Command usage: cask doc or cask docs
• Build documentation to doc or docs folder

  questions

• Should it be possible to change doc directory?
• What kind of documentation should be supported?

[rejeep]

@lunaryorn I know that you are writing the docs for flycheck in tex, so you might have some good insights here. How do you think this should work?

[swsnr]

@rejeep I am not sure whether there is a generic approach.

In Flycheck, I have a single documentation file in doc/flycheck.texi, which is build with makeinfo, e.g. makeinfo doc/flycheck.texi -o doc/flycheck.info, but I do not know whether this would be considered “good” practice by other Emacs developers. Flycheck is a rare exception, only very few packages bother to have comprehensive manuals.

As such, I am probably the wrong person to ask. I think my approach is reasonable, and in the absence of any better idea, we can ultimately resort to taking this approach, e.g.

• Let the user specify a main Texinfo file via files,
• then build it with makeinfo, with the target being the file name minus .texi extension plus .info extension,
• and afterwards call install-info with the new info file, to create the dir file in the same directory.

However, I'd like to invite @purcell to this discussion. MELPA has been building Texinfo documentation for packages for quite some time now, so if there are any experts on this matter, it's the MELPA maintainers.

He can probably provide figures about how many packages on MELPA actually have Texinfo manuals, and how these packages are structured.

I'd like to hear his opinion first, before starting to implement this feature.

[rejeep]

That makes sense. @purcell, maybe you could add a public function for this in package-build? @lunaryorn see https://github.com/milkypostman/melpa/issues/1274

[purcell]

Yes, that would be a good plan.

[swsnr]

I agree. Re-using MELPA's code is a great idea. We can share ideas and improvements, and provide a consistent experience to our users.

[conao3]

I think it's hard to maintain documents on the main Elisp Commentary and the Cask file. I'm closing this for the purpose of making the issue board healthier.

[conao3]

Whop, I misunderstand this issue.