-
Notifications
You must be signed in to change notification settings - Fork 616
Documentation overhaul #4300
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
Documentation overhaul #4300
Conversation
Nice! Love the new explanations 👍 |
we can probably vendor the redirect extension honestly, it's pretty small (and MIT licensed): https://github.com/documatt/sphinx-reredirects/blob/main/sphinx_reredirects/__init__.py |
quick thoughts, apologies for limited time for engagement lately
|
That makes sense, I'll split this up. (have I said before how glad I am that you think thoughtfully about these things? 😄) over-documenting internalswe can debate this in a future pull xD, but I'm reminded of Guido's commentary about this:
which I'm highly sympathetic to. I want to make Hypothesis feel as little like magic as possible, and that means not hiding implementation details (to a certain extent). I don't want to document the shrinker or promise anything about its behavior, but we should explain it, and similarly for generation. executable tutorial examplesthere's space for some great stuff here but there's just no way I have time to work on this right now lol, or probably in their near future either |
|
I'm planning to keep this branch up to date as we merge each piece, so I don't lose any work. I'll continue to split off this PR into smaller ones, so I don't expect this PR to be merged until the very end, if at all. |
It seems the docs on thread safety have disappeared. Any chance the old text could come back so that this isn't a broken link, or so I can fix this link? https://hypothesis.readthedocs.io/en/latest/details.html#thread-safety-policy |
Looks like it got temporarily lost during the transition, thanks. I'll fix this later today! |
sorry for sharing the wrong link earlier 🙃 |
@ngoldbaum this section is now at https://hypothesis.readthedocs.io/en/latest/supported.html#thread-safety-policy, and we've left a redirect from https://hypothesis.readthedocs.io/en/latest/details.html#thread-safety-policy as well! |
consider rebasing? It seems like much of the diff for this PR has already landed. |
I don't think so - most of the diff is articles we decided to defer. I think we should close this PR though, to avoid notification overhead. I'm still keeping the branch up to date as I go, but only to track my own work. I'm very excited about the new docs that have landed as a result of (splitting off) this pull! |
What's in this PR
Adding notes
andStateful tests
pages, which have copied content from old docsFor reviewers
https://hypothesis--4300.org.readthedocs.build/en/4300/ or
make documentation && open hypothesis-python/docs/_build/html/index.html
All critiques welcome, up to and including "we should change the entire structure". I think there's a perception that people are more sensitive to writing criticisms than code criticisms, but my sole goal is to have great docs, and my writing style coming through is habit / ease, not intention. So comment away! Similarly I don't view comments for single word changes etc as "too small", everything adds up and even small stuff can be important in docs (especially on the index page). I'm expecting a lot of back and forth in this pull before we merge it.