Skip to content

Commit 176eb7b

Browse files
benjaomingericholscher
benjaoming
and
ericholscher
authored
Docs: New how-to sublevels (Diátaxis) (#10131)
* WIP: New how-to sublevel structure * WIP: New sub-levels introduced, need to order items under each level and create better index pages * WIP * Completed writing actual content for all sub-levels on how-to guides * Fill in best practice, represent a couple of guides in different sub-levels and add a few missing introduction paragraphs to some guides * tweaking the language * Title of this page indicates a broad guide, but it's a troubleshooting list of errors * Update docs/user/guides/access/index.rst * Apply suggestions from @ericholscher's code review Co-authored-by: Eric Holscher <[email protected]> * Use consistent "tense" for verb fix the last couple of relative paths * Consolidate style guide with How-to convention * Refactor user/automatic-redirects.rst -> user/guides/best-practice/links.rst * Apply suggestions from code review Co-authored-by: Eric Holscher <[email protected]> * Update lead paragraph for automatic/manual repo how-tos --------- Co-authored-by: Eric Holscher <[email protected]>
1 parent bc4bced commit 176eb7b

28 files changed

+344
-152
lines changed

‎docs/dev/style-guide.rst

+16-5
Original file line numberDiff line numberDiff line change
@@ -187,9 +187,11 @@ This means that *both content and navigation path* for all sections should fit a
187187
Explanation
188188
~~~~~~~~~~~
189189

190-
* Introduce the scope: **“This article introduces ...”**
191-
(write this as the very first thing,
192-
then consider rewriting it or turning it into an internal comment afterwards).
190+
* Title convention: Use words indicating explanation in the title.
191+
Like **Understanding <subject>**, **Dive into <subject>**, **Introduction to <subject>** etc.
192+
* Introduce the scope in the first paragraph: **“This article introduces ...”**.
193+
Write this as the very first thing,
194+
then re-read it and potentially shorten it later in your writing process.
193195
* Cross-reference the related How-to Guide.
194196
Put a ``seealso::`` somewhere visible.
195197
It should likely be placed right after the introduction,
@@ -200,9 +202,17 @@ Explanation
200202
How-to guides
201203
~~~~~~~~~~~~~
202204

203-
* Title should begin with **“How to ...”**,
204-
but navigation titles should not contain the “How to” part.
205+
* Title should begin with **“How to ...”**.
206+
If the how-to guide is specific for a tool, make sure to note it in the title.
207+
* Navigation titles should not contain the “How to” part.
208+
Navigation title for "How to create a thing" is **Creating a thing**.
205209
* Introduce the scope: **“In this guide, we will…”**
210+
211+
* Introduction paragraph suggestions:
212+
213+
* "This guide shows <something>. <motivation>"
214+
* "<motivation>. This guide shows you how."
215+
206216
* Cross-reference related explanation.
207217
Put a ``seealso::`` somewhere visible,
208218
It should likely be placed right after the introduction
@@ -231,6 +241,7 @@ Tutorial
231241

232242
.. note:: We don’t really have tutorials targeted in the systematic refactor, so this checklist isn’t very important right now.
233243

244+
* "Getting started with <subject>" is likely a good start!
234245
* Cross-reference related explanation and how-to.
235246
* Try not to explain things too much, and instead link to the explanation content.
236247
* **Refactor other resources** so you can use references instead of disturbing the flow of the tutorial.

‎docs/user/connected-accounts.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
How to connect your Git repository
22
==================================
33

4-
In this article, we explain how connecting your Read the Docs account to one of the supported Git providers
4+
In this article, we explain how connecting your Read the Docs account to |git_providers_or|
55
automatically configures your Git repository and your Read the Docs project.
66

77
✅️ Signed up with your Git provider?

‎docs/user/guides/access/index.rst

+39
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
How-to guides: security and access
2+
==================================
3+
4+
⏩️ :doc:`Single Sign-On (SSO) with GitHub, GitLab, or Bitbucket </guides/setup-single-sign-on-github-gitlab-bitbucket>`
5+
When using an :doc:`organization </commercial/organizations>` on |com_brand|,
6+
you can configure SSO for your users to authenticate to Read the Docs.
7+
8+
⏩️ :doc:`Single Sign-On (SSO) with Google Workspace </guides/setup-single-sign-on-google-email>`
9+
When using an :doc:`organization </commercial/organizations>` on |com_brand|,
10+
you can configure SSO for your users to authenticate to Read the Docs.
11+
This guide is written for Google Workspace.
12+
13+
⏩️ :doc:`Managing Read the Docs teams </guides/manage-read-the-docs-teams>`
14+
When using an :doc:`organization </commercial/organizations>` on |com_brand|,
15+
it's possible to create different teams with custom access levels.
16+
17+
⏩️ :doc:`Manually importing private repositories </guides/importing-private-repositories>`
18+
You can grant access to private Git repositories using |com_brand| using a custom process if required.
19+
Here is how you set it up.
20+
21+
⏩️ :doc:`Using private Git submodules </guides/private-submodules>`
22+
If you are using private Git repositories and they also contain private Git submodules,
23+
you need to follow a few special steps.
24+
25+
⏩️ :doc:`Installing private python packages </guides/private-python-packages>`
26+
If you have private dependencies, you can install them from
27+
a :ref:`private Git repository <guides/private-python-packages:From a Git repository>` or
28+
a :ref:`private repository manager <guides/private-python-packages:From a repository manager other than PyPI>`.
29+
30+
.. toctree::
31+
:maxdepth: 1
32+
:hidden:
33+
34+
Single Sign-On (SSO) with GitHub, GitLab, or Bitbucket </guides/setup-single-sign-on-github-gitlab-bitbucket>
35+
Single Sign-On (SSO) with Google Workspace </guides/setup-single-sign-on-google-email>
36+
Managing Read the Docs teams </guides/manage-read-the-docs-teams>
37+
Manually importing private repositories </guides/importing-private-repositories>
38+
Using private Git submodules </guides/private-submodules>
39+
Installing private python packages </guides/private-python-packages>

‎docs/user/guides/administrators.rst

-35
This file was deleted.

‎docs/user/guides/authors.rst

-24
This file was deleted.

‎docs/user/guides/best-practice/index.rst

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
How-to guides: best practices
2+
=============================
3+
4+
Over the years,
5+
we have become familiar with a number of methods that work well and which we consider **best practice**.
6+
7+
⏩️ :doc:`Best practices for linking to your documentation </guides/best-practice/links>`
8+
Documentation changes over time,
9+
and links and cross-references can become challenging manage for various reasons.
10+
Here is a set of best practices explaining and addressing these challenges.
11+
12+
⏩️ :doc:`Deprecating content </guides/deprecating-content>`
13+
Best practice for removing or deprecating documentation content.
14+
15+
⏩️ :doc:`Creating reproducible builds </guides/reproducible-builds>`
16+
Every documentation project has dependencies that are required to build it.
17+
Using an unspecified versions of these dependencies means that your project can start breaking.
18+
In this guide,
19+
learn how to protect your project against breaking randomly.
20+
**This is one of our most popular guides!**
21+
22+
⏩️ :doc:`Search Engine Optimization (SEO) for documentation projects </guides/technical-docs-seo-guide>`
23+
This article explains how documentation can be optimized to appear in search results,
24+
increasing traffic to your docs.
25+
26+
⏩️ :doc:`Hiding a version </guides/hiding-a-version>`
27+
Learn how you can keep your entire version history online without overwhelming the reader with version choices.
28+
29+
.. toctree::
30+
:maxdepth: 1
31+
:hidden:
32+
33+
Deprecating content </guides/deprecating-content>
34+
Best practices for linking to your documentation </guides/best-practice/links>
35+
Creating reproducible builds </guides/reproducible-builds>
36+
Search Engine Optimization (SEO) for documentation projects </guides/technical-docs-seo-guide>
37+
Hiding a version </guides/hiding-a-version>

‎docs/user/automatic-redirects.rst renamed to ‎docs/user/guides/best-practice/links.rst

File renamed without changes.

‎docs/user/guides/build-troubleshooting.rst

+3-2
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
1-
How to troubleshoote build errors
2-
=================================
1+
Troubleshooting build errors
2+
============================
33

44
.. include:: /shared/contribute-to-troubleshooting.rst
55

6+
This guide provides some common errors and resolutions encountered in the :doc:`build process </builds>`.
67

78
Git errors
89
----------

‎docs/user/guides/build-using-too-many-resources.rst

+4
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,13 @@
11
Troubleshooting slow builds
22
===========================
33

4+
This page contains a list of the most common issues that are slowing down builds.
5+
46
In case you are waiting a long time for your builds to finish
57
or your builds are terminated by exceeding general resource limits,
68
this troubleshooting guide will help you resolve some of the most common issues causing slow builds.
9+
Even if you are not facing any immediate performance issues,
10+
it's always good to be familiar with the most common ones.
711

812
Build resources on Read the Docs are limited to make sure that users don't overwhelm our build systems.
913
The current build limits can be found on our :ref:`Build resources reference <builds:Build resources>`.

‎docs/user/guides/build/index.rst

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
How-to guides: build process
2+
============================
3+
4+
⏩️ :doc:`Setup build notifications and webhooks </guides/build-notifications>`
5+
Build notifications can alert you when your builds fail so you can take immediate action.
6+
In this guide,
7+
you will learn how to get notified through various available channel integrations,
8+
including email and chat.
9+
10+
⏩️ :doc:`Configuring pull request builds </guides/pull-requests>`
11+
Have your documentation built and access a preview for every :doc:`pull request builds </pull-requests>`.
12+
13+
⏩️ :doc:`Using custom environment variables </guides/environment-variables>`
14+
Extra environment variables, for instance secrets, may be needed in the build process and can be defined from the project's :term:`dashboard`.
15+
16+
⏩️ :doc:`Managing versions automatically </guides/automation-rules>`
17+
Automating your versioning on Read the Docs means you only have to handle your versioning logic in Git.
18+
Learn how to define rules to automate creation of new versions on Read the Docs,
19+
entirely using your Git repository's version logic.
20+
21+
22+
.. seealso:
23+
24+
:doc:`/builds`
25+
An overview and introduction to the build process.
26+
27+
.. toctree::
28+
:maxdepth: 1
29+
:hidden:
30+
31+
Setup build notifications and webhooks </guides/build-notifications>
32+
Configuring pull request builds </guides/pull-requests>
33+
Using custom environment variables </guides/environment-variables>
34+
Managing versions automatically </guides/automation-rules>

‎docs/user/guides/content/index.rst

+82
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
How-to guides: content, themes and SEO
2+
======================================
3+
4+
⏩️ :doc:`Search Engine Optimization (SEO) for documentation projects </guides/technical-docs-seo-guide>`
5+
This article explains how documentation can be optimized to appear in search results,
6+
ultimately increasing traffic to your docs.
7+
8+
⏩️ :doc:`Enabling canonical URLs </guides/canonical-urls>`
9+
In this guide, we introduce relevant settings for enabling canonical URLs in popular documentation frameworks.
10+
11+
⏩️ :doc:`Using traffic analytics </analytics>`
12+
In this guide, you can learn to use Read the Docs' built-in traffic analytics for your documentation project.
13+
You will also learn how to optionally add your own Google Analytics account or completely disable Google Analytics on your project.
14+
15+
⏩️ :doc:`Managing translations for Sphinx projects </guides/manage-translations-sphinx>`
16+
This guide walks through the process needed to manage translations of your documentation.
17+
Once this work is done, you can setup your project under Read the Docs to build each language of your documentation by reading :doc:`/localization`.
18+
19+
⏩️ :doc:`Supporting Unicode in Sphinx PDFs </guides/pdf-non-ascii-languages>`
20+
Sphinx offers different LaTeX engines that have better support for Unicode characters, relevant for instance for Japanese or Chinese.
21+
22+
⏩️ :doc:`Cross-referencing with Sphinx </guides/cross-referencing-with-sphinx>`
23+
When writing documentation you often need to link to other pages of your documentation,
24+
other sections of the current page, or sections from other pages.
25+
26+
⏩️ :doc:`Linking to other projects with Intersphinx </guides/intersphinx>`
27+
This section shows you how to maintain references to named sections of other external Sphinx projects.
28+
29+
⏩️ :doc:`Using Jupyter notebooks in Sphinx </guides/jupyter>`
30+
There are a few extensions that allow integrating Jupyter and Sphinx,
31+
and this document will explain how to achieve some of the most commonly requested features.
32+
33+
⏩️ :doc:`Migrating from rST to MyST </guides/migrate-rest-myst>`
34+
In this guide, you will find
35+
how you can start writing Markdown in your existing reStructuredText project,
36+
or migrate it completely.
37+
38+
⏩️ :doc:`Enabling offline formats </guides/enable-offline-formats>`
39+
This guide provides step-by-step instructions to enabling offline formats of your documentation.
40+
41+
⏩️ :doc:`Using search analytics </guides/search-analytics>`
42+
In this guide, you can learn to use Read the Docs' built-in search analytics for your documentation project.
43+
44+
⏩️ :doc:`Adding custom CSS or JavaScript to Sphinx documentation </guides/adding-custom-css>`
45+
Adding additional CSS or JavaScript files to your Sphinx documentation
46+
can let you customize the look and feel of your docs
47+
or add additional functionality.
48+
49+
⏩️ :doc:`Embedding content from your documentation </guides/embedding-content>`
50+
Did you know that Read the Docs has a public API that you can use to embed documentation content?
51+
There are a number of use cases for embedding content,
52+
so we've built our integration in a way that enables users to build on top of it.
53+
54+
⏩️ :doc:`Removing "Edit on ..." buttons from documentation </guides/remove-edit-buttons>`
55+
When building your documentation,
56+
Read the Docs automatically adds buttons at the top of your documentation and in the versions menu that point readers to your repository to make changes.
57+
Here's how to remove it.
58+
59+
⏩️ :doc:`Adding "Edit Source" links on your Sphinx theme </guides/edit-source-links-sphinx>`
60+
Using your own theme?
61+
Read the Docs injects some extra variables in the Sphinx ``html_context``,
62+
some of which you can use to add an "edit source" link at the top of all pages.
63+
64+
.. toctree::
65+
:maxdepth: 1
66+
:hidden:
67+
68+
Search Engine Optimization (SEO) for documentation projects </guides/technical-docs-seo-guide>
69+
Using traffic analytics </analytics>
70+
Using search analytics </guides/search-analytics>
71+
Enabling canonical URLs </guides/canonical-urls>
72+
Enabling offline formats </guides/enable-offline-formats>
73+
Embedding content from your documentation </guides/embedding-content>
74+
Managing translations for Sphinx projects </guides/manage-translations-sphinx>
75+
Supporting Unicode in Sphinx PDFs </guides/pdf-non-ascii-languages>
76+
Cross-referencing with Sphinx </guides/cross-referencing-with-sphinx>
77+
Linking to other projects with Intersphinx </guides/intersphinx>
78+
Using Jupyter notebooks in Sphinx </guides/jupyter>
79+
Migrating from rST to MyST </guides/migrate-rest-myst>
80+
Adding custom CSS or JavaScript to Sphinx documentation </guides/adding-custom-css>
81+
Removing "Edit on ..." buttons from documentation </guides/remove-edit-buttons>
82+
Adding "Edit Source" links on your Sphinx theme </guides/edit-source-links-sphinx>

‎docs/user/guides/deprecating-content.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ progressively and in non harmful ways.
1313

1414
.. seealso::
1515

16-
:doc:`/automatic-redirects`
16+
:doc:`/guides/best-practice/links`
1717
More information about handling URL structures, renaming and removing content.
1818

1919
Deprecating versions

‎docs/user/guides/developers.rst

-18
This file was deleted.

‎docs/user/guides/embedding-content.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ Read the Docs allows you to embed content from any of the projects we host and s
55
(currently, ``docs.python.org``, ``docs.scipy.org``, ``docs.sympy.org``, ``numpy.org``)
66
This allows reuse of content across sites, making sure the content is always up to date.
77

8-
There are a number of uses cases for embedding content,
8+
There are a number of use cases for embedding content,
99
so we've built our integration in a way that enables users to build on top of it.
1010
This guide will show you some of our favorite integrations:
1111

‎docs/user/guides/git-integrations.rst

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
11
How to manually connect your Git repository
22
===========================================
33

4-
In this guide, you will find the simple steps to integrating your Read the Docs project with GitHub, Bitbucket, GitLab, Gitea or any other Git provider that supports our generic API.
4+
In this guide,
5+
you will find the simple steps to manually integrating your Read the Docs project with all Git providers that supports our generic API.
6+
This includes most Git providers, for example |git_providers_and|.
57

68
.. note::
79

‎docs/user/guides/importing-private-repositories.rst

+3
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,9 @@ How to import private repositories
88
we recommend :doc:`connecting your account </connected-accounts>` and importing your project from
99
https://readthedocs.com/dashboard/import instead of importing it manually.
1010

11+
You can grant access to private Git repositories using |com_brand|.
12+
Here is how you set it up.
13+
1114
If you are using an unsupported integration, or don't want to connect your account,
1215
you'll need to do some **extra steps in order to have your project working**.
1316

0 commit comments

Comments
 (0)