Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update docs for 0.14.3 #66

Closed
Technologicat opened this issue Aug 7, 2020 · 7 comments
Closed

Update docs for 0.14.3 #66

Technologicat opened this issue Aug 7, 2020 · 7 comments
Labels
documentation Non-executable English, for humans
Milestone

Comments

@Technologicat
Copy link
Owner

Technologicat commented Aug 7, 2020

This issue will gather information about any documentation updates needed for the next minor release, 0.14.3.

Moved from 0.14.2 (see #8):

  • Check the tone of our criticisms of Python, that we don't come down too harshly on it - for the most part, the language is excellent. (If it wasn't, it wouldn't have made sense to build this whole thing - maybe we should mention that.) Especially the focus on readability. The vertical-space-saving indentation-sensitive surface syntax is nice minor detail, too. As is the general with protocol. Moved to 0.14.4.
  • Ping aisha-w about proofreading any new docs, if they're still interested. Moved to 0.14.4.
@Technologicat Technologicat added the documentation Non-executable English, for humans label Aug 7, 2020
@Technologicat Technologicat added this to the 0.14.3 milestone Aug 7, 2020
@Technologicat
Copy link
Owner Author

Technologicat commented Aug 10, 2020

The new test[] macro needs to be documented properly.

EDIT: "documented properly" means it should be listed and explained in doc/macros.md. The material to make those docs pretty much already exists in the docstrings and in the unit tests.

@Technologicat
Copy link
Owner Author

Technologicat commented Aug 11, 2020

doc/readings.md: gather links to a few writings in John Shutt's blog, which is very relevant to language design. We already link some posts in other documentation, but at the very least, those links should be copied to readings to make them easier to find. Done.

Also, link HACKING.md (contribution guidelines) from README.md. Forgot to do this earlier. Done.

Consider switching away from Title Case in Documentation Headings, in favor of Just capitalize the first word, to increase readability. It's a feature of capital letters to catch the eye and stop scanning; let's use that effectively. Moved to 0.14.4.

@Technologicat
Copy link
Owner Author

Technologicat commented Aug 12, 2020

unpythonic.test.fixtures needs to be documented properly. The start, testset, and summary functions, to be used together with the test[] macro, are the beginnings of a testing framework for macro-enabled Python code.

See unpythonic.syntax.test.test_testutil for a commented-out demo.

@Technologicat
Copy link
Owner Author

Technologicat commented Aug 12, 2020

New functions:

  • Document unpythonic.misc.tryf, a way to handle exceptions in an expression position.
  • Document unpythonic.misc.equip_with_traceback.
  • Document unpythonic.misc.safeissubclass.

@Technologicat
Copy link
Owner Author

Meh, a bunch of stuff has already changed since I wrote that. The changelog is up to date.

@Technologicat
Copy link
Owner Author

  • Update the explicit tags that say "this document is up to date for...".

@Technologicat
Copy link
Owner Author

Done in 9b7ff51.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Non-executable English, for humans
Projects
None yet
Development

No branches or pull requests

1 participant