diff --git a/docs/user/_static/images/first-steps/admin-panel.png b/docs/user/_static/images/first-steps/admin-panel.png deleted file mode 100644 index 9f6cc24dd3e..00000000000 Binary files a/docs/user/_static/images/first-steps/admin-panel.png and /dev/null differ diff --git a/docs/user/_static/images/first-steps/import-a-repository.png b/docs/user/_static/images/first-steps/import-a-repository.png deleted file mode 100644 index 252f69834df..00000000000 Binary files a/docs/user/_static/images/first-steps/import-a-repository.png and /dev/null differ diff --git a/docs/user/glossary.rst b/docs/user/glossary.rst index adfe5b72cb6..8dbca79b354 100644 --- a/docs/user/glossary.rst +++ b/docs/user/glossary.rst @@ -11,12 +11,21 @@ so that you have a reference for how we're using them. In some scenarios, they exist as two separate platforms. Read the Docs is a combined CI/CD platform made for documentation. + configuration file + YAML configuration file (e.g. ``.readthedocs.yaml``) that configures the build process of your project on Read the Docs. + + .. seealso:: + + :doc:`/config-file/index` + Practical steps to add a configuration file to your documentation project. + + dashboard The "admin" site where Read the Docs projects are managed and configured. This varies for our two properties: - * |com_brand|: https://readthedocs.com/dashboard/. - * |org_brand|: https://readthedocs.org/dashboard/. + * |com_brand|: https://app.readthedocs.com/dashboard/ + * |org_brand|: https://app.readthedocs.org/dashboard/ default version Projects have a *default version*, usually the latest stable version of a project. @@ -145,4 +154,10 @@ so that you have a reference for how we're using them. * Git providers have webhooks which are special URLs that Read the Docs can call in order to notify about documentation builds. * Read the Docs has a unique webhook for each project that the Git provider calls when changes happen in Git. - See also: :doc:`/guides/setup/git-repo-manual` and :doc:`/build-notifications` + .. seealso:: + + :doc:`/guides/setup/git-repo-manual` + Manually configuration for Git repositories. + + :doc:`/build-notifications` + Receive notifications when your documentation builds fail. diff --git a/docs/user/guides/importing-private-repositories.rst b/docs/user/guides/importing-private-repositories.rst index 20a2df6360d..c98a271e304 100644 --- a/docs/user/guides/importing-private-repositories.rst +++ b/docs/user/guides/importing-private-repositories.rst @@ -8,7 +8,7 @@ Here is how you set it up. ✅ī¸ Logged in with |git_providers_or|? If you signed up or logged in to Read the Docs with your |git_providers_or| credentials, - *all you have to do* is to use the normal :doc:`project import `. + *all you have to do* is to use the normal :doc:`project import `. Your Read the Docs account is connected to your Git provider and will let you choose from private Git repositories and configure them for you. diff --git a/docs/user/guides/setup/git-repo-automatic.rst b/docs/user/guides/setup/git-repo-automatic.rst index bb212ab7f78..225fc25aeb8 100644 --- a/docs/user/guides/setup/git-repo-automatic.rst +++ b/docs/user/guides/setup/git-repo-automatic.rst @@ -26,7 +26,7 @@ the integration will automatically be configured on the Read the Docs project an Here is an outline of what happens: #. A list of repositories that you have access to are automatically listed on Read the Docs' project import. -#. You choose a Git repository from the list (see :doc:`/intro/import-guide`). +#. You choose a Git repository from the list (see :doc:`/intro/add-project`). #. Data about the repository is now fetched using the account connection and you are asked to confirm the setup. #. When Read the Docs creates your project, it automatically sets up an integration with the Git provider, @@ -55,7 +55,7 @@ including the ones that were automatically created. .. seealso:: - :ref:`intro/import-guide:Manually import your docs` + :ref:`intro/add-project:Manually add your project` Using a different provider? Read the Docs still supports other providers such as Gitea or GitHub Enterprise. In fact, any Git repository URL can be configured manually. @@ -80,7 +80,7 @@ By granting Read the Docs the requested permissions, we are issued a secret OAuth token from your Git provider. Using the secret token, -we can automatically configure the repository that you select in the :doc:`project import `. +we can automatically configure repositories during :doc:`project creation `. We also use the token to send back build statuses and preview URLs for :doc:`pull requests `. .. _OAuth: https://en.wikipedia.org/wiki/OAuth diff --git a/docs/user/guides/setup/monorepo.rst b/docs/user/guides/setup/monorepo.rst index fc7347abd14..d376afc175d 100644 --- a/docs/user/guides/setup/monorepo.rst +++ b/docs/user/guides/setup/monorepo.rst @@ -36,10 +36,8 @@ A custom build configuration file path is applied to all versions of your docume Adding an additional project from the same repository ----------------------------------------------------- -Once you have added the first project from the :ref:`Import Wizard `, -it will show as if it has already been imported and cannot be imported again. -In order to add another project with the same repository, -you will need to use the :ref:`Manual Import `. +Once you have added the first project from the :ref:`Import Wizard `, +you will need to repeat this process again to add the additional project from the same repository. Setting the custom build configuration file ------------------------------------------- diff --git a/docs/user/index.rst b/docs/user/index.rst index bcdce68e49d..c5ac5cca7d9 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -9,7 +9,7 @@ Read the Docs: documentation simplified /tutorial/index /intro/getting-started-with-sphinx /intro/getting-started-with-mkdocs - /intro/import-guide + /intro/add-project /examples .. toctree:: diff --git a/docs/user/intro/add-project.rst b/docs/user/intro/add-project.rst new file mode 100644 index 00000000000..5ef93621c52 --- /dev/null +++ b/docs/user/intro/add-project.rst @@ -0,0 +1,62 @@ +Adding a documentation project +============================== + +.. meta:: + :description lang=en: Add your existing documentation from a Git repository into Read the Docs. + +This page takes you through the process of adding a documentation project to Read the Docs. +If you have :doc:`connected your Read the Docs account ` to GitHub, Bitbucket or GitLab you will be able to add your project automatically. +Otherwise, you will need to add it manually and perform some extra steps. + +Automatically add your project +------------------------------ + +#. Go to your :term:`dashboard`. +#. Click on :guilabel:`Add project`. +#. Type the name of the respository you want to add and click on it. +#. Click on :guilabel:`Continue`. +#. Edit any of the pre-filled fields with information of the repository. +#. Click on :guilabel:`Next`. +#. Add a :term:`configuration file` to your repository if it's doesn't exist yet. +#. Click on :guilabel:`This file exists`. + +Manually add your project +------------------------- + +#. Go to your :term:`dashboard`. +#. Click on :guilabel:`Add project`. +#. Click on :guilabel:`Configure manually`. +#. Click on :guilabel:`Continue`. +#. Fill all the fields of the form. +#. Click on :guilabel:`Next`. +#. Add a :term:`configuration file` to your repository if it's doesn't exist yet. +#. Click on :guilabel:`This file exists`. + +Once your project is created, you'll need to manually configure the repository webhook if you would like to have new changes trigger builds for your project on Read the Docs. + +.. seealso:: + + :doc:`/guides/setup/git-repo-manual` + Additional setup steps required for manually created projects. This guide covers setting up SSH keys and webhook integrations. + + +What's next +----------- + +Once your documentation project is created, a build will be triggered. +It will automatically fetch the code from your repository and build the documentation. +You can see the logs for the build process from your :term:`dashboard`. + +.. seealso:: + + :doc:`/builds` + Explanation about the build process. + + :doc:`/config-file/index` + Practical steps to add a configuration file to your documentation project. + + :doc:`/versions` + Manage multiple versions of your documentation project. + +If you have any trouble, don't hesitate to reach out to us. +The :doc:`support ` page has more information on getting in touch. diff --git a/docs/user/intro/getting-started-with-mkdocs.rst b/docs/user/intro/getting-started-with-mkdocs.rst index 150d07ccb30..9f952e4db9f 100644 --- a/docs/user/intro/getting-started-with-mkdocs.rst +++ b/docs/user/intro/getting-started-with-mkdocs.rst @@ -22,7 +22,7 @@ It has many great features including: Quick start ----------- -.. seealso:: If you already have a Mkdocs project, check out our :doc:`/intro/import-guide` guide. +.. seealso:: If you already have a Mkdocs project, check out our :doc:`/intro/add-project` guide. Assuming you have Python already, `install MkDocs`_: @@ -59,7 +59,7 @@ You can make changes to your Markdown files and your docs will automatically reb Your MkDocs project is built Once you have your documentation in a public repository such as GitHub, Bitbucket, or GitLab, -you can start using Read the Docs by :doc:`importing your docs `. +you can start using Read the Docs by :doc:`adding a project `. .. _install MkDocs: https://www.mkdocs.org/user-guide/installation/ diff --git a/docs/user/intro/getting-started-with-sphinx.rst b/docs/user/intro/getting-started-with-sphinx.rst index 48fb3b5c68d..3ed44e7bcd7 100644 --- a/docs/user/intro/getting-started-with-sphinx.rst +++ b/docs/user/intro/getting-started-with-sphinx.rst @@ -22,7 +22,7 @@ check out :doc:`/tutorial/index`. Quick start ----------- -.. seealso:: If you already have a Sphinx project, check out our :doc:`/intro/import-guide` guide. +.. seealso:: If you already have a Sphinx project, check out our :doc:`/intro/add-project` guide. Assuming you have Python already, :doc:`install Sphinx `: @@ -68,7 +68,7 @@ Open this file in your web browser to see your docs. Edit your files and rebuild until you like what you see, then commit your changes and push to your public repository. Once you have Sphinx documentation in a public repository, you can start using Read the Docs -by :doc:`importing your docs `. +by :doc:`adding a project `. .. warning:: diff --git a/docs/user/intro/import-guide.rst b/docs/user/intro/import-guide.rst deleted file mode 100644 index f98d2d8bfda..00000000000 --- a/docs/user/intro/import-guide.rst +++ /dev/null @@ -1,93 +0,0 @@ -Importing your documentation -============================ - -.. meta:: - :description lang=en: Import your existing technical documentation from version control into Read the Docs. - - -To import a public documentation repository, visit your `Read the Docs dashboard`_ and click Import_. -For private repositories, please use :doc:`Read the Docs for Business `. - -Automatically import your docs ------------------------------- - -If you have :doc:`connected your Read the Docs account ` to GitHub, Bitbucket, or GitLab, -you will see a list of your repositories that we are able to import. -To import one of these projects, just click the import -icon next to the repository you'd like to import. This will bring up a form that -is already filled with your project's information. Feel free to edit any of -these properties, and then click **Next** to -:ref:`build your documentation `. - -.. _Read the Docs dashboard: https://readthedocs.org/dashboard -.. _Import: https://readthedocs.org/dashboard/import - - -.. figure:: ../_static/images/first-steps/import-a-repository.png - :align: right - :figwidth: 300px - - Importing a repository - - -Manually import your docs -------------------------- - -If you have not :doc:`connected a Git provider account `, -you will need to select **Import Manually** -and enter the information for your repository yourself. You will also need to -manually configure the webhook for your repository as well. When importing your -project, you will be asked for the repository URL, along with some other -information for your new project. The URL is normally the URL or path name you'd -use to checkout, clone, or branch your repository. Some examples: - -* ``https://github.com/ericholscher/django-kong.git`` -* ``https://gitlab.com/gitlab-org/gitlab`` - -Add an optional homepage URL and some tags, and then click **Next**. - -Once your project is created, you'll need to manually configure the repository -webhook if you would like to have new changes trigger builds for your -project on Read the Docs. Go to your project's :guilabel:`Admin` > :guilabel:`Integrations` page to -configure a new webhook. - -.. seealso:: - - :doc:`/guides/setup/git-repo-manual` - Once you have imported your git project, use this guide to manually set up basic and additional *webhook* integration. - -.. note:: - The ``Admin`` page can be found at ``https://readthedocs.org/dashboard//edit/``. - You can access all of the project settings from the admin page sidebar. - - .. figure:: ../_static/images/first-steps/admin-panel.png - :figwidth: 400px - - -Building your documentation ---------------------------- - -Within a few seconds of completing the import process, -your code will automatically be fetched from your repository, -and the documentation will be built. -Check out our :doc:`/builds` page to learn more about how Read the Docs builds your docs, -and to troubleshoot any issues that arise. - -We require an additional configuration file to build your project. -This allows you to specifying special requirements for your build, -such as your version of Python or how you wish to install addition Python requirements. -You can configure these settings in a ``.readthedocs.yaml`` file. -See our :doc:`/config-file/index` docs for more details. - -.. note:: - - Using a configuration file :doc:`is required from September 2023 `. - -It is also important to note that the default version of Sphinx is ``v1.8.5``. -We recommend to set the version your project uses :doc:`explicitily with pinned dependencies `. - -Read the Docs will host multiple versions of your code. You can read more about -how to use this well on our :doc:`/versions` page. - -If you have any more trouble, don't hesitate to reach out to us. -The :doc:`/support` page has more information on getting in touch. diff --git a/docs/user/reference/git-integration.rst b/docs/user/reference/git-integration.rst index 42057e57c60..e3708288b6d 100644 --- a/docs/user/reference/git-integration.rst +++ b/docs/user/reference/git-integration.rst @@ -9,7 +9,7 @@ Connecting your account provides the following features: 🔁ī¸ List your projects Select a project to automatically import from all your Git repositories and organizations. - See: :doc:`/intro/import-guide`. + See: :doc:`/intro/add-project`. ⚙ī¸ Automatic configuration Have your Git repository automatically configured with your Read the Docs :term:`webhook`, diff --git a/docs/user/tutorials/index.rst b/docs/user/tutorials/index.rst index bc04a479b3c..d72b5b03c37 100644 --- a/docs/user/tutorials/index.rst +++ b/docs/user/tutorials/index.rst @@ -19,7 +19,7 @@ Tutorials This is especially popular because of its default of using Markdown. This tool is well-supported on our platform and that's why we have a tutorial. -⏊ī¸ :doc:`/intro/import-guide` +⏊ī¸ :doc:`/intro/add-project` If you already wrote your documentation, this guide will help you get started at the most natural point: importing an existing documentation project. @@ -39,6 +39,6 @@ Tutorials /tutorial/index /intro/getting-started-with-sphinx /intro/getting-started-with-mkdocs - /intro/import-guide + /intro/add-project /config-file/index /examples