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/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 index 323c7b06f2e..5459843f87d 100644 --- a/docs/user/explanation/advanced.rst +++ b/docs/user/explanation/advanced.rst @@ -18,6 +18,8 @@ we explain some of the more specific or advanced concepts of writing documentati ⏩️ :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 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 4088dc21774..c29a57b4dcb 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 we 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 :term:`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..45520602d6e --- /dev/null +++ b/docs/user/explanation/dedicated-platform.rst @@ -0,0 +1,290 @@ +.. 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: +.. - Tiny screenshots possible? It would be nice if examples of features had little screenshots. + +.. Inspiration for items to 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. + +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: + +* :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/explanation/index.rst b/docs/user/explanation/index.rst index b78ab9912aa..d18b2ab4051 100644 --- a/docs/user/explanation/index.rst +++ b/docs/user/explanation/index.rst @@ -6,12 +6,15 @@ Explanation =========== -⏩️ :doc:`/choosing-a-site` - Users often ask what the differences are between Read the Docs Community and Read the Docs for Business: here's an overview. +⏩️ :doc:`/explanation/dedicated-platform` + An introduction to what a dedicated documentation platform like Read the Docs does offers documentation projects. -⏩️ :doc:`/integrations` +⏩️ :doc:`/explanation/continuous-documentation` A high-level introduction to *Continuous Documentation Deployment*. +⏩️ :doc:`/config-file/index` + An explanation of the value of having a versioned configuration file for your project. + ⏩️ :doc:`/subprojects` Learn more about how several documentation projects can be combined and presented to the reader on the same website. @@ -29,9 +32,6 @@ Explanation :maxdepth: 1 :hidden: - /choosing-a-site - /integrations - /subprojects - /localization - /downloadable-documentation - /environment-variables + /explanation/dedicated-platform + /explanation/continuous-documentation + /explanation/advanced 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/setup/git-repo-automatic.rst b/docs/user/guides/setup/git-repo-automatic.rst index 04aa310f55e..e602307d306 100644 --- a/docs/user/guides/setup/git-repo-automatic.rst +++ b/docs/user/guides/setup/git-repo-automatic.rst @@ -48,11 +48,10 @@ including the ones that were automatically created. .. 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. - .. seealso:: :ref:`intro/import-guide:Manually import your docs` @@ -111,7 +110,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/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 d7f41f2d311..ef03cbdb044 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -17,8 +17,8 @@ Read the Docs: documentation simplified :hidden: :caption: 💡 Explanation - /choosing-a-site - /integrations + /explanation/dedicated-platform + /explanation/continuous-documentation /explanation/advanced .. toctree:: @@ -82,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? ---------------- @@ -117,22 +117,18 @@ Get a high-level overview of our platform: .. Descriptions here are focused on learning -.. TODO: This next item needs its article to be finished in a separate PR -.. https://github.com/readthedocs/readthedocs.org/pull/10071 +💡 :doc:`/explanation/dedicated-platform` + An introduction to the reasons behind choosing a dedicated documentation platform. -💡 :doc:`Continuous Documentation ` +💡 :doc:`/explanation/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/advanced` Get familiar with some of the more advanced topics of building and deploying documentation with Read the Docs. 💡 :doc:`All explanation articles ` Browser all our explanation articles. - How-to guides ------------- diff --git a/docs/user/tutorial/index.rst b/docs/user/tutorial/index.rst index 55af5deed97..8853a964dbf 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 ----------- @@ -685,7 +685,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