diff --git a/docs/user/choosing-a-site.rst b/docs/user/choosing-a-site.rst deleted file mode 100644 index b964507b1ea..00000000000 --- a/docs/user/choosing-a-site.rst +++ /dev/null @@ -1,53 +0,0 @@ -Choosing between our two platforms -================================== - -Users often ask what the differences are between |org_brand| and |com_brand|. - -While many of our features are available on both of these platforms, there -are some key differences between our two platforms. - -Read the Docs Community ------------------------ - -|org_brand| is exclusively for hosting open source documentation. We support -open source communities by providing free documentation building and hosting -services, for projects of all sizes. - -Important points: - -* Open source project hosting is always free -* All documentation sites include advertising -* Only supports public VCS repositories -* All documentation is publicly accessible to the world -* Less build time and fewer build resources (memory & CPU) -* Email support included only for issues with our platform -* Documentation is organized by projects - -You can sign up for an account at https://readthedocs.org. - -Read the Docs for Business --------------------------- - -|com_brand| is meant for companies and users who have more complex requirements -for their documentation project. This can include commercial projects with -private source code, projects that can only be viewed with authentication, and -even large scale projects that are publicly available. - -Important points: - -* Hosting plans require a paid subscription plan -* There is no advertising on documentation sites -* Allows importing private and public repositories from VCS -* Supports private versions that require authentication to view -* Supports team authentication, including SSO with Google, GitHub, GitLab, and Bitbucket -* More build time and more build resources (memory & CPU) -* Includes 24x5 email support, with 24x7 SLA support available -* Documentation is organized by organization, giving more control over permissions - -You can sign up for an account at https://readthedocs.com. - -Questions? ----------- - -If you have a question about which platform would be best, -email us at support@readthedocs.org. diff --git a/docs/user/config-file/index.rst b/docs/user/config-file/index.rst index a853933444d..9bf7ea8ddad 100644 --- a/docs/user/config-file/index.rst +++ b/docs/user/config-file/index.rst @@ -1,27 +1,66 @@ -Configuration file -================== +.. TODO: Use new glossary terms added in another PR -In addition to using the admin panel of your project to configure your project, -you can use a configuration file in the root of your project. -The configuration file should be named ``.readthedocs.yaml``. +Versioning your configuration +============================= -.. note:: +The lifecycle of a documentation project changes the content and the structure of the documentation. +In addition to this, +**the whole configuration of a project also changes**. - Some other variants like ``readthedocs.yaml``, ``.readthedocs.yml``, etc - are deprecated. +But changing your configuration for your documentation's version 2.x should not make it impossible to keep maintaining the documentation for version 1.x using a previous configuration. + +.. seealso:: + + :doc:`/config-file/v2` + Reference of all the settings offered in the build configuration file. + +Consider the following aspects of a documentation project: + +:Build environment: + You may depend on a number of packages but your method for installing them changes. + What is installed, how it's installed and what installs it can change. + + For instance, + you might change between Pip, Pipenv, Conda etc. + + You might also jump between Python 2 and 3 or Python 3.8 and Python 3.10. + +:Documentation tools: + Using Sphinx? Using MkDocs? Or some other tool? + All these tools have their own configuration files and special ways to invoke them. + + Changing the documentation tool should also be possible in the lifecycle of your documentation. + Read the Docs understands outputs from several different documentation tools and therefore, + it's possible to change documentation tools between different versions of documentation. + + +You can configure your Read the Docs project by adding a special file ``.readthedocs.yaml`` [1]_ to your Git repository. + +Because the file is stored in Git, +the configuration will apply to the exact version that is being built. +This allows you to store different configurations for different versions of your documentation. The main advantages of using a configuration file over the web interface are: - Settings are per version rather than per project. -- Settings live in your VCS. +- Settings live in your Git repository. - They enable reproducible build environments over time. - Some settings are only available using a configuration file -.. tip:: +.. [1] Other variants of the configuration file name like ``readthedocs.yaml``, ``.readthedocs.yml``, etc. are deprecated. + +Configuration as Code +--------------------- + +"Configuration as Code" is a concept whereby the configuration or settings of software is maintained in a Git repository as *code*. +Alternatively, configurations are often added and managed inside the software's own UI, +making it hard to track changes, and reproduce and copy behavior to other projects. - Using a configuration file is the recommended way of using Read the Docs. +Because of its fragility and uniqueness, +the alternative to "Configuration as Code" is also often referred to as snowflake ❄️ configuration. -.. toctree:: - :maxdepth: 3 +.. seealso:: - Version 2 + :doc:`/guides/reproducible-builds` + In addition to storing your configuration in Git, + we also recommend special practices for making your builds resilient to changes in your software dependencies. diff --git a/docs/user/config-file/v2.rst b/docs/user/config-file/v2.rst index 01d83afe0c7..7c7f9ecdaa7 100644 --- a/docs/user/config-file/v2.rst +++ b/docs/user/config-file/v2.rst @@ -1,11 +1,15 @@ -Configuration file v2 -===================== +Configuration file .readthedocs.yaml +==================================== Read the Docs supports configuring your documentation builds with a YAML file. -The :doc:`configuration file ` must be in the root directory of your project -and be named ``.readthedocs.yaml``. +It's required to be named ``.readthedocs.yaml`` and be placed in the root of your Git repository. + +The file can contain a number of settings that are not accessible through the Read the Docs website. + +Because the file is stored in Git, +the configuration will apply to the exact version that is being built. +This allows you to store different configurations for different versions of your documentation. -All options are applied to the version containing this file. Below is an example YAML file which shows the most common configuration options: .. tabs:: @@ -942,3 +946,23 @@ These settings aren't supported via the configuration file. * ``Show versions warning`` * ``Privacy level`` * ``Analytics code`` + +Custom sub-folder for .readthedocs.yaml +--------------------------------------- + +In order to support *monorepo* layouts, +it's possible to configure the sub-folder where your ``.readthedocs.yaml`` is found. + +Using this configuration makes it possible to create several Read the Docs projects pointing at the same Git repository. +This is recommended for monorepo layouts that host several documentation projects in the same repository. + +.. seealso:: + + :doc:`/guides/setup/monorepo` + This guide explains how to use the configuration. + +Previous version: v1 +-------------------- + +Version 1 is deprecated and using it is discouraged, +view its reference here :doc:`/config-file/v2`. diff --git a/docs/user/connected-accounts.rst b/docs/user/connected-accounts.rst index 4fa9a05b7c2..fbae6320c43 100644 --- a/docs/user/connected-accounts.rst +++ b/docs/user/connected-accounts.rst @@ -19,8 +19,8 @@ we recommend that you connect your Read the Docs account to your Git provider. Connecting your account allows for: * Easy import of your repositories. -* Automatic configuration of your repository :doc:`/integrations`. - which allow Read the Docs to build your docs on every change to your repository +* Automatic configuration of your repository's :term:`webhooks `. + which allows Read the Docs to build your docs on every change to your repository. * Logging into Read the Docs with your |git_providers_or| credentials. @@ -71,7 +71,7 @@ Read the Docs does not generally ask for *write* permission to your repository c and since we only connect to public repositories we don't need special permissions to read them. However, we do need permissions for authorizing your account so that you can login to Read the Docs with your connected account credentials -and to setup :doc:`/integrations` +and to setup :term:`webhooks ` which allow us to build your documentation on every change to your repository. diff --git a/docs/user/environment-variables.rst b/docs/user/environment-variables.rst index 5b523bf8346..266e4079d47 100644 --- a/docs/user/environment-variables.rst +++ b/docs/user/environment-variables.rst @@ -4,11 +4,11 @@ Understanding environment variables =================================== Read the Docs allows you to define your own environment variables to be used in the build process. -It also defines a set of :doc:`default environment variables ` with information about your build. +It also defines a set of :doc:`pre-defined environment variables ` with information about your build. These are useful for different purposes: * Custom environment variables are useful for adding build secrets such as API tokens. -* Default environment variables are useful for varying your build specifically for Read the Docs or specific types of builds on Read the Docs. +* Pre-defined environment variables are useful for varying your build specifically for Read the Docs or specific types of builds on Read the Docs. .. The following introduction is difficult to balance. .. We should ideally support environment variables in the Config File, diff --git a/docs/user/explanation/advanced.rst b/docs/user/explanation/advanced.rst new file mode 100644 index 00000000000..38b520c105f --- /dev/null +++ b/docs/user/explanation/advanced.rst @@ -0,0 +1,35 @@ +Deep dive into Read the Docs +============================ + +In this section, +we explain some of the more specific or advanced concepts of writing documentation on Read the Docs. + +⏩️ :doc:`/config-file/index` + Configure your documentation build in a configuration file stored in Git: + The lifecycle of a documentation project changes the content and the structure of the documentation. + In addition to this, **the whole configuration of a project also changes**. + +⏩️ :doc:`/subprojects` + Thinking about gathering several documentation projects under the same umbrella? + This is a common need, and using *subprojects* is a flexible option that is recommended for most cases. + +⏩️ :doc:`/localization` + Learn more about multilingual documentation projects and how translation workflows are supported. + +⏩️ :doc:`/downloadable-documentation` + An introduction to adding downloadable files that can be read offline to your documentation and keep them versioned. + +⏩️ :doc:`/environment-variables` + Environment variables can be used to make your documentation builds flexible and easy to customize. + This is a general introduction to environment variables on our platform, both pre-defined and custom environment variables. + + +.. toctree:: + :maxdepth: 2 + :hidden: + + /config-file/index + /subprojects + /localization + /downloadable-documentation + /environment-variables diff --git a/docs/user/integrations.rst b/docs/user/explanation/continuous-documentation.rst similarity index 64% rename from docs/user/integrations.rst rename to docs/user/explanation/continuous-documentation.rst index d27e3d39b86..099f1c5cddd 100644 --- a/docs/user/integrations.rst +++ b/docs/user/explanation/continuous-documentation.rst @@ -7,28 +7,50 @@ -Continuous Documentation Deployment -=================================== +Continuous Documentation +======================== -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. +Read the Docs is a *Continuous Documentation* platform for your software project. +Every time you change something in your documentation, Read the Docs will automatically detect your changes, +*build* your documentation, +and finally *deploy* your documentation for readers to see. -The Continuous Integration and Continuous Deployment (CI/CD) features are configured with your repository provider, -such as GitHub, Bitbucket or GitLab. -With each change committed to your repository, we are notified by the configured *webhook*. +The Continuous Integration and Continuous Deployment (:term:`CI/CD`) features are configured with your repository provider, +such as |git_providers_or|. +With each change committed to your repository, we are notified by the configured :term:`webhook`. -When a receive a *webhook* notification, we match it to a project's *Integration*. -When a webhook is received, the matching project will then: +When a receive a *webhook* notification, we match it to a Read the Docs project. +The matching project will then process your build and publish the documentation. -* :doc:`Build ` the latest commit. -* Synchronize your versions based on the latest tag and branch data in Git. -* Run your :doc:`automation rules`. -* Auto-cancel any currently running builds of the same version. -* Add a log entry to the integration's :guilabel:`Recent Activity`. +.. seealso:: + + :doc:`/builds` + Read more about the technical specification of the Build process and how you configure it. + +.. The short version +.. ----------------- + +.. If you follow for instance the tutorial, +.. a simple setup will use our builders and deploy everything in the following way: + +.. 1. ... +.. 2. ... +.. 3. ... + +.. The long version +.. ---------------- + +.. * :doc:`Build ` the latest commit. +.. * Synchronize your versions based on the latest tag and branch data in Git. +.. * Run your :doc:`automation rules`. +.. * Auto-cancel any currently running builds of the same version. +.. * Add a log entry to the integration's :guilabel:`Recent Activity`. Continuous Documentation for software projects ---------------------------------------------- +.. TODO: This should be improved + Documentation fits into any CI/CD pipeline by following a process known as *Documentation as Code (Docs as code)*. The primary method of doing this is by maintaining documentation alongside the source code, meaning that the documentation's life cycle is the same as your software project. @@ -43,6 +65,11 @@ and increases overall value from the documentation you write. As part of this quick feedback loop, You can preview documentation changes immediately using :doc:`pull request previews `. +.. Continuous Documentation for scientific projects +.. ------------------------------------------------ + +.. We should perhaps write a short introduction here and reference the science page. + Automated versioning -------------------- diff --git a/docs/user/explanation/dedicated-platform.rst b/docs/user/explanation/dedicated-platform.rst new file mode 100644 index 00000000000..4f7f284b38c --- /dev/null +++ b/docs/user/explanation/dedicated-platform.rst @@ -0,0 +1,296 @@ +.. This page seeks to put out lots of pointers to other articles in the documentation +.. while giving an introduction that can be read consecutively. +.. TODO: +.. - More links and references! (remember the methodology section from a separate PR) +.. - Tiny screenshots possible? It would be nice if examples of features had little screenshots. + +.. There are other reasons that we could cover: +.. - Code: If you write docs as code, you want this +.. - When you should NOT choose a dedicated documentation CI/CD: You just need a README in your Git repo! You need WYSIWYG so badly that you're probably better off with Confluence, GitBook or Google Docs. +.. - A dedicated platform helps to solve tasks that you otherwise end up writing and maintaining your own scripts and CI tools for. +.. - Always evolving: Read the Docs develops new features on-demand. So you get a dedicated platform that's maintained and has new features added. +.. - Community: Related to the above, but perhaps worth mentioning that a lot of people are building tools and extensions that run on the platform etc. +.. - Reader features: Alternative name for "Batteries included" is "Reader features" +.. - Use-cases: The list would be really nice to wrap up with a set of use-cases. Software projects, onboarding docs, science, books etc. + +.. TODO: This article is kind of a "long-read" intended to read and share with other decision-makers. +.. It's not far from a "white paper", although it lacks case studies. +.. One way to help the reader would perhaps be to add a little box +.. Reading time: 15 minutes +.. Content: An elaborated case for why Read the Docs as a dedicated platform makes sense. +.. If you are interested in understanding why to use Read the Docs for the first time, this is a great starting point. + + +Read the Docs: An all-in-one documentation solution +=================================================== + +This page covers the benefits of using an all-in-one documentation platform. +There are a number of approaches to writing and deploying documentation, +but using a platform built for this purpose provides you with a number of benefits that generic platforms do not. + +The role of a *dedicated documentation platform* is to offer a compelling set of features that documentation projects and their organizations need. +This article gives a broad introduction to those features and their importance: + +🧭️️️ :ref:`lifecycle` + Documentation has a unique lifecycle, our platform handles a variety of challenges and complexities that documentation projects require, like versioning. + +🛠️ :ref:`documentation_tools` + Support for a variety of documentation tools allows you the flexibility to choose the best tool for your project. + +🚢️️ :ref:`workflows` + Our platform works like a :term:`CI/CD platform `, publishing and versioning your documentation automatically. + You save time not writing your own scripts and deployment workflows, + and get a reliable and reproducible process. + +🔋️ :ref:`batteries_included` + Read the Docs continues to develop new projects and ideas, + bringing additional powers to documentation projects that are hosted on the platform. + +.. The following sections are about using a dedicated platform as a first-choice in order to free up space for other tasks. +.. These paragraphs can benefit from being shortened and organized, but they are intended as the summary of the introduction. + +Using Read the Docs allows you to focus on other critical tasks, +such as choosing structuring and writing your documentation itself! + +.. seealso:: + + `Comparison with GitHub Pages `__ + On our website, we have a list of common tasks that teams have to solve themselves on a generic CI. + +.. _lifecycle: + +Features for the lifecycle of a documentation project +----------------------------------------------------- + +Read the Docs is a platform with over a decade of experience in automating documentation tools. +The platform handles your current challenges or challenges that you face down the road. +The right features are available when you need them. + +Some features respond to external factors, +while other features respond to the natural development of a documentation project. +The combined set of features make it possible to bootstrap a small documentation project and turn it into a mature enterprise product. + +.. figure:: /img/documentation-lifecycle.svg + :alt: A diagram of external effects to a documentation's lifecycle + + The number of effects on a lifecycle are many. + Some are caused by external factors, + changes to the product or project, + changes in the team, + vision etc. + +Example: Automated versioning and redirects + Once a documentation project is bootstrapped, + the software product might change its version and remove or add features. + Old versions of the product still need to be able to refer to their original documentation while new versions should not be unnecessarily complicated by documenting old features. + + As your documentation grows and pages are moved around, versioning and redirects become critical. + + :doc:`Versioning ` is a core part of documentation projects on our platform. + And on top of versioning support, + Read the Docs offers a mature set of :doc:`user-defined redirects `. + +Example: Analytics + Documentation websites benefit from knowing which pages are popular and how people discover them through online search. + + This may not be an immediate requirement for a documentation project, + but the need often arises. + And why should every documentation project have to implement their own analytics solution? + For this, you can use :doc:`/reference/analytics`. + +Example: Cloud hosting (CDN) + Read the Docs deploys and hosts your documentation. + Part of this package is to host documentation projects with a CDN in front of them, + so you never have to worry about incoming traffic. + + We also have intelligent caching, + so you don't have to worry about when to invalidate your cloud cache when your project is updated. + + Read more in :doc:`/reference/cdn`. + +.. seealso:: + + :doc:`/reference/features` + A practical way to understand Read the Docs is to look at our :doc:`list of features `. + All these features ultimately sustain the lifecycle of a documentation project. + + +.. _documentation_tools: + +Freedom to choose documentation tools +------------------------------------- + +One of the big choices facing new documentation project is to choose between the many documentation tools that exist. +Read the Docs was originally built for Sphinx, +but has since then evolved into a generic documentation building platform. + +In the :doc:`build process `, +your documentation tool is called according to your own configuration and Read the Docs will then gather, version and publish files written by the documentation tool. +Whatever documentation tool you choose to build with, +your static website and additional :doc:`offline formats ` can be versioned and published at your project's :doc:`domain ` + +A documentation tool simply needs to be able to run on Linux inside a Docker container. +Most documentation frameworks will do this. +Some examples include: + +.. TODO: expand the list and add links + +* :doc:`Sphinx ` +* `MkDocs `__ and `Material for MkDocs `__ +* `Jupyter Book `__ +* `Pelican `__ +* `Docusaurus `__ +* `Docsy for Hugo `__ +* `Asciidoctor `__ +* ...and any other tool that will install and run in a Docker container. +* ...and plugins/extensions/themes for all of the above. + +.. _workflows: + +Move faster by integrating the building and deployment of documentation +----------------------------------------------------------------------- + +Automating your `build and deploy process `, +enables documentation writers to suggest changes, share previews, receive feedback and implement feedback quickly and iteratively. +Making your documentation project's workflow *agile* is supported by Read the Docs through a number of features. +Here are some examples: + +.. these examples need more love. They could be more focused on practical tasks, rather than just the abstract topic. + +Example: Automatic Git integration + Many software projects already have a Git workflow, + while many other types of projects have recently discovered the benefits of using Git. + A dedicated documentation CI/CD will hook into your Git repository and be notified of changes so it can build and publish your documentation. + This includes a number of additional options, + such as support for private repositories, + storing Read the Docs configuration in the Git repository (configuration as code) + and managing access through GitHub SSO. + +Example: Automatic previews + When someone opens a *pull request*, + Read the Docs will automatically build and display these changes, + allowing your workflow to continue undisturbed. + No need to email screenshots or attachments. + No need to upload a temporary version somewhere. + +Example: Automatic deploys with version tagging + Read the Docs enables you to only have to do things once. + You can *tag* your new version in Git and then have Read the Docs automatically see your change and publish a new version, + keeping old versions active. + +.. seealso:: + + :doc:`/explanation/continuous-documentation` + A more technical introduction to CI/CD for documentation projects. + + `Diátaxis Framework `__ + Having an agile workflow enables your documentation project to *grow organically*. + This is one of the core principles of the Diatáxis Methodology, + which presents a universal structure and agile workflow methodology for documentation projects. + + +.. _batteries_included: + +Better documentation reader experience +-------------------------------------- + +Read the Docs offers a number of features that are visible to readers of your documentation. +This gives you the ability to provide a nicer experience to your readers, +while also providing many benefits to the authors and maintainers. + +Example: Integrated :doc:`server side search ` + Many documentation tools include a small JavaScript-based search utilities. + Some don't. + In any case, + Read the Docs parses and indexes your HTML and offers a search form and search result dialogue that fits in any documentation project. + Search results can be delivered faster than JavaScript-based search tools and we also offer searches across multiple projects, + which is great for organizations. + +Example: :doc:`Flyout menu ` + By default, + an MkDocs and Sphinx project hosted on Read the Docs will have a little :term:`flyout menu` at the bottom of the screen. + The menu always contains the latest list of releases and alternative formats, + as well as convenient links to edit the project on |git_providers_or|. + + .. note:: + + As of April 2023, we are testing a new version of the :term:`flyout menu`, + which integrates with any documentation project. + Please contact :doc:`/support` for more information. + +.. TODO: Split this into an include:: since we are repeating it + +.. seealso:: + + :doc:`/reference/features` + A practical way to understand Read the Docs is to look at our :doc:`list of features `. + All these features ultimately sustain the lifecycle of a documentation project. + + +.. Types of documentation projects +.. ------------------------------- + +.. Software projects +.. ~~~~~~~~~~~~~~~~~ + +.. Scientific writing and academic projects +.. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _com_org_differences: + +Differences between Community and Business +------------------------------------------ + +While many of our features are available on both of these platforms, there +are some key differences between our two platforms. + +.. seealso:: + + `Our website: Comparison of Community and all subscription plans `__ + Refer to the complete table of features included in all of the Read the Docs solutions available. + +|org_brand| +~~~~~~~~~~~ + +|org_brand| is exclusively for free and open source software, content and projects. +We support open source communities by providing free documentation building and hosting +services, for projects of all sizes. + +Important points: + +* Open source project hosting is always free +* All documentation sites include advertising +* Only supports public VCS repositories +* All documentation is publicly accessible to the world +* Less build time and fewer build resources (memory & CPU) +* Email support included only for issues with our platform +* Documentation is organized by projects + +You can sign up for an account at https://readthedocs.org. + +|com_brand| +~~~~~~~~~~~ + +|com_brand| is meant for companies and users who have more complex requirements +for their documentation project. This can include commercial projects with +private source code, projects that can only be viewed with authentication, and +even large scale projects that are publicly available. + +Important points: + +* Hosting plans require a paid subscription plan +* There is no advertising on documentation sites +* Allows importing private and public repositories from VCS +* Supports private versions that require authentication to view +* Supports team authentication, including SSO with Google, GitHub, GitLab, and Bitbucket +* More build time and more build resources (memory & CPU) +* Includes 24x5 email support, with 24x7 SLA support available +* Documentation is organized by organization, giving more control over permissions + +You can sign up for an account at https://readthedocs.com. + +Questions? +~~~~~~~~~~ + +If you have a question about which platform would be best, +email us at support@readthedocs.org. diff --git a/docs/user/flyout-menu.rst b/docs/user/flyout-menu.rst index 640c51701bb..072b815a5b1 100644 --- a/docs/user/flyout-menu.rst +++ b/docs/user/flyout-menu.rst @@ -14,7 +14,7 @@ The flyout menu provides access to the following bits of Read the Docs functiona * A :doc:`version switcher ` that shows users all of the active, unhidden versions they have access to. * :doc:`Offline formats ` for the current version, including HTML & PDF downloads that are enabled by the project. * Links to the Read the Docs dashboard for the project. -* Links to your :doc:`VCS provider ` that allow the user to quickly find the exact file that the documentation was rendered from. +* Links to your Git provider (|git_providers_or|) that allow the user to quickly find the exact file that the documentation was rendered from. * A search bar that gives users access to our :doc:`/server-side-search/index` of the current version. Closed diff --git a/docs/user/guides/importing-private-repositories.rst b/docs/user/guides/importing-private-repositories.rst index f5bd09f916f..ad63df98a22 100644 --- a/docs/user/guides/importing-private-repositories.rst +++ b/docs/user/guides/importing-private-repositories.rst @@ -4,7 +4,7 @@ How to import private repositories .. warning:: This guide is for users of :doc:`/commercial/index`. - **If you are using GitHub, GitLab, or Bitbucket**, + **If you are using |git_providers_or|**, we recommend :doc:`connecting your account ` and importing your project from https://readthedocs.com/dashboard/import instead of importing it manually. @@ -122,7 +122,7 @@ Webhooks -------- To build your documentation on every commit, -you'll need to manually add a webhook, see :doc:`/integrations`. +you'll need to manually add a webhook, see :doc:`/guides/git-integrations`. If you are using an unsupported integration, you may need to setup a custom integration using our :ref:`generic webhook `. diff --git a/docs/user/img/documentation-lifecycle.svg b/docs/user/img/documentation-lifecycle.svg new file mode 100644 index 00000000000..7dea16826bd --- /dev/null +++ b/docs/user/img/documentation-lifecycle.svg @@ -0,0 +1,316 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Product changesname + + + + + + + + + + + + + + + Maintainerscome and go + + + + + + + + + + + + + + + “Let’s refactorthe navigation!” + + + + + + + + + + + + + + + Big changes from 1.0 to 2.0=> new API, new theme + + + + + + + + + + + + + + + Features added anddeprecated in 1.1 + + + + + + Documentationlifecycle + + + + + + + + + + + + + + + Contributor suggestsa new page orsmall change + + + + + + + + + + + + + + + Analyzing andunderstandinguser behavior + + + + + + + + + + + + + + + Inviting stake-holders for a hidden release + + + + + + + + + + + + + + + Adding a new custom domain + + + + + + + + + + + + + + + New tool for APIdocumentation + + + + + + + + + + + + + + + Several active development branches + + + + + + + + + + + + + + + Sudden success!100,000 page viewsper day. + + + + + + + + diff --git a/docs/user/index.rst b/docs/user/index.rst index db83fb90cae..3c5babf763f 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -17,12 +17,9 @@ Read the Docs: documentation simplified :hidden: :caption: 💡 Explanation - /choosing-a-site - /integrations - /downloadable-documentation - /environment-variables - /subprojects - /localization + /explanation/dedicated-platform + /explanation/continuous-documentation + /explanation/advanced .. toctree:: :maxdepth: 2 @@ -44,7 +41,7 @@ Read the Docs: documentation simplified :caption: 📚 Reference /reference/features - /config-file/index + /config-file/v2 /builds /build-customization /server-side-search/syntax @@ -85,7 +82,7 @@ and your documentation up to date. |org_brand| hosts documentation for over 100,000 large and small open source projects. |com_brand| supports hundreds of organizations with product and internal documentation. - Learn more about :doc:`our two platforms `. + Learn more about :ref:`our two platforms `. First time here? ---------------- @@ -123,17 +120,14 @@ Get a high-level overview of our platform: .. TODO: This next item needs its article to be finished in a separate PR .. https://github.com/readthedocs/readthedocs.org/pull/10071 -💡 :doc:`Continuous Documentation ` - Discover the advantages of having your documentation continuously deployed. - -💡 :doc:`/choosing-a-site` - Learn about the differences between |org_brand| and |com_brand|. +💡 :doc:`/explanation/dedicated-platform` + An introduction to the reasons behind choosing a dedicated documentation platform. -.. TODO: This next item needs its article to be finished in a separate PR -.. https://github.com/readthedocs/readthedocs.org/pull/10071 -.. TODO: 💡 Advanced topics: Deep-dive into Read the Docs -.. Get familiar with some of the more advanced topics of building and deploying documentation with Read the Docs. +💡 :doc:`/explanation/continuous-documentation` + Discover the advantages of having your documentation continuously deployed. +💡 :doc:`/explanation/advanced` + Get familiar with some of the more advanced topics of building and deploying documentation. How-to guides ------------- @@ -166,7 +160,7 @@ Need to know how something works? Our references provide the details: 📚 :doc:`/reference/features` Overview of all the main features of Read the Docs. -📚 :doc:`/config-file/index` +📚 :doc:`/config-file/v2` Information for our configuration file: ``.readthedocs.yaml``. 📚 :doc:`/builds` diff --git a/docs/user/tutorial/index.rst b/docs/user/tutorial/index.rst index 7420f086bf3..29391c443bb 100644 --- a/docs/user/tutorial/index.rst +++ b/docs/user/tutorial/index.rst @@ -112,7 +112,7 @@ Welcome! Our commercial site offers some extra features, like support for private projects. - You can learn more about :doc:`our two different sites `. + You can learn more about :ref:`our two platforms `. First steps ----------- @@ -675,7 +675,7 @@ and Read the Docs: available under :doc:`/guides/index`. - For private project support and other enterprise features, you can use :doc:`our commercial service ` - (and if in doubt, check out :doc:`/choosing-a-site`). + (and if in doubt, check out :ref:`com_org_differences`). - Do you want to join a global community of fellow `documentarians `? Check out `Write the Docs `_ and :doc:`its Slack workspace `. diff --git a/docs/user/versions.rst b/docs/user/versions.rst index a20c7f994d4..d5e3a8f19c8 100644 --- a/docs/user/versions.rst +++ b/docs/user/versions.rst @@ -12,7 +12,7 @@ we also create a ``stable`` version, tracking your most recent release. If you want a custom ``stable`` version, create either a tag or branch in your project with that name. -When you have :doc:`/integrations` configured for your repository, +When you have :term:`webhook` configured for your repository, we will automatically build each version when you push a commit. How we envision versions working