Merge Diataxis into main!
#10034
Merged
Merge Diataxis into main!
#10034
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…taxis iteration 0) (#9758) Place the 4 diátaxis categories at the top of the navigation sidebar
…g into diataxis/main
* Refactor offline formats docs Refs #9746 Closes #9577 * Apply suggestions from code review Co-authored-by: Benjamin Balder Bach <[email protected]> * Update docs/user/downloadable-documentation.rst Co-authored-by: Benjamin Balder Bach <[email protected]> * Lots of updates from feedback * Fix CI * Move to Explanation * Update docs/user/downloadable-documentation.rst Co-authored-by: Benjamin Balder Bach <[email protected]> * Fix lint Co-authored-by: Benjamin Balder Bach <[email protected]>
Replace 2 occurrences of "downloadable"
…xis) (#9784) Move "Choosing between our two platforms" to Explanation
…#9676) * Diatáxis refactor: Move Custom Domains to the How-to section * Proposal: Split up Custom Domains into two articles, no new contents added (step 1 of 2) * Try to make "Custom Domain" feature description more self-contained * Update cross-references to match new location * Update docs/user/guides/custom-domains.rst Co-authored-by: Anthony <[email protected]> * Update docs/user/custom-domains.rst Co-authored-by: Anthony <[email protected]> * Update seealso:: box with a better pattern * Remove redundant section label * Add custom-domains to explanation section, add a "What to consider" section * Replace "central" with "reliable" * Remove the example, there's already enough explanation * Add mention of canonical domains * Highlight **canonical** at first apperance, then emphasize its importance * Try to simplify explanation and adds CNAME to the equation. * Fix language * Remove "by default" * Apply suggestions from code review @ericholscher Co-authored-by: Eric Holscher <[email protected]> * Use Dashboard term * Fix up the canonical domain explanation * Change to use :guilabel: in explanation of where to add Custom Domains * Try to build an SVG diagram with sphinxcontrib-mermaid and mmdc * Start a real diagram, only build with mmdc if in a Read the Docs build * Disable SVG generation with mermaid-js * Swap direction of diagram, add some more icons * Also illustrate the build process * Sketching: Move contents of Canonical URLs to Custom Domains explanation, it reads well... * Tweak text, sembr * Canonical URLs again in separate article. More cross-references in Custom Domains. conf.py Comment that :doc: isn't supported yet * Make sure to mention cache invalidation for Read the Docs for Business * Replace "See more" with a better caption * Refer using seealso:: * Text tweaks to Canonical URLs explanation * Move How-to content to a separate how-to * Updates to the original Canonical URLs how-to sections and further references * Revert back to previous phrase, it reads better * Update docs/user/canonical-urls.rst Co-authored-by: Anthony <[email protected]> * Apply suggestions from code review from @agjohnson and @benjaoming Co-authored-by: Anthony <[email protected]> * Update docs/user/custom-domains.rst Co-authored-by: Anthony <[email protected]> * Apply suggestions from @ericholscher code review Co-authored-by: Eric Holscher <[email protected]> * Downgrade cross-reference from a seealso to normal text re:@ericholsher * Add a cautious message to anyone that would want to define html_baseurl. * parenthesis clarified * Add a shortcut convention for referencing issues * Add example code for MkDocs which unfortunately requires a bit of elaboration * Updates diagram and intro text to be easier to digest * Add a bold text that a project needs to be rebuilt. Move the note about ANAME/CNAME. * Turn support seealso into a note * Apply suggestions from @ericholscher code review Co-authored-by: Eric Holscher <[email protected]> * Convert Mermaid diagram to SVG, remove sphinxcontrib-mermaid * Add a closing backtick, remove image alignment (causes wrong vertical margins) * Update docs/user/guides/canonical-urls.rst * Manually create a PNG version (not as straight-forward as assumed) Co-authored-by: Anthony <[email protected]> Co-authored-by: Eric Holscher <[email protected]>
… (Diátaxis) (#9679) * Split up Pull Request Builds since it's pretty much 50:50 in reference and how-to (Diátaxis) * Reformat seealso:: box to @agjohnson's proposal * Move Pull Request Builds to Explanation menu
* Relabel as Explanation, add initial paragraph, move weird note::, remove note:: about Sphinx-only * Adds some more explanation and change odd section "Single project in another language" (what is Single project?) * Change headlines * Add a section "Translation Workflows" * Make the Sphinx guide much more prominent as a seealso at the top of the subsection * Update docs/user/localization.rst Co-authored-by: Eric Holscher <[email protected]> * Update docs/user/localization.rst Co-authored-by: Eric Holscher <[email protected]> Co-authored-by: Eric Holscher <[email protected]>
…átaxis) (#9675) * Re-label VCS integration as a how-to guide and let's call it "Git platform integration"? * Revert back to saying VCS (to cut short discussion) * Revert another change, just to reduce distractions * WIP: Splitting up and updating VCS integration * Update references to integrations after the split * Remove the generic framing of VCS providers * Add git integrations to the list of explanations * Add a local table of content, move oddly placed instructions, fixup broken headline levels * Remove local TOC, move individual provider guides to tabs * Makes it possible to open up a tab using a sphinx label reference * Move Debugging Webhooks into Troubleshooting * Remove section Resyncing webhooks * Comment about scope * Update docs/user/integrations.rst Co-authored-by: Eric Holscher <[email protected]> * WIP * Adds a draft of explanation of how continuous documentation fits into the landscape * Apply suggestions from code review @ericholscher Co-authored-by: Eric Holscher <[email protected]> * Update docs/user/integrations.rst * Add explanation about versioning and a seealso for Automation Rules * Tweak the Automated Versioning subsection and add a seealso for the flyout menu * Refinements to versioning subsection * Update docs/user/integrations.rst Co-authored-by: Eric Holscher <[email protected]> * Remove paragraph that already had a broken reference (even before AFAICT) and that does not lead to clear solutions * Make Git a proper noun. This way of writing "Git repository" etc. is widely used, example: https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository. Ref #9813 Co-authored-by: Eric Holscher <[email protected]>
* Docs: Split SSO docs into HowTo/Explanation This is an initial attempt. I ended up making a couple decisions: * Breaking each SSO method out into its own page, to make it clearer and rank better on Google * Pulling the content around generic team membership out into its own page, since it wasn't really Google related There's probably some light finishing touches to clean things up, but wanted to get this up today. * Apply suggestions from code review Co-authored-by: Benjamin Balder Bach <[email protected]> * Apply suggestions from code review Co-authored-by: Benjamin Balder Bach <[email protected]> * A bit more feedback about SSO explanation page * Update docs/user/commercial/single-sign-on.rst * Fix BitBucket branding * Standardize on Username format * More fixup * Link to teams * Fix link title * Have proper intro * Fix link * Update docs/user/guides/setup-single-sign-on-github-gitlab-bitbucket.rst Co-authored-by: Manuel Kaufmann <[email protected]> * Apply suggestions from code review Co-authored-by: Manuel Kaufmann <[email protected]> * Lots more updates based on feedback * Apply suggestions from code review from @humitos Co-authored-by: Manuel Kaufmann <[email protected]> * Apply suggestions from code review Co-authored-by: Benjamin Balder Bach <[email protected]> * Small cleanup Co-authored-by: Benjamin Balder Bach <[email protected]> Co-authored-by: Manuel Kaufmann <[email protected]>
Understand the "Science" page as Explanation and add framing to introduction
…re to explanation (Diátaxis) (#9835) * WIP: Updates to "Single version documentation" documentation * Apply suggestions from code review Co-authored-by: Eric Holscher <[email protected]> * Fix whitespace Co-authored-by: Eric Holscher <[email protected]>
* Existing text refactored into howto and explanation * Improve subproject explanation with some cases of when it's useful * Apply suggestions from code review by @humitos Co-authored-by: Manuel Kaufmann <[email protected]> * Really spell out the alias of a subproject vs. its name * Lowercase foo and bar * Describe common searching as a main objective of using subprojects, add a subsection about Separate release cycles * Update docs/user/subprojects.rst Co-authored-by: Eric Holscher <[email protected]> * Apply suggestions from code review @ericholscher Co-authored-by: Eric Holscher <[email protected]> * Update docs/user/guides/subprojects.rst * Updates to Subprojects Explanation and How-to from @ericholscher feedback * Update introduction, improvents pending... * Adds another intro paragraph * Also make *main website* emphasized * Update docs/user/guides/subprojects.rst Co-authored-by: Eric Holscher <[email protected]> * Update docs/user/guides/subprojects.rst Co-authored-by: Eric Holscher <[email protected]> * Apply suggestions from code review @ericholscher Co-authored-by: Eric Holscher <[email protected]> * Add mentions of subprojects in Intersphinx how-to and vice versa * Thanks PyCharm for the lovely emoji support 📝️📝️📝️ * Make it possible to see from the main example that example-project-plugin has a short alias * Rename all occurrences of foo and bar to example-project and example-project-plugin * Add precision to subproject create/edit form * Apply suggestions from code review by @humitos 🎉 👍 Co-authored-by: Manuel Kaufmann <[email protected]> * Update docs/user/subprojects.rst Co-authored-by: Manuel Kaufmann <[email protected]> Co-authored-by: Eric Holscher <[email protected]>
…Diátaxis) (#9677) * Re-label Traffic Analysis as a How-To (Diátaxis) * Improve introduction paragraph * Update title to reflect contents better, add additional entry in developer's and designer's guides * Apply suggestions from code review Co-authored-by: Eric Holscher <[email protected]> * Add Traffic Analytics to the Main Features page * Remove How-to from Features * Add a new Reference / Features section and create a stub for Search Analytics * Update screenshot and add more guidance to using the search analytics feature * Clarify "Daily search totals" * Clarify what "Download all data" does * Update docs/user/reference/analytics.rst Co-authored-by: Eric Holscher <[email protected]> * Rm trailing whitespace * Apply sentence case for titles * Apply suggestions from code review @ericholscher Co-authored-by: Eric Holscher <[email protected]> * Fix white-space lint Co-authored-by: Eric Holscher <[email protected]>
…g into diataxis/main
* WIP: Rephrase Organization as an explanation article, include current how-to guide for teams in this work * Apply suggestions from code review @ericholscher Co-authored-by: Eric Holscher <[email protected]> * Change heading of Organizations article Co-authored-by: Eric Holscher <[email protected]>
#9834) * WIP: Refactor explanation/howto revolving around OAuth * Make it more clear to some users that they don't need to do anything (majority of users?) * Tested GitLab and Bitbucket, we need to add one permission to the list * Adds a seealso:: back from howto to explanation * Apply suggestions from code review @ericholscher Co-authored-by: Eric Holscher <[email protected]> * read the dots - list entries end with a period * Adds more explanation about how OAuth works and organizes permissions into tabs * Add link to OAuth, remove redundant seealso * Update how-to guide and use place-holders for screenshots * Clarify ambiguous sign-up text * Add subsection about disconnecting a service * Add screenshots to howto * pre-commit is lit 🔥 * Move to Explanation TOC section * Apply suggestions from code review @ericholscher Co-authored-by: Eric Holscher <[email protected]> * Apply the new substitution for Git providers Co-authored-by: Eric Holscher <[email protected]>
* Move FAQ to How-to navigation area, pending updates * Remove duplicate /faq in TOC, experiment with :titlesonly: in the how-to TOC * Rework first batch of FAQ entries to be Questions with Answers and cross-references * Restore entry in Troubleshooting * Less frisky question * Re-order FAQ into top-levels * Adds a seealso, change some literals to code-blocks * Clarify a few random items * Re-add :hidden: for TOC - not sure it makes any difference
…g into diataxis/main
…9953) * WIP: Split "Automation rules" into reference and how-to * WIP: More restructuring of reference * WIP: Step-by-step guide with screenshot and *explanation* of choices * Reorder actions into definition list, add a tip box with 2 tips in how-to * A few changes and edits in a second draft * Fix build issues * Fix lint * Conventions are lowercase, removed `<Project Detail>` from menuselection * Re-add default version term refs --------- Co-authored-by: Eric Holscher <[email protected]> Co-authored-by: Eric Holscher <[email protected]>
* Adds a seealso and includes existing rtd4b * Relabel the current article as a how-to * Refactor as feature reference * Apply suggestions from @ericholscher's code review Co-authored-by: Eric Holscher <[email protected]> * Adds @stsewd suggestions - dot some item lists * Rephrase security log of downloading documentation --------- Co-authored-by: Eric Holscher <[email protected]>
…ataxis/main Conflicts: requirements/docs.txt Resolved by re-running pip-compile
…g into diataxis/main
* Transform the guide into an explanation with best practices, use Sphinx and MkDocs examples in tabs * Apply suggestions from @ericholscher's code review Co-authored-by: Eric Holscher <[email protected]> * Re-add motivational text with a reference to the best practices.. but can't be **bold** because reST * Finish the sentence * General intro to unlinked pages * Add TODO items * Apply suggestions from @ericholscher's code review Co-authored-by: Eric Holscher <[email protected]> --------- Co-authored-by: Eric Holscher <[email protected]>
…"privacy level" page (Diátaxis) (#10007) * Move ALL Read the Docs for Business features into Feature Reference * Use :menuselection: * Present Read the Docs for business trimming out marketing and referring to landing pages * Use the soon-to-be-non-ambiguous term "website" + various improvements * Apply suggestions from @ericholscher's code review Co-authored-by: Eric Holscher <[email protected]> * Lint and fix *|com_brand|* * Apply suggestions from code review Co-authored-by: Eric Holscher <[email protected]> --------- Co-authored-by: Eric Holscher <[email protected]>
) * Splits environment variable articles in explanation (custom variables) and reference (pre-defined) * Split out further contents to a how-to, refine all the text, adding more detail on using secret envs * Clarification * Expand section "alternative approaches" and improve intro * Clarification of environment expansion * "Build process" not "build environment" to make it easier * Merge together two paragraphs and clarify that "two layers" as "two sets of environment variables" * Elaborate the scenario for an alternative approach * Real sentence structure for how-to steps * Put the note before the "Save" instruction. Add a bit more message glue between sections * Add a reference and improve env variable reference intro * a-z order env vars * New title for explanation and some more content on sphinx-multiproject * Phrase a bit more general as "patterns" * Re-order env vars, remove Git conflict artifact, add seealsos * Apply suggestions from @ericholscher's code review Co-authored-by: Eric Holscher <[email protected]> * Fix a :ref: * seealso texts updated * Have one `note::` box less --------- Co-authored-by: Eric Holscher <[email protected]>
mini language tweak
…#9952) * Updated reference for hosting features, adding more features and re-organizing content * Apply suggestions from code review @ericholscher Co-authored-by: Eric Holscher <[email protected]> * Update name of Feature reference index to avoid explicit labels elsewhere * Fix misalignments * Redo in-page references * Update "read more" link for "multiple documentation versions" * Add "private documentation" to hosting feature list * Revert to old title, modify introduction with less passive voice * Dot the list sentences, don't say "bust" but "invalidate and refresh" * Refactor of feature section * Initial refactor of features into dedicated pages. Ended up writing a bunch of additional content here, since these features were barely documented... This will be a big win for our users. * More refactoring * Remove redundancy * Remove stray Makefile commit * Make a mention of this "404/index.html" structure in relation to Sphinx DirHTML builder. * Apply suggestions from code review Co-authored-by: Benjamin Balder Bach <[email protected]> * Lint * Fix typo --------- Co-authored-by: Eric Holscher <[email protected]> Co-authored-by: Eric Holscher <[email protected]>
…as Reference (Diátaxis) (#10010) * Collects About Read the Docs and Features and Advanced Features in Reference * Reorder a few things * Add 🔗 for Developer Documentation * Having a go at explaining the website and how we use documentation tools for organization information :) * Apply suggestions from @ericholscher's code review Co-authored-by: Eric Holscher <[email protected]> * Move seealso to after the list * remove non-existing TOC ref --------- Co-authored-by: Eric Holscher <[email protected]>
humitos
approved these changes
Feb 15, 2023
There was a problem hiding this comment.
I'm not sure what I'm supposed to review here ( +3,189 −1,469, 🤯 ), but we have been reviewing these changes in smaller PRs while doing this work. So, I guess everything is on its place.
I'm happy we are merging this into main so people can start reading better docs 😉
* Put the toctrees at the top of index.rst content * Re-order explanation * Move how-to guides before explanation * Emojis in navigation * re-order reference items * Lots of TOC refactoring * A bit more futzing * Remove underscores from files, and do a bit more cleanup * Fix links * Single TOC for all --------- Co-authored-by: Eric Holscher <[email protected]>
|
Fixing conflicts now... This will include removing a dependency on |
benjaoming
approved these changes
Feb 15, 2023
There was a problem hiding this comment.
There shouldn't be anything to review here 👍
Question could be if there is any outstanding PRs we want to wait for. While there are more significant improvements inbound, I don't see any blockers on moving forwards with this.
The best thing about this refactor is that it doesn't break stuff like incoming links and cross-references. If the builds work, merging this is all it takes to go live with all the new changes 💯
|
Btw! WARNING! Please don't squash merge but use a merge commit so we can keep this git history. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Exciting times :)
Fixes: #9746
📚 Documentation previews 📚
docs): https://docs--10034.org.readthedocs.build/en/10034/dev): https://dev--10034.org.readthedocs.build/en/10034/