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/about/index.rst b/docs/user/about/index.rst index 117983746b5..e36c5761070 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/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/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/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/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/guides/troubleshooting/index.rst b/docs/user/guides/troubleshooting/index.rst index 452156bc43f..d7fd27fce9e 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. @@ -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 diff --git a/docs/user/index.rst b/docs/user/index.rst index e432c5acc4d..385d3059aee 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -1,6 +1,55 @@ Read the Docs: Documentation Simplified ======================================= +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: Tutorials 🚀 + + /tutorial/index + /intro/getting-started-with-sphinx + /intro/getting-started-with-mkdocs + /intro/import-guide + /examples + +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: Explanation 💡 + + /choosing-a-site + /integrations + /downloadable-documentation + /environment-variables + /subprojects + /localization + +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: How-to guides 🪄 + + /guides/authors + /guides/administrators + /guides/developers + /guides/troubleshooting/index + +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: Reference 📚 + + /reference/features + /config-file/index + /builds + /build-customization + /server-side-search/syntax + /faq + /api/index + /changelog + /about/index + Developer Documentation 🔗 + .. meta:: :description lang=en: Automate building, versioning, and hosting of your technical documentation continuously on Read the Docs. @@ -37,7 +86,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 ----------- @@ -57,69 +106,6 @@ to help you create fantastic documentation for your project. * **Importing your existing documentation**: :doc:`Import guide ` - -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: Tutorials - - /tutorial/index - /intro/getting-started-with-sphinx - /intro/getting-started-with-mkdocs - /intro/import-guide - - -.. toctree:: - :maxdepth: 2 - :hidden: - :glob: - :caption: Explanation - - /localization - /choosing-a-site - /build-notifications - /integrations - /custom-domains - /environment-variables - /pull-requests - /connected-accounts - /downloadable-documentation - /subprojects - /single_version - /science - /automatic-redirects - /guides/technical-docs-seo-guide - -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: How-to Guides - - /guides/authors - /guides/administrators - /guides/developers - Troubleshooting - /examples - /faq - - -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: Reference - :glob: - - /reference/features - /api/index - /server-side-search/api - /server-side-search/syntax - /reference/environment-variables - changelog - Developer Documentation 🔗 - /about/index - /glossary - - Read the Docs feature overview ------------------------------ @@ -127,7 +113,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` | @@ -198,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/integrations.rst b/docs/user/integrations.rst index 4c7564999f0..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) -Building documentation on every Git 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/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..902b2b36a22 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, @@ -18,40 +15,47 @@ Hosting features 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. + 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,40 @@ 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 +.. Move these to the above TOC once they're in the fancy list above + +.. toctree:: + :maxdepth: 1 + :caption: Business features - /builds - /build-customization - /environment-variables - /flyout-menu - /canonical-urls - /feature-flags /commercial/organizations /commercial/privacy-level - /commercial/sharing /commercial/single-sign-on + +.. toctree:: + :maxdepth: 1 + :caption: Additional features + + /automation-rules + /badges + /canonical-urls + /feature-flags + /flyout-menu + /reference/environment-variables + /security-log + /server-side-search/index + /single-version 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` 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/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 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 `_.