Docs: Configuration file pages as explanation and reference (Diátaxis) #9921
Conversation
…ataxis/split-configuration-file-v2
I got motivated to write this, but struggled to figure out what to say in a clear way.. Leaving this in a draft for another day.
|
!! Pay attention to some .py files being changed in this PR (probably the target branch is outdated) |
…rg into diataxis/explanation-refactor
…re precise concept
…hould probably remove old content
…tentially a diagram)
…ataxis/explanation-refactor
…/readthedocs.org into diataxis/explanation-refactor
…ataxis/explanation-refactor
…g sections. Some work still left.
…ataxis/explanation-refactor
…/readthedocs.org into diataxis/explanation-refactor
…iguration-file-v2
…tom sub-folder support
|
This PR is ready for review with a bigger disclaimer, namely that it's currently easier to review here: https://github.com/benjaoming/readthedocs.org/pull/6/files |
…ataxis/explanation-refactor
…/readthedocs.org into diataxis/split-configuration-file-v2
I'm confused... what are the PR's on your fork for? This isn't a workflow we generally use. This PR has a bunch of additional changes in it from other PR's as well? |
I stopped using this workflow some months ago. But these changes are older. I wanted to have this PR point to a different base branch, but since the base branch is in my fork, it got necessary. Pretty good argument to avoid forked repos in a workflow.. chained PRs aren't possible.
Yes, this PR has been around way too long :/ It now contains all of #10071 - I fail to recall the reasoning. I could move all changes over in #10071, but this PR is already too long for a nice a simple review process. |
|
I'd recommend breaking the PRs up into discrete changes. I can't really track what is happening between them. Does it make sense to try to review and merge #10071 first, and then look at this as a diff on top of that? |
Yes, I think so. #10071 is a bit hefty, but we'll have to wrestle it sooner or later... better to wrestle it sooner because it has this PR stacked on top. Once #10071 is in, I can merge/rebase this PR branch so it gets simpler to review. |
|
I definitely did something in this PR that requires #10071 because I explicitly merged it in at some point. I'll mark it as blocked for now 👍 |
|
I should also mention that there is another similar change chained on #10071 : https://github.com/benjaoming/readthedocs.org/pull/3/files |
|
Cut out and proposed here: #10416 |
#10416) * Scissor out and refine changes from #9921 * Polish intro sentences * Add how-to reference * Do some content updates. * Emoji ⚖️ * fix mini err * typo fix * typo fixes * Adds a seealso to v2 reference -- many people are visiting the reference directly (because we didn't have any other resources), should add the how-to --------- Co-authored-by: Eric Holscher <[email protected]>
Not ready for review
Depends on: #10071
This flags changes that are incoming
Refs: #9746
Fixes: #8648
📚 Documentation previews 📚
docs): https://docs--9921.org.readthedocs.build/en/9921/dev): https://dev--9921.org.readthedocs.build/en/9921/