Emacs package quickstart with Eldev (my notes)

[bard]

I've written a couple of packages in the past (run-command and director) and I'm looking at adopting Eldev to cut down on maintenance work and possibly enforce structure and good practices.

The project's README is very thorough; the flip side is that the basic use flow is not immediately apparent. I tried reconstructing it some weeks ago, didn't get far, and put it on hold. I picked it up again today, and this time I wrote notes, mostly to help myself next time. They're at https://massimilianomirra.com/notes/emacs-package-quickstart-with-eldev. I might expand them as I encounter other typical tasks (e.g. linting, publishing).

A couple of observations:

• Would it make sense to modify the README so that it's a little less reference-like and a little more guide-like, at least in its first part? I'm happy to contribute my notes if they seem like a suitable starting point.

• In the JavaScript world, there are many create-xyz-app CLI tools which take a project name as argument, and create a project directory, structure, example content (e.g. a main application page, components, tests), initialize the git repo, and install dependencies. They're great at getting people started immediately on application code, while still keeping them within the boundaries of best practices. @doublep do you think that an eldev create command that does the above could be useful?

[doublep]

I guess most documentation should be moved out of README.adoc, as it has become too huge. AFAIR there is something for hosting documentation on GitHub, but I have never looked into it (also not into how to create multifile documentation using Asciidoctor). README.doc should be eventually reduced to the first few sections with a quick-start guide, with prominent links to the current "reference" documentation. I feel like the existence of this huge page is rather daunting to newcomers. If you feel like writing a quick-start guide, you are welcome, but please be aware that I'm rather picky in this area and will likely edit your work heavily.

About eldev create, see issue #45 that instead proposes to improve existing eldev init. I never really started anything though, as I rather agree with alphapapa's sentiment there: "An Emacs package can be simply one Elisp file, nothing else".

[bard]

If you feel like writing a quick-start guide, you are welcome, but please be aware that I'm rather picky in this area and will likely edit your work heavily.

If the notes mentioned above look reasonable, I'm happy to convert them to asciidoc and submit them. What you do with them afterwards is entirely up to you, this is still open source. :)

It's possible to set up a static site generator that takes a directory of markdown (probably asciidoc too) and outputs a documentation website to https://doublep.github.io/eldev. But a lot of projects just split their README into various files in a docs/ folder; personally I find that's just as good, and with a fraction of the overhead.

About eldev create, see issue #45 that instead proposes to improve existing eldev init. I never really started anything though, as I rather agree with alphapapa's sentiment there: "An Emacs package can be simply one Elisp file, nothing else".

I don't see that argument as diminishing the usefulness of a create command, though. The total time to create that single Elisp file (which includes ensuring the correct format, either by copy-pasting from a past projects, or reading documentation, or copying it from another package) and setting things up with Eldev is still higher than launching a single command; it was for me despite having authored packages already, I'd imagine that to be even more so for a newbie. On the other hand, getting people started fast and with something that includes some best practices could be a win both for them, since they get to work immediately on their idea and don't lose steam, and perhaps the community, as the average quality of code increases.

[doublep]

It's possible to set up a static site generator that takes a directory of markdown (probably asciidoc too) and outputs a documentation website to https://doublep.github.io/eldev.

Finally did that and trimmed down main README.adoc heavily. Feedback welcome.

If the notes mentioned above look reasonable, I'm happy to convert them to asciidoc and submit them

Maybe you could create a PR against the smaller README.adoc now.

I don't see that argument as diminishing the usefulness of a create command, though.

In general, I agree with you, but it would be likely a waste of time. There are what, fewer than 200 projects using Eldev currently (half of them probably abandoned). And a project would need init only once or a few times at the start — assuming it's not even an older project switching to Eldev and its creator even knew about eldev init.

I mean, at least half of things in Eldev are a waste of time, but those are at least reusable for people who discover them, not use-five-times-in-lifetime features.