From 69a3403433f8b3d5d4d1f34c382cb62b712bae2d Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Tue, 14 Feb 2023 22:02:28 +0100 Subject: [PATCH 01/10] Put the toctrees at the top of index.rst content --- docs/user/index.rst | 114 +++++++++++++++++++++----------------------- 1 file changed, 55 insertions(+), 59 deletions(-) diff --git a/docs/user/index.rst b/docs/user/index.rst index e432c5acc4d..22494ce7630 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -1,63 +1,6 @@ Read the Docs: Documentation Simplified ======================================= -.. meta:: - :description lang=en: Automate building, versioning, and hosting of your technical documentation continuously on Read the Docs. - -.. Adds a hidden link for the purpose of validating Read the Docs' Mastodon profile -.. raw:: html - - Mastodon - -`Read the Docs`_ simplifies software documentation -by building, versioning, and hosting of your docs, automatically. -This enables many "docs like code" workflows, -keeping your code & documentation as close as possible. - -Never out of sync |:arrows_counterclockwise:| - Whenever you push code to your favorite version control system, - whether that is Git or Mercurial, - Read the Docs will automatically build your docs - so your code and documentation are always up-to-date. - Read more about :doc:`/integrations`. - -Multiple versions |:card_index_dividers:| - Read the Docs can host and build multiple versions of your docs - so having a 1.0 version of your docs and a 2.0 version - of your docs is as easy as having a separate branch or tag in your version control system. - Read more about :doc:`/versions`. - -Open Source and User Focused |:heartbeat:| - Our code is free and `open source `_. - :doc:`Our company ` is bootstrapped and 100% user focused. - |org_brand| hosts documentation for over 100,000 large - and small open source projects, - in almost every human and computer language. - |com_brand| supports hundreds of organizations with product and internal documentation. - -.. _Read the docs: https://readthedocs.org/ - -You can find out more about our all the :doc:`/features` in these pages. - -First steps ------------ - -Are you new to software documentation -or are you looking to use your existing docs with Read the Docs? -Learn about documentation authoring tools such as Sphinx and MkDocs -to help you create fantastic documentation for your project. - -* **Tutorial**: :doc:`/tutorial/index` - -* **Getting started**: - :doc:`With Sphinx ` | - :doc:`With MkDocs ` | - :doc:`/choosing-a-site` - -* **Importing your existing documentation**: - :doc:`Import guide ` - - .. toctree:: :maxdepth: 2 :hidden: @@ -68,7 +11,6 @@ to help you create fantastic documentation for your project. /intro/getting-started-with-mkdocs /intro/import-guide - .. toctree:: :maxdepth: 2 :hidden: @@ -102,7 +44,6 @@ to help you create fantastic documentation for your project. /examples /faq - .. toctree:: :maxdepth: 2 :hidden: @@ -119,6 +60,61 @@ to help you create fantastic documentation for your project. /about/index /glossary +.. meta:: + :description lang=en: Automate building, versioning, and hosting of your technical documentation continuously on Read the Docs. + +.. Adds a hidden link for the purpose of validating Read the Docs' Mastodon profile +.. raw:: html + + Mastodon + +`Read the Docs`_ simplifies software documentation +by building, versioning, and hosting of your docs, automatically. +This enables many "docs like code" workflows, +keeping your code & documentation as close as possible. + +Never out of sync |:arrows_counterclockwise:| + Whenever you push code to your favorite version control system, + whether that is Git or Mercurial, + Read the Docs will automatically build your docs + so your code and documentation are always up-to-date. + Read more about :doc:`/integrations`. + +Multiple versions |:card_index_dividers:| + Read the Docs can host and build multiple versions of your docs + so having a 1.0 version of your docs and a 2.0 version + of your docs is as easy as having a separate branch or tag in your version control system. + Read more about :doc:`/versions`. + +Open Source and User Focused |:heartbeat:| + Our code is free and `open source `_. + :doc:`Our company ` is bootstrapped and 100% user focused. + |org_brand| hosts documentation for over 100,000 large + and small open source projects, + in almost every human and computer language. + |com_brand| supports hundreds of organizations with product and internal documentation. + +.. _Read the docs: https://readthedocs.org/ + +You can find out more about our all the :doc:`/features` in these pages. + +First steps +----------- + +Are you new to software documentation +or are you looking to use your existing docs with Read the Docs? +Learn about documentation authoring tools such as Sphinx and MkDocs +to help you create fantastic documentation for your project. + +* **Tutorial**: :doc:`/tutorial/index` + +* **Getting started**: + :doc:`With Sphinx ` | + :doc:`With MkDocs ` | + :doc:`/choosing-a-site` + +* **Importing your existing documentation**: + :doc:`Import guide ` Read the Docs feature overview ------------------------------ From 0b03097546e2f289a62ed27f82fe2ae1f93a5cfb Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Tue, 14 Feb 2023 22:23:09 +0100 Subject: [PATCH 02/10] Re-order explanation --- docs/user/index.rst | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/docs/user/index.rst b/docs/user/index.rst index 22494ce7630..0402324d206 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -14,23 +14,22 @@ Read the Docs: Documentation Simplified .. toctree:: :maxdepth: 2 :hidden: - :glob: :caption: Explanation - /localization /choosing-a-site - /build-notifications /integrations - /custom-domains - /environment-variables /pull-requests + /science + /automatic-redirects + /guides/technical-docs-seo-guide + /localization + /build-notifications + /custom-domains /connected-accounts /downloadable-documentation /subprojects /single_version - /science - /automatic-redirects - /guides/technical-docs-seo-guide + /environment-variables .. toctree:: :maxdepth: 2 @@ -48,7 +47,6 @@ Read the Docs: Documentation Simplified :maxdepth: 2 :hidden: :caption: Reference - :glob: /reference/features /api/index From 3d355250900bd63e350cf70418937905253a0b55 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Tue, 14 Feb 2023 22:23:32 +0100 Subject: [PATCH 03/10] Move how-to guides before explanation --- docs/user/index.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/user/index.rst b/docs/user/index.rst index 0402324d206..c829f4ad5bb 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -11,6 +11,18 @@ Read the Docs: Documentation Simplified /intro/getting-started-with-mkdocs /intro/import-guide +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: How-to Guides + + /guides/authors + /guides/administrators + /guides/developers + Troubleshooting + /examples + /faq + .. toctree:: :maxdepth: 2 :hidden: @@ -31,18 +43,6 @@ Read the Docs: Documentation Simplified /single_version /environment-variables -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: How-to Guides - - /guides/authors - /guides/administrators - /guides/developers - Troubleshooting - /examples - /faq - .. toctree:: :maxdepth: 2 :hidden: From e2fac21041b9a73779476aeced20cefec7f53290 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Tue, 14 Feb 2023 22:28:07 +0100 Subject: [PATCH 04/10] Emojis in navigation --- docs/user/index.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/user/index.rst b/docs/user/index.rst index c829f4ad5bb..12e79a08e5d 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -4,7 +4,7 @@ Read the Docs: Documentation Simplified .. toctree:: :maxdepth: 2 :hidden: - :caption: Tutorials + :caption: Tutorials 🚀 /tutorial/index /intro/getting-started-with-sphinx @@ -14,7 +14,7 @@ Read the Docs: Documentation Simplified .. toctree:: :maxdepth: 2 :hidden: - :caption: How-to Guides + :caption: How-to guides 🪄 /guides/authors /guides/administrators @@ -26,7 +26,7 @@ Read the Docs: Documentation Simplified .. toctree:: :maxdepth: 2 :hidden: - :caption: Explanation + :caption: Explanation 💡 /choosing-a-site /integrations @@ -46,7 +46,7 @@ Read the Docs: Documentation Simplified .. toctree:: :maxdepth: 2 :hidden: - :caption: Reference + :caption: Reference 📚 /reference/features /api/index From d3f67e3a94942a6db42f8adde6096f4109fd189b Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Tue, 14 Feb 2023 22:29:33 +0100 Subject: [PATCH 05/10] re-order reference items --- docs/user/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user/index.rst b/docs/user/index.rst index 12e79a08e5d..718a8893a65 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -49,14 +49,14 @@ Read the Docs: Documentation Simplified :caption: Reference 📚 /reference/features + /about/index /api/index /server-side-search/api /server-side-search/syntax /reference/environment-variables changelog - Developer Documentation 🔗 - /about/index /glossary + Developer Documentation 🔗 .. meta:: :description lang=en: Automate building, versioning, and hosting of your technical documentation continuously on Read the Docs. From 2191ddb3edcd8c4bf3653bd3e14daef948236e08 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Tue, 14 Feb 2023 15:48:41 -0800 Subject: [PATCH 06/10] Lots of TOC refactoring --- docs/conf.py | 1 + docs/user/api/index.rst | 1 + docs/user/build-default-versions.rst | 2 +- docs/user/commercial/sharing.rst | 4 +- docs/user/connected-accounts.rst | 4 +- docs/user/features.rst | 91 ---------------------- docs/user/guides/administrators.rst | 1 + docs/user/guides/authors.rst | 3 + docs/user/guides/troubleshooting/index.rst | 4 +- docs/user/index.rst | 48 +++++------- docs/user/integrations.rst | 2 +- docs/user/pull-requests.rst | 5 +- docs/user/reference/features.rst | 53 +++++++------ docs/user/science.rst | 2 +- docs/user/tutorial/index.rst | 2 +- 15 files changed, 66 insertions(+), 157 deletions(-) delete mode 100644 docs/user/features.rst diff --git a/docs/conf.py b/docs/conf.py index 1c4dcb601d9..ab930118f85 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -61,6 +61,7 @@ release = version exclude_patterns = ["_build", "shared", "_includes"] default_role = "obj" +intersphinx_cache_limit = 14 # cache for 2 weeks intersphinx_timeout = 3 # 3 seconds timeout intersphinx_mapping = { "python": ("https://docs.python.org/3.10/", None), diff --git a/docs/user/api/index.rst b/docs/user/api/index.rst index 99a0878de4b..629253a4e7e 100644 --- a/docs/user/api/index.rst +++ b/docs/user/api/index.rst @@ -12,3 +12,4 @@ from Read the Docs. v3 v2 + /server-side-search/api diff --git a/docs/user/build-default-versions.rst b/docs/user/build-default-versions.rst index b6b961a45ef..46923c917b9 100644 --- a/docs/user/build-default-versions.rst +++ b/docs/user/build-default-versions.rst @@ -12,7 +12,7 @@ Default versions of dependencies Read the Docs supports two tools to build your documentation: `Sphinx `__ and `MkDocs `__. -In order to provide :doc:`several features `, +In order to provide :doc:`several features `, Read the Docs injects or modifies some content while building your docs. In particular, if you don't specify the dependencies of your project, diff --git a/docs/user/commercial/sharing.rst b/docs/user/commercial/sharing.rst index 0b5c90b8cba..112a068acca 100644 --- a/docs/user/commercial/sharing.rst +++ b/docs/user/commercial/sharing.rst @@ -1,5 +1,5 @@ -Sharing -======= +Private Documentation Sharing +============================= .. include:: /shared/admonition-rtd-business.rst diff --git a/docs/user/connected-accounts.rst b/docs/user/connected-accounts.rst index c3703c1a90e..2b5be584280 100644 --- a/docs/user/connected-accounts.rst +++ b/docs/user/connected-accounts.rst @@ -1,5 +1,5 @@ -Connecting your Git repository -============================== +How to connect your Git repository +================================== In this article, we explain how connecting your Read the Docs account to one of the supported Git providers automatically configures your Git repository and your Read the Docs project. diff --git a/docs/user/features.rst b/docs/user/features.rst deleted file mode 100644 index b0d5f64ab82..00000000000 --- a/docs/user/features.rst +++ /dev/null @@ -1,91 +0,0 @@ -Main Features -============= - -Read the Docs offers a number of platform features that are possible because we both build and host documentation for you. - - -Automatic Documentation Deployment ----------------------------------- - -We integrate with GitHub, Bitbucket, and GitLab. -We automatically create webhooks in your repository, -which tell us whenever you push a commit. -We will then build and deploy your docs every time you push a commit. -This enables a workflow that we call *Continuous Documentation*: - -**Once you set up your Read the Docs project, -your users will always have up-to-date documentation.** - -Learn more about :doc:`/integrations`. - -Custom Domains & White Labeling -------------------------------- - -When you import a project to Read the Docs, -we assign you a URL based on your project name. -You are welcome to use this URL, -but we also fully support custom domains for all our documentation projects. - -Learn more about :doc:`/custom-domains`. - -Versioned Documentation ------------------------ - -We support multiple versions of your documentation, -so that users can find the exact docs for the version they are using. -We build this on top of the version control system that you're already using. -Each version on Read the Docs is just a tag or branch in your repository. - -You don't need to change how you version your code, -we work with whatever process you are already using. -If you don't have a process, -we can recommend one. - -Learn more about :doc:`/versions`. - -Downloadable Documentation --------------------------- - -Read the Docs supports building multiple formats for Sphinx-based projects: - -* PDF -* ePub -* Zipped HTML - -This means that every commit that you push will automatically update your PDFs as well as your HTML. - -This feature is great for users who are about to get on a plane and want offline docs, -as well as being able to ship your entire set of documentation as one file. - -Learn more about :doc:`/downloadable-documentation`. - -Full-Text Search ----------------- - -We provide search across all the projects that we host. -This actually comes in two different search experiences: -dashboard search on the Read the Docs dashboard and in-doc search on documentation sites, using your own theme and our search results. - -We offer a number of search features: - -* Search across :doc:`subprojects ` -* Search results land on the exact content you were looking for -* Search across projects you have access to -* A full range of :doc:`search operators ` including exact matching and excluding phrases. - -Learn more about :doc:`/server-side-search/index`. - -Open Source and Customer Focused --------------------------------- - -Read the Docs cares deeply about our customers and our community. -As part of that commitment, -all of the source code for Read the Docs is open source. -This means there's no vendor lock-in, -and you are welcome to :doc:`contribute ` the features you want or run your own instance. - -Our bootstrapped company is owned and controlled by the founders, -and fully funded by our customers and advertisers. -That allows us to focus 100% of our attention on building the best possible product for you. - -Learn more :doc:`/about/index`. diff --git a/docs/user/guides/administrators.rst b/docs/user/guides/administrators.rst index f7473092763..418e7d75433 100644 --- a/docs/user/guides/administrators.rst +++ b/docs/user/guides/administrators.rst @@ -13,6 +13,7 @@ have a look at our :doc:`/tutorial/index`. :maxdepth: 1 Connect your git repository + /connected-accounts Connect your Read the Docs account to your Git repository Manage Custom Domains Enable Canonical URLs diff --git a/docs/user/guides/authors.rst b/docs/user/guides/authors.rst index cf5e9b0ce93..b853749b5c6 100644 --- a/docs/user/guides/authors.rst +++ b/docs/user/guides/authors.rst @@ -16,6 +16,9 @@ and :doc:`/intro/getting-started-with-mkdocs`. cross-referencing-with-sphinx Link to external projects (Intersphinx) jupyter + /guides/technical-docs-seo-guide Migrate from rST to MyST enable-offline-formats Using search analytics + /automatic-redirects + /science diff --git a/docs/user/guides/troubleshooting/index.rst b/docs/user/guides/troubleshooting/index.rst index 452156bc43f..99a2a7a0916 100644 --- a/docs/user/guides/troubleshooting/index.rst +++ b/docs/user/guides/troubleshooting/index.rst @@ -1,5 +1,5 @@ -Troubleshooting guides ----------------------- +Guides for troubleshooting problems +----------------------------------- In the following guides, you can learn how to fix common problems using Read the Docs. diff --git a/docs/user/index.rst b/docs/user/index.rst index 718a8893a65..5577d68d24c 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -10,18 +10,7 @@ Read the Docs: Documentation Simplified /intro/getting-started-with-sphinx /intro/getting-started-with-mkdocs /intro/import-guide - -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: How-to guides 🪄 - - /guides/authors - /guides/administrators - /guides/developers - Troubleshooting /examples - /faq .. toctree:: :maxdepth: 2 @@ -30,18 +19,21 @@ Read the Docs: Documentation Simplified /choosing-a-site /integrations - /pull-requests - /science - /automatic-redirects - /guides/technical-docs-seo-guide - /localization - /build-notifications - /custom-domains - /connected-accounts + /builds /downloadable-documentation - /subprojects - /single_version /environment-variables + /subprojects + /localization + +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: How-to guides 🪄 + + /guides/authors + /guides/administrators + /guides/developers + /guides/troubleshooting/index .. toctree:: :maxdepth: 2 @@ -49,13 +41,14 @@ Read the Docs: Documentation Simplified :caption: Reference 📚 /reference/features - /about/index - /api/index - /server-side-search/api + /config-file/index + /build-customization /server-side-search/syntax - /reference/environment-variables - changelog + /faq /glossary + /api/index + /changelog + /about/index Developer Documentation 🔗 .. meta:: @@ -94,7 +87,7 @@ Open Source and User Focused |:heartbeat:| .. _Read the docs: https://readthedocs.org/ -You can find out more about our all the :doc:`/features` in these pages. +You can find out more about our all the :doc:`features ` in these pages. First steps ----------- @@ -121,7 +114,6 @@ Learn more about configuring your automated documentation builds and some of the core features of Read the Docs. * **Overview of core features**: - :doc:`/features` | :doc:`/custom-domains` | :doc:`/versions` | :doc:`/downloadable-documentation` | diff --git a/docs/user/integrations.rst b/docs/user/integrations.rst index 4c7564999f0..0da1b5abeb9 100644 --- a/docs/user/integrations.rst +++ b/docs/user/integrations.rst @@ -6,7 +6,7 @@ (Perhaps reuse this: https://about.readthedocs.com/images/homepage.png) -Building documentation on every Git commit +Integrations: building docs on each commit ========================================== Read the Docs is a *Continuous Documentation Deployment* platform for your software project. diff --git a/docs/user/pull-requests.rst b/docs/user/pull-requests.rst index 5d96bec33a5..5e3e4afd240 100644 --- a/docs/user/pull-requests.rst +++ b/docs/user/pull-requests.rst @@ -2,9 +2,8 @@ Preview Documentation from Pull Requests ======================================== Your project can be configured to build and host documentation for every new -pull request. Previewing changes to your documentation during review makes it -easier to catch documentation formatting and display issues introduced in pull -requests. +pull request. Previewing changes during review makes it +easier to catch formatting and display issues before they go live. Features -------- diff --git a/docs/user/reference/features.rst b/docs/user/reference/features.rst index c51c9877ece..f2d29f6a2a5 100644 --- a/docs/user/reference/features.rst +++ b/docs/user/reference/features.rst @@ -4,9 +4,6 @@ Feature reference .. TODO: Continue to add more features here. -Hosting features ----------------- - ⏩️ :doc:`/custom-domains` Documentation projects can use their own domain name. A project may define multiple domains, @@ -20,38 +17,45 @@ Hosting features If you only have 1 version and translation, we also support :doc:`single version projects ` served at ``/``. +⏩️ :doc:`/pull-requests` + Your project can be configured to build and host documentation for every new pull request. + Previewing changes during review makes it easier to catch formatting and display issues. + +⏩️ :doc:`/build-notifications` + Build notifications can alert you when your builds fail so you can take immediate action. + +⏩️ :doc:`/reference/analytics` + Traffic and Search analytics are built into the platform. + This allows you to easily see what the most popular pages are, + and what people are searching for. ⏩️ :doc:`/user-defined-redirects` Projects may define their own custom URL redirects, with advanced functionality like folder redirects. +⏩️ :doc:`/commercial/sharing` + It is possible to host private and password protected documentation on Read the Docs for Business. + ⏩️ :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/sitemaps` Sitemaps are generated and hosted automatically, improving search engine optimization. This helps your users find content more effectively on your site. - ⏩️ :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/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:`/commercial/sharing` - It is possible to host private and password protected documentation on Read the Docs for Business. - .. 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. @@ -60,31 +64,30 @@ Hosting features .. toctree:: :maxdepth: 1 - :glob: + :caption: Hosting features - ../features - analytics - /server-side-search/index - /automation-rules + /custom-domains + /versions + /pull-requests + /build-notifications /user-defined-redirects - /badges + /reference/analytics + /commercial/sharing /reference/cdn + /reference/sitemaps /reference/404-not-found /reference/robots - /reference/sitemaps - /security-log - /config-file/index - /integrations - /versions + /server-side-search/index + /automation-rules + /badges + /security-log + /single_version - /builds - /build-customization - /environment-variables + /reference/environment-variables /flyout-menu /canonical-urls /feature-flags /commercial/organizations /commercial/privacy-level - /commercial/sharing /commercial/single-sign-on diff --git a/docs/user/science.rst b/docs/user/science.rst index 928bc6c1b38..965ef4e4957 100644 --- a/docs/user/science.rst +++ b/docs/user/science.rst @@ -24,7 +24,7 @@ Documentation and technical writing are broad fields. Their tools and practices have grown relevant to most scientific activities. This includes building publications, books, educational resources, interactive data science, resources for data journalism and full-scale websites for research projects and courses. -Here's a brief overview of some :doc:`features ` that people in science and academic writing love about Read the Docs: +Here's a brief overview of some :doc:`features ` that people in science and academic writing love about Read the Docs: .. dropdown:: 🪄 Easy to use :open: diff --git a/docs/user/tutorial/index.rst b/docs/user/tutorial/index.rst index 5d88e5c39b1..13c825cbbed 100644 --- a/docs/user/tutorial/index.rst +++ b/docs/user/tutorial/index.rst @@ -665,7 +665,7 @@ Here you have some resources to continue learning about documentation and Read the Docs: - You can learn more about the functionality of the platform - by going over our :doc:`/features` page. + by going over our :doc:`features ` page. - To make the most of the documentation generators that are supported, you can read the :doc:`Sphinx tutorial ` or the `MkDocs User Guide `_. From 6e405478af5872706688eff2bd5edf5cb5632324 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Tue, 14 Feb 2023 16:02:05 -0800 Subject: [PATCH 07/10] A bit more futzing --- docs/user/about/index.rst | 31 ++++++++++++++++--------------- docs/user/guides/index.rst | 4 ++-- docs/user/index.rst | 1 - docs/user/reference/features.rst | 8 ++++++-- docs/user/reference/policies.rst | 2 +- 5 files changed, 25 insertions(+), 21 deletions(-) diff --git a/docs/user/about/index.rst b/docs/user/about/index.rst index 117983746b5..8790b23c0f1 100644 --- a/docs/user/about/index.rst +++ b/docs/user/about/index.rst @@ -1,18 +1,6 @@ About Read the Docs =================== -.. toctree:: - :hidden: - - /commercial/index - /reference/policies - /advertising/index - /story - /sponsors - /open-source-philosophy - /team - /support - Read the Docs is a C Corporation registered in Oregon. Our bootstrapped company is owned and fully controlled by the founders, and fully funded by our customers and advertisers. @@ -38,9 +26,6 @@ This allows us to give back to the communities and projects that we support and We are proud about the way we manage our company and products, and are glad to have you on board with us in this :doc:`great documentation journey `. -Additional content -------------------------------- - If you want to dive more into more specific information and our policies, we've brought most of the most important ones below. @@ -68,7 +53,23 @@ we've brought most of the most important ones below. ⏩ :doc:`/support` Read this before asking for help: How to get support and where. +⏩ :doc:`/glossary` + A useful index of terms used in our docs. + .. seealso:: `Our website `__ Our primary website has general-purpose information about Read the Docs like pricing and feature overviews. + +.. toctree:: + :hidden: + + /commercial/index + /reference/policies + /advertising/index + /story + /sponsors + /open-source-philosophy + /team + /support + /glossary diff --git a/docs/user/guides/index.rst b/docs/user/guides/index.rst index 51a198528a2..6b754d32f6e 100644 --- a/docs/user/guides/index.rst +++ b/docs/user/guides/index.rst @@ -1,4 +1,4 @@ -:orphan: +:orphan: Guides ====== @@ -7,10 +7,10 @@ These guides will help walk you through specific use cases related to Read the Docs itself, documentation tools like Sphinx and MkDocs and how to write successful documentation. - .. toctree:: :maxdepth: 2 authors administrators + build-troubleshooting developers diff --git a/docs/user/index.rst b/docs/user/index.rst index 5577d68d24c..e5c764762b8 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -45,7 +45,6 @@ Read the Docs: Documentation Simplified /build-customization /server-side-search/syntax /faq - /glossary /api/index /changelog /about/index diff --git a/docs/user/reference/features.rst b/docs/user/reference/features.rst index f2d29f6a2a5..a27cedbf072 100644 --- a/docs/user/reference/features.rst +++ b/docs/user/reference/features.rst @@ -64,7 +64,7 @@ Feature reference .. toctree:: :maxdepth: 1 - :caption: Hosting features + :hidden: /custom-domains /versions @@ -78,12 +78,16 @@ Feature reference /reference/404-not-found /reference/robots +.. Move these to the above TOC once they're in the fancy list above + +.. toctree:: + :maxdepth: 1 + /server-side-search/index /automation-rules /badges /security-log /single_version - /reference/environment-variables /flyout-menu /canonical-urls diff --git a/docs/user/reference/policies.rst b/docs/user/reference/policies.rst index 32db4054109..57042614ae4 100644 --- a/docs/user/reference/policies.rst +++ b/docs/user/reference/policies.rst @@ -17,7 +17,7 @@ Here is some of the fine print used by |org_brand| and |com_brand|: /legal/security-policy /security /terms-of-service - DMCA takedown policy + /dmca/index /legal/dpa/index :doc:`/abandoned-projects` From 877f2e07b2603be266c1564e83f70d63264b3514 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Tue, 14 Feb 2023 16:46:34 -0800 Subject: [PATCH 08/10] Remove underscores from files, and do a bit more cleanup --- docs/user/guides/build-troubleshooting.rst | 2 +- .../guides/build-using-too-many-resources.rst | 2 +- docs/user/index.rst | 2 +- docs/user/integrations.rst | 4 ++-- docs/user/reference/features.rst | 24 ++++++++++++------- ....rst => contribute-to-troubleshooting.rst} | 0 ...{single_version.rst => single-version.rst} | 0 7 files changed, 20 insertions(+), 14 deletions(-) rename docs/user/shared/{contribute_to_troubleshooting.rst => contribute-to-troubleshooting.rst} (100%) rename docs/user/{single_version.rst => single-version.rst} (100%) diff --git a/docs/user/guides/build-troubleshooting.rst b/docs/user/guides/build-troubleshooting.rst index d5ef1f74dab..a1ee175ae6f 100644 --- a/docs/user/guides/build-troubleshooting.rst +++ b/docs/user/guides/build-troubleshooting.rst @@ -1,7 +1,7 @@ Troubleshooting build errors ============================ -.. include:: /shared/contribute_to_troubleshooting.rst +.. include:: /shared/contribute-to-troubleshooting.rst Git errors diff --git a/docs/user/guides/build-using-too-many-resources.rst b/docs/user/guides/build-using-too-many-resources.rst index eab08f2b9f4..7e01a795cc7 100644 --- a/docs/user/guides/build-using-too-many-resources.rst +++ b/docs/user/guides/build-using-too-many-resources.rst @@ -8,7 +8,7 @@ this troubleshooting guide will help you resolve some of the most common issues Build resources on Read the Docs are limited to make sure that users don't overwhelm our build systems. The current build limits can be found on our :ref:`Build resources reference `. -.. include:: /shared/contribute_to_troubleshooting.rst +.. include:: /shared/contribute-to-troubleshooting.rst Reduce formats you're building ------------------------------ diff --git a/docs/user/index.rst b/docs/user/index.rst index e5c764762b8..47feb2b65cf 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -19,7 +19,6 @@ Read the Docs: Documentation Simplified /choosing-a-site /integrations - /builds /downloadable-documentation /environment-variables /subprojects @@ -42,6 +41,7 @@ Read the Docs: Documentation Simplified /reference/features /config-file/index + /builds /build-customization /server-side-search/syntax /faq diff --git a/docs/user/integrations.rst b/docs/user/integrations.rst index 0da1b5abeb9..c3b4dd3dba2 100644 --- a/docs/user/integrations.rst +++ b/docs/user/integrations.rst @@ -6,8 +6,8 @@ (Perhaps reuse this: https://about.readthedocs.com/images/homepage.png) -Integrations: building docs on each commit -========================================== +Continuous Documentation Deployment +=================================== Read the Docs is a *Continuous Documentation Deployment* platform for your software project. Every time you change something in your documentation, Read the Docs will detect your change and build your documentation. diff --git a/docs/user/reference/features.rst b/docs/user/reference/features.rst index a27cedbf072..d0119d2a601 100644 --- a/docs/user/reference/features.rst +++ b/docs/user/reference/features.rst @@ -64,7 +64,7 @@ Feature reference .. toctree:: :maxdepth: 1 - :hidden: + :caption: Hosting Features /custom-domains /versions @@ -82,16 +82,22 @@ Feature reference .. toctree:: :maxdepth: 1 + :caption: Business features + + /commercial/organizations + /commercial/privacy-level + /commercial/single-sign-on + +.. toctree:: + :maxdepth: 1 + :caption: Additional features - /server-side-search/index /automation-rules /badges - /security-log - /single_version - /reference/environment-variables - /flyout-menu /canonical-urls /feature-flags - /commercial/organizations - /commercial/privacy-level - /commercial/single-sign-on + /flyout-menu + /reference/environment-variables + /security-log + /server-side-search/index + /single_version diff --git a/docs/user/shared/contribute_to_troubleshooting.rst b/docs/user/shared/contribute-to-troubleshooting.rst similarity index 100% rename from docs/user/shared/contribute_to_troubleshooting.rst rename to docs/user/shared/contribute-to-troubleshooting.rst diff --git a/docs/user/single_version.rst b/docs/user/single-version.rst similarity index 100% rename from docs/user/single_version.rst rename to docs/user/single-version.rst From e041d256ead8e0181af035ebb28ce18c138e453d Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Tue, 14 Feb 2023 16:55:24 -0800 Subject: [PATCH 09/10] Fix links --- docs/user/index.rst | 2 +- docs/user/reference/features.rst | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/user/index.rst b/docs/user/index.rst index 47feb2b65cf..385d3059aee 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -183,7 +183,7 @@ out of your documentation and Read the Docs. * **Advanced project configuration**: :doc:`subprojects` | - :doc:`Single version docs ` | + :doc:`Single version docs ` | :doc:`flyout-menu` | :doc:`feature-flags` diff --git a/docs/user/reference/features.rst b/docs/user/reference/features.rst index d0119d2a601..902b2b36a22 100644 --- a/docs/user/reference/features.rst +++ b/docs/user/reference/features.rst @@ -15,7 +15,7 @@ Feature reference 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 ` served at ``/``. + we also support :doc:`single version projects ` served at ``/``. ⏩️ :doc:`/pull-requests` Your project can be configured to build and host documentation for every new pull request. @@ -100,4 +100,4 @@ Feature reference /reference/environment-variables /security-log /server-side-search/index - /single_version + /single-version From 80c9f2e5656051c6f0ff999c4586f72a25c575e0 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Tue, 14 Feb 2023 16:58:51 -0800 Subject: [PATCH 10/10] Single TOC for all --- docs/user/about/index.rst | 2 +- docs/user/guides/developers.rst | 1 - docs/user/guides/troubleshooting/index.rst | 4 ++-- 3 files changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/user/about/index.rst b/docs/user/about/index.rst index 8790b23c0f1..e36c5761070 100644 --- a/docs/user/about/index.rst +++ b/docs/user/about/index.rst @@ -54,7 +54,7 @@ we've brought most of the most important ones below. Read this before asking for help: How to get support and where. ⏩ :doc:`/glossary` - A useful index of terms used in our docs. + A useful index of terms used in our docs .. seealso:: diff --git a/docs/user/guides/developers.rst b/docs/user/guides/developers.rst index 8ec157046eb..411b93680db 100644 --- a/docs/user/guides/developers.rst +++ b/docs/user/guides/developers.rst @@ -15,7 +15,6 @@ or customize the documentation appearance. embedding-content conda remove-edit-buttons - build-using-too-many-resources edit-source-links-sphinx Setup Build Notifications Use traffic analytics diff --git a/docs/user/guides/troubleshooting/index.rst b/docs/user/guides/troubleshooting/index.rst index 99a2a7a0916..d7fd27fce9e 100644 --- a/docs/user/guides/troubleshooting/index.rst +++ b/docs/user/guides/troubleshooting/index.rst @@ -10,5 +10,5 @@ you can learn how to fix common problems using Read the Docs. .. toctree:: :maxdepth: 1 - Build errors <../build-troubleshooting> - Slow builds <../build-using-too-many-resources> + ../build-troubleshooting + ../build-using-too-many-resources