search

bendudson / array-operations

Common Lisp library that facilitates working with Common Lisp arrays.
Other
43 stars 5 forks source link

Possible doc update #32

Closed Symbolics closed 2 years ago

Symbolics commented 3 years ago

I'm making a lot of use of array-operations, and polished the documentation a bit. If this is useful, I can submit a pull request whenever I improve it.

bendudson commented 3 years ago

Hi @Symbolics thanks that looks nice! Documentation is always very welcome

Symbolics commented 3 years ago

Let me think about the best way to do this with minimal friction. With Papp's other libraries, I made the README describe logistics (see numerical-utilities for an example) and linked to the website documentation. I supposed I could manually copy the website markdown into the README, but I would rather have a 'single source' if I can convince the doc generator and github repo to place nicely together. Alternatively, we could do the same and link to the website for docs, in which case it will always be up to date.

Symbolics commented 3 years ago

I haven't found a good way to keep the doc generator and repo in sync that doesn't require manual effort, so it's probably best to have a single source for the user manual; I'm currently maintaining that on the Lisp-Stat website.

Do you know if there is a way to exclude a single file from a git pull? The only thing that we might not want in this repo is the README that refers to Lisp-Stat. If exclusion or manual-merge exclusion is too difficult, perhaps we can adjust the wording to suit both repos.

Also, some refactoring for consideration:

  1. Put the API docs in a docs/ directory. As soon as version 4 of declt (should be soon) is released, I'm going to auto-generate docs for all the libraries I'm maintaining, then link to them from the repo main page (settings) for API level documentation.
  2. Put a link to the lisp-stat aops manual in this repos README. I keep this user manual up to date, and have recently added documentation for several functions I discovered during my development with aops, and clarified descriptions of others (see documentation change log for details). This way users will always know where to go for the latest user manual.
  3. Merge the matrix package of numerical-utilities into aops. I think they belong here more than they do in numerical-utilities. I've taken over maintenance of several of Tamas's libraries, including numerical-utilities and replacing Tamas' Quicklisp libraries with the ones from Lisp-Stat, so it will be easy to do this (well, at least from a coordination standpoint).

Finally, I recently added a map-array that maps a function over each element of an array (each does not do this and should probably be renamed). Hard to believe there wasn't one in all the functionality of aops, but there you go; I hope I didn't just miss it, but if I did it underscores the need for improved documentation. I'd like to get map-array into the main aops distribution, as I use it in Lisp-Stat and Quicklisp is complaining about its absence.

Perhaps we could start by doing a merge request from the Lisp-Stat repo and discuss the issues as they come up?

bendudson commented 2 years ago

Hopefully this issue is now resolved, thanks @Symbolics!