Improve docs #8
Improve docs #8
Conversation
This frees up room in the README for instructions on how to use the project.
Before this change, the readme hadn't talked about the particulars of using this library at all. This adds a brief summary of the available tools. There's still a good amount of room for improvement here, and we could benefit from having distinct "how-to", "explanation", "reference" and "tutorial" docs.
CONTRIBUTING.md
Outdated
| Ensure one of the supported Pythons (see README) is installed and used by the `python` executable: | ||
|
|
||
| ```sh | ||
| python --version |
There was a problem hiding this comment.
python won't exist unless you've set an alias yourself or some tool has put a shim in your PATH. Should we reccommend invoking python directly with python3.12 or python3.10 etc?
There was a problem hiding this comment.
I'd say mention that it's easiest to manage python with asdf or pyvenv than to rely on a single system level python.
There was a problem hiding this comment.
easiest to manage python with asdf or pyvenv
I strongly disagree with this -- I have had all sorts of problem with both of those tools and the magic they do and have helped countless people with similar. I have never had problems with an explicit installation from python.org, as long as I don't expect my shell to read my mind.
Not the point here, though -- I don't want to get into an argument about environment setup. My only point was that python doesn't exist by default, so we might confuse users if we assume their shell setup.
All python expose a specific executable (e.g. python3.12) and it looks like they also have a python3 symlink to the same, so whichever is first in the PATH can use that. If we're going to be non-specific about minor version then I think this should at least use the real name of that symlink (python3). Similarly, we wouldn't put shell commands in docs that assumed specific oh-my-zsh plugins, even if those are what we use locally.
There was a problem hiding this comment.
Thanks for this.
I also don't want to get into details of shell setup, but I'm going to run on the assumption that anyone who's got as far as reading this guide will know the details of which python to use.
I'm cool with changing this to python3, but I don't think I want to go any further than that at this point.
| If you only intend to run the tests with [tox], then you may only require: | ||
|
|
||
| ```sh | ||
| pip install tox |
There was a problem hiding this comment.
If we aren't installing the dependencies, are we still assuming the user has created a virtual env? Personally I would use pipx for this.
There was a problem hiding this comment.
I don't want to recommend any particular tool here, pipx included. I think that this file needs more revision, but that can wait for another PR. This PR should be mostly about the README.
|
|
||
| By making the constraint `IMMEDIATE`, | ||
| the constraint would be checked on `INSERT`, | ||
| and it would be much easier to catch. |
There was a problem hiding this comment.
Definitely starting to look like a poem
There was a problem hiding this comment.
Not sure how to fix.
Might leave this until later.
Or haiku whole doc.
README.md
Outdated
| and it would be much easier to catch. | ||
|
|
||
| More generally, | ||
| if you have custom deferrable constraint, |
There was a problem hiding this comment.
Grammar not quite right here.
This alias is more likely to exist on a wider array of operating systems.
This sentence didn't quite make sense before because I missed word.
This:
CONTRIBUTING.md.README.md. (There is a lot of room for future improvement here. I think adding a proper docs build should come next.)