From 2bf10ec497b9aca4a16f0d882ba9f7d5d01402a2 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Mon, 9 Dec 2024 16:20:01 -0800 Subject: [PATCH 1/3] Add authentication documentation This adds two pages: * A intro reference page on authentication methods * A guide on managing maintainers for Community These are just basic places to start on this content. I wasn't 100% sure the best way to structure the Authencation methods page, so definitely would like feedback on that one. --- docs/user/guides/access/index.rst | 4 ++ .../guides/manage-read-the-docs-teams.rst | 2 - docs/user/guides/managing-maintainers.rst | 41 +++++++++++++++++++ docs/user/index.rst | 1 + docs/user/intro/accounts.rst | 39 ++++++++++++++++++ 5 files changed, 85 insertions(+), 2 deletions(-) create mode 100644 docs/user/guides/managing-maintainers.rst create mode 100644 docs/user/intro/accounts.rst diff --git a/docs/user/guides/access/index.rst b/docs/user/guides/access/index.rst index 8dd19fad8d9..61a4fc5eeea 100644 --- a/docs/user/guides/access/index.rst +++ b/docs/user/guides/access/index.rst @@ -27,6 +27,9 @@ How-to guides: security and access a :ref:`private Git repository ` or a :ref:`private repository manager `. +⏩️ :doc:`Manage Maintainers ` + Learn how to manage maintainers for your projects on |org_brand|. + .. toctree:: :maxdepth: 1 :hidden: @@ -38,3 +41,4 @@ How-to guides: security and access Manually importing private repositories Using private Git submodules Installing private python packages + Manage Maintainers diff --git a/docs/user/guides/manage-read-the-docs-teams.rst b/docs/user/guides/manage-read-the-docs-teams.rst index c9675f4ea85..58bdf426f99 100644 --- a/docs/user/guides/manage-read-the-docs-teams.rst +++ b/docs/user/guides/manage-read-the-docs-teams.rst @@ -1,5 +1,3 @@ -.. TODO: We should documentation how community team management works - How to manage Read the Docs teams ================================= diff --git a/docs/user/guides/managing-maintainers.rst b/docs/user/guides/managing-maintainers.rst new file mode 100644 index 00000000000..8b92310e839 --- /dev/null +++ b/docs/user/guides/managing-maintainers.rst @@ -0,0 +1,41 @@ +How to manage maintainers for your project +========================================== + +|org_brand| allows you to manage maintainers for your projects. +Maintainers have admin access to the project, so be careful when adding them. + +When you add a maintainer to your project, +they will be invited to join the project as a maintainer. +They will receive an email notification with a link to accept the invitation, +and won't have access to the project until they accept the invitation. + +Adding a maintainer +------------------- + +Adding a maintainer gives them admin access to your project. + +Follow these steps: + +* Navigate to the :guilabel:`Settings` tab of your project. +* Click on the :guilabel:`Setup > Maintainers` tab. +* Click the :guilabel:`Add Maintainer` button. +* Fill out the form with the new maintainer's username or email address. +* Click :guilabel:`Invite`. + +Removing a maintainer +--------------------- + +Removing a maintainer revokes their admin access to your project. + +Follow these steps: + +* Navigate to the :guilabel:`Settings` tab of your project. +* Click on the :guilabel:`Setup > Maintainers` tab. +* Find the maintainer you want to remove in the list. +* Click the :guilabel:`Remove` button next to their name. +* Confirm the removal in the dialog that appears. + +.. seealso:: + + :doc:`/guides/manage-read-the-docs-teams` + Learn how to manage teams within an organization on |com_brand|. diff --git a/docs/user/index.rst b/docs/user/index.rst index 6855676b30b..bee722c90bf 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -14,6 +14,7 @@ Read the Docs: documentation simplified /intro/markdoc /intro/add-project /examples + /intro/accounts .. toctree:: :maxdepth: 2 diff --git a/docs/user/intro/accounts.rst b/docs/user/intro/accounts.rst new file mode 100644 index 00000000000..79b5489222e --- /dev/null +++ b/docs/user/intro/accounts.rst @@ -0,0 +1,39 @@ +Account authentication methods +============================== + +Read the Docs supports several authentication methods for creating an account and logging in. +The method you choose depends on your preferences and the security requirements of your organization. + +These authentication methods are not mutually exclusive, +you can use multiple methods to access your account. + +Email and password +------------------ + +You can create an account on Read the Docs using your email address and a password. +This method works well for individual users and small teams, +but it limits the functionality available to you. + +VCS provider authentication +--------------------------- + +You can also create an account on Read the Docs using a VCS authentication provider: GitHub, GitLab, or Bitbucket. +This method is more secure and convenient than using an email and password, +and provides access to additional features like automatic repository syncing. + +.. seealso:: + + :doc:`/guides/connecting-git-account` + Learn how to connect your Read the Docs account with a Git provider. + +Two factor authentication +------------------------- + +Read the Docs supports Two Factor Authentication (2FA) for added security on all authentication methods. +If you have 2FA enabled on your account, you will be prompted to enter a code +when logging in. + +.. seealso:: + + :doc:`/guides/management/2fa` + Learn how to enable and disable Two Factor Authentication on your account. From 05d2674170a79652f5e0d204d334e072ae743e53 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Mon, 9 Dec 2024 16:30:41 -0800 Subject: [PATCH 2/3] Clean up copy a bit more --- docs/user/commercial/single-sign-on.rst | 4 +++ docs/user/intro/accounts.rst | 43 +++++++++++++++++++++++++ 2 files changed, 47 insertions(+) diff --git a/docs/user/commercial/single-sign-on.rst b/docs/user/commercial/single-sign-on.rst index 61898a924eb..7068e5aa2c6 100644 --- a/docs/user/commercial/single-sign-on.rst +++ b/docs/user/commercial/single-sign-on.rst @@ -31,6 +31,8 @@ including any two-factor authentication and additional Single Sign-on that they Learn how to configure this SSO method with our :doc:`/guides/setup-single-sign-on-github-gitlab-bitbucket`. +.. _sso_google_workspace: + SSO with Google Workspace ------------------------- @@ -42,6 +44,8 @@ permissions are managed by the :ref:`internal Read the Docs's teams Date: Wed, 11 Dec 2024 13:55:04 -0800 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Anthony --- docs/user/guides/access/index.rst | 2 +- docs/user/guides/managing-maintainers.rst | 10 ++++++---- docs/user/intro/accounts.rst | 14 +++++++------- 3 files changed, 14 insertions(+), 12 deletions(-) diff --git a/docs/user/guides/access/index.rst b/docs/user/guides/access/index.rst index 61a4fc5eeea..66befc631c1 100644 --- a/docs/user/guides/access/index.rst +++ b/docs/user/guides/access/index.rst @@ -41,4 +41,4 @@ How-to guides: security and access Manually importing private repositories Using private Git submodules Installing private python packages - Manage Maintainers + Manage maintainers diff --git a/docs/user/guides/managing-maintainers.rst b/docs/user/guides/managing-maintainers.rst index 8b92310e839..33a9d30b6c3 100644 --- a/docs/user/guides/managing-maintainers.rst +++ b/docs/user/guides/managing-maintainers.rst @@ -2,7 +2,9 @@ How to manage maintainers for your project ========================================== |org_brand| allows you to manage maintainers for your projects. -Maintainers have admin access to the project, so be careful when adding them. +Every project is configured with its own list of maintainers +who will all have admin privileges to the project, +so be careful when adding new maintainers. When you add a maintainer to your project, they will be invited to join the project as a maintainer. @@ -17,8 +19,8 @@ Adding a maintainer gives them admin access to your project. Follow these steps: * Navigate to the :guilabel:`Settings` tab of your project. -* Click on the :guilabel:`Setup > Maintainers` tab. -* Click the :guilabel:`Add Maintainer` button. +* Under :guilabel:`Setup`, click on the :guilabel:`Maintainers` tab. +* Click the :guilabel:`Add maintainer` button. * Fill out the form with the new maintainer's username or email address. * Click :guilabel:`Invite`. @@ -30,7 +32,7 @@ Removing a maintainer revokes their admin access to your project. Follow these steps: * Navigate to the :guilabel:`Settings` tab of your project. -* Click on the :guilabel:`Setup > Maintainers` tab. +* Under :guilabel:`Setup`, click on the :guilabel:`Maintainers` tab. * Find the maintainer you want to remove in the list. * Click the :guilabel:`Remove` button next to their name. * Confirm the removal in the dialog that appears. diff --git a/docs/user/intro/accounts.rst b/docs/user/intro/accounts.rst index 09753f2f24c..2509a99b4af 100644 --- a/docs/user/intro/accounts.rst +++ b/docs/user/intro/accounts.rst @@ -24,8 +24,8 @@ and provides access to additional features like automatic repository syncing. VCS provider authentication is required for the following features: * :doc:`/pull-requests` -* Automatic repository syncing for easy project import -* Automatic webhook creation on project import +* Automatic repository syncing for easy project creation +* Automatic webhook creation on project creation .. seealso:: @@ -61,22 +61,22 @@ This is only available on Enterprise plans, and requires custom integration to be enabled. SAML provides authentication, but not authorization. -This means that you can login to Read the Docs with this method, -but we aren't able to determine which projects you have access to automatically. +This means that users can login to Read the Docs with this method, +but we aren't able to determine which projects each user has access to automatically. .. seealso:: :ref:`sso_saml` Learn how to configure SAML authentication for your organization. -Two factor authentication +Two-factor authentication ------------------------- -Read the Docs supports Two Factor Authentication (2FA) for added security on all authentication methods. +Read the Docs supports two-factor authentication (2FA) for added security on all authentication methods. If you have 2FA enabled on your account, you will be prompted to enter a code when logging in. .. seealso:: :doc:`/guides/management/2fa` - Learn how to enable and disable Two Factor Authentication on your account. + Learn how to enable and disable two-factor authentication on your account.