Overhaul introductory documentation #1811
Conversation
| * [Python `sh` Fun](https://twitter.com/paultag/status/314925996442796032) | ||
| * [Hy IRC Bot](https://github.com/hylang/hygdrop) | ||
| * [miniKanren in Hy](https://github.com/algernon/adderall) | ||
| To install the latest stable release of Hy, just use the command `pip3 install |
There was a problem hiding this comment.
Side note: do we really want to be recommending pip3 without --user these days? It has a tendency to break...a lot. (Unless you're in a venv I guess, but if you are using venvs for apps, you might as well use pipx, right?)
There was a problem hiding this comment.
Oh dang, does it? I haven't noticed.
There was a problem hiding this comment.
Is pip3 --user more reliable, or is it just easier to clean up a mess in your home directory?
There was a problem hiding this comment.
More reliable; since sudo pip3 installs to the same directory as distro package managers, it has a tendency to either overwrite the distro packages with wrong versions (broke apt for me back when I was on Ubuntu, not very fun to fix), or cause issues when you then try to install the distro version of a package that pip3 already installed. At this point Debian defaults to --user (though that patch also has its own issues).
There was a problem hiding this comment.
Okay, good to know. I'll add in the --users and merge.
docs/whyhy.rst
Outdated
|
|
||
| Overall, Hy, like Common Lisp, is intended to be an unopinionated big-tent | ||
| language that lets you do what you want. If you're interested in a more | ||
| small-and-beautiful approach to Lisp, in the style of Scheme or Clojure, check |
There was a problem hiding this comment.
Also minor side note: not that familiar with Clojure, but does it actually count for this? (I mean, it has a for loop macro, syntax for creating Java objects and implementing interfaces via reify...)
There was a problem hiding this comment.
That's a good question. I think the answer is that that was the goal, but any language that sees real use (e.g., not R5RS Scheme, but Racket) inevitably accumulates lots of features over its lifetime. Python itself is probably the best example.
There was a problem hiding this comment.
True, I mean I understand the Scheme comparison, I just feel like Clojure's is a bit more of a stretch.
There was a problem hiding this comment.
Fair enough. I'll change it.
- Removed links to non-updated code and badges. - Compressed `quickstart.rst` into a few sentences at the very start of the docs. - Added a "Why Hy?" chapter discussing Hy's features and comparing Hy to Python and other Lisps. - Rewrote the tutorial to be more accessible to non-Python programmers and to be greater in breadth but lesser in depth. - Cut down on the self-congratulatory manic tone and exclamation points, while keeping the jokes I liked best.
Kodiologist
force-pushed
the
intro-docs-improvements
branch
from
860f6f6
to
6c93fc6
Compare
This is long overdue, and the rest of the documentation remains in less-than-great shape, and we still don't test the documentation code or automatically mirror docstrings, but it's progress.
See the commit message of the big commit for more.