Skip to content

Docs: Relabel and reorganize hosting features as reference (Diátaxis) #9952

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.

Sign up for GitHub

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

Merged
merged 20 commits into from
Feb 14, 2023
Merged

Docs: Relabel and reorganize hosting features as reference (Diátaxis) #9952

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
b14e129
Updated reference for hosting features, adding more features and re-o…
benjaoming Jan 26, 2023
1e0e846
Merge branch 'diataxis/main' of github.com:readthedocs/readthedocs.or…
benjaoming Feb 1, 2023
3c5a569
Apply suggestions from code review @ericholscher
benjaoming Feb 1, 2023
78ac176
Update name of Feature reference index to avoid explicit labels elsew…
benjaoming Feb 1, 2023
e11f180
Fix misalignments
benjaoming Feb 1, 2023
9c38f27
Redo in-page references
benjaoming Feb 1, 2023
a5323b6
Update "read more" link for "multiple documentation versions"
benjaoming Feb 1, 2023
c3ac6de
Add "private documentation" to hosting feature list
benjaoming Feb 1, 2023
e885bc7
Revert to old title, modify introduction with less passive voice
benjaoming Feb 1, 2023
0a36b8b
Dot the list sentences, don't say "bust" but "invalidate and refresh"
benjaoming Feb 1, 2023
4d8dd32
Refactor of feature section
ericholscher Feb 2, 2023
2022d5b
Initial refactor of features into dedicated pages.
ericholscher Feb 10, 2023
6f71b64
More refactoring
ericholscher Feb 10, 2023
c7e5fb2
Remove redundancy
ericholscher Feb 10, 2023
3294054
Remove stray Makefile commit
ericholscher Feb 10, 2023
118aae6
Merge branch 'diataxis/main' of github.com:readthedocs/readthedocs.or…
benjaoming Feb 10, 2023
2b192a5
Make a mention of this "404/index.html" structure in relation to Sphi…
benjaoming Feb 10, 2023
afa0ec8
Apply suggestions from code review
ericholscher Feb 11, 2023
419dccf
Lint
benjaoming Feb 14, 2023
2435b30
Fix typo
benjaoming Feb 14, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
# (except for '--keep-going', failing fast is prefered on local builds)
# We also remove '-E' to reduce the time of rebuilding reference indexes
# on each build.
SPHINXOPTS = -T -j auto -W
SPHINXOPTS = -T -W
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pretty sure that -j auto is the default in our Sphinx builder?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh yea, I was getting errors on this locally, but I just needed to update my depednencies.

SPHINXBUILD = sphinx-build
PAPER =
PROJECT ?= user
Expand Down
26 changes: 8 additions & 18 deletions docs/user/reference/features.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,61 +7,51 @@ Feature reference
Hosting features
----------------

Custom domain support
⏩️ :doc:`/custom-domains`
Documentation projects can use their own domain name.
A project may define multiple domains,
as well as define the *canonical domain* where all other domains will redirect.

⏩️ :doc:`/custom-domains`

Multiple documentation versions
⏩️ :doc:`/versions`
We support multiple versions and translations,
integrated nicely into the URL of your documentation.
This is served at ``/en/latest/`` by default.
If you only have 1 version and translation,
we also support :doc:`single version projects </single_version>` served at ``/``.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a really nice purposeful use of the introduction, clarifying a basic misconception that somehow multiple versions are required 👍


⏩️ :doc:`/versions`

Custom URL redirects
⏩️ :doc:`/user-defined-redirects`
Projects may define their own custom URL redirects,
with advanced functionality like folder redirects.

⏩️ :doc:`/user-defined-redirects`

Content Delivery Network (CDN)
⬇️ :doc:`/reference/cdn`
Documentation projects are primarily static HTML pages along with media files.
This allows us to cache them with our CDN,
making them *load faster* for your users.

⬇️ :doc:`/reference/cdn`

Sitemaps
⬇️ :doc:`/reference/sitemaps`
Sitemaps are generated and hosted automatically,
improving search engine optimization.
This helps your users find content more effectively on your site.

⬇️ :doc:`/reference/sitemaps`

Custom ``404s Not Found`` pages
⬇️ :doc:`/reference/404-not-found`
A 404 page is served when we can't find a page on your site.
We provide a default 404 page,
but you can also customize it.

⬇️ :doc:`/reference/404-not-found`

Custom robots.txt
⬇️ :doc:`/reference/robots`
`robots.txt` files allow you to customize how your documentation is indexed in search engines.
We provide a default robots.txt file,
but you can also customize it.

⬇️ :doc:`/reference/robots`

Private documentation
⬇️ :doc:`/reference/robots`
It is possible to host private and password protected documentation on Read the Docs for Business.

⏩️ :doc:`/commercial/sharing`

.. The TOC here will be refactored once we reorganize the files in docs/user/.
.. Probably, all feature reference should be in this directory!
.. In upcoming work, redirects will be added for old URL destinations.
Expand Down