Create quickref.rst

[tjdwill]

A page of useful examples and links to examples for ease of writing Hy programs.

I'm not sure how to do an integration test/build as I've never used Sphinx or reStructuredText before. When trying to do so, I get an error because I think my Sphinx version is too recent.

[Kodiologist]

Like I said, this covers a lot of the same material as the tutorial. The parts not already covered by the tutorial seem to be covered pretty well by the API reference, and indeed some of the entries are just links to the API reference and nothing else. An overly redundant manual is ultimately harder to navigate and maintain. So, instead of adding a new page to the manual, try finding the points in the tutorial or the API reference that you think are missing something and adding material there.

I'm not sure how to do an integration test/build

See CONTRIBUTING.rst.

[tjdwill]

I understand your view on it.

To me, while the tutorial provides a great introduction to the language, the examples aren't comprehensive enough in terms of translating between more complex Python syntax and Hy in order to do something useful. Adding more complex examples to the tutorial, however, would clutter it in my opinion and possibly overwhelm new users with too much information. It's fine as-is for the purpose it serves.

The API reference does have more involved examples, but it isn't as approachable, and you need to know the macro you're looking for to begin with (hence the direct links in the quick ref to the relevant sections of the API reference). Personally, I don't mind reading the API reference and continue to do so, but I know most people who would have an interest in this would want something that gets them up-to-speed more quickly. The new page is meant to bridge the gap between the two pages. It also provides a space to cover edge-cases in the future such as Numpy's multi-dimensional slicing (something that is not obvious to do and required online searching to figure out).

However, I acknowledge that I don't know the goals of this project in terms of adoption nor who the target audience is.

I get what you're saying and understand if you don't approve the merge. However, from the perspective of a new user who doesn't have the familiarity with the language that Hy developers or even experienced Lispers have, something of this sort would have been very helpful in the beginning. If not a new page, then a downloadable PDF or something.

See CONTRIBUTING.rst.

Yeah, I realized that I missed the Sphinx setup on my first pass. Thank you for that.

[Kodiologist]

Adding more complex examples to the tutorial, however, would clutter it in my opinion and possibly overwhelm new users with too much information.

Agreed.

I don't know the goals of this project in terms of adoption nor who the target audience is.

I have no goals for adoption. If people use Hy, cool. If they don't, so be it. The target audience is some combination of Python programmers who want more features and less limitations, non-Python programmers who want to use Python libraries, and programmers in general.

Anyway, I see your point about the value of a page that "bridges the gap". Truth is, though, I don't want to maintain documentation that overlaps with but isn't quite identical to preexisting material. The manual is already big (a fact that I better appreciate now I've nearly completed an editing pass of the whole thing). Additions should be parsimonious. I'd prefer that supplementary learning resources be outside the manual and Hylang.org, where I'm not responsible for their maintenance. We have a GitHub wiki, if you want to use that. Or you could keep in it a separate repository, which could be linked to from Hy's tutorial or README or something.

[Kodiologist]

It also provides a space to cover edge-cases in the future such as Numpy's multi-dimensional slicing

This wiki page I made recently should be a good place for that.

[tjdwill]

I have no goals for adoption. If people use Hy, cool. If they don't, so be it. The target audience is some combination of Python programmers who want more features and less limitations, non-Python programmers who want to use Python libraries, and programmers in general.

Understood.

I'd prefer that supplementary learning resources be outside the manual and Hylang.org, where I'm not responsible for their maintenance.

Fair enough. I've never maintained a project before, so I don't have a solid grasp of how much work goes into it, and I definitely don't know how much extra work new additions produce.

I'll look into the wiki solution. Should I close this pull request?

[Kodiologist]

I can do it.