Docs: Docusaurus tutorial

docs/user/index.rst

@@ -6,7 +6,9 @@ Read the Docs: documentation simplified
    :hidden:
    :caption: Getting started
 
-   Tutorial </tutorial/index>
+   Sphinx tutorial </tutorial/index>
+   Docusaurus tutorial </tutorial/docusaurus>
+   Quickstart with an AI agent </tutorial/docusaurus-with-ai>
    /intro/add-project
    /intro/doctools
    /examples
@@ -165,11 +167,17 @@ We have a few places for you to get started:
 
 .. descriptions here are active
 
+:doc:`/tutorial/docusaurus-with-ai`
+  Use an AI coding agent (Claude Code, Cursor, etc.) to scaffold and host your docs.
+
+:doc:`/tutorial/docusaurus`
+  Follow the Read the Docs tutorial for Docusaurus.
+
 :doc:`/tutorial/index`
-  Follow the Read the Docs tutorial.
+  Follow the Read the Docs tutorial for Sphinx.
 
 :doc:`/intro/doctools`
-  Quick start for MkDocs and Docusaurus.
+  Quick start for MkDocs and other tools.
 
 :doc:`/examples`
   Start your journey with an example project to learn how to use Read the Docs.

docs/user/tutorial/docusaurus-with-ai.rst

@@ -0,0 +1,236 @@
+Read the Docs quickstart with an AI coding agent
+================================================
+
+This is the AI-assisted version of the :doc:`Docusaurus tutorial </tutorial/docusaurus>`.
+Instead of clicking through templates and dashboards step by step,
+you delegate as much of the work as possible to an AI coding agent
+(`Claude Code <https://claude.com/claude-code>`_, `Cursor <https://cursor.sh/>`_,
+`GitHub Copilot CLI <https://docs.github.com/en/copilot/github-copilot-in-the-cli>`_,
+or any other tool that can run shell commands and call HTTP APIs).
+
+By the end of this quickstart, you will have:
+
+- A `Docusaurus`_ documentation site scaffolded from scratch,
+- A public GitHub repository for it,
+- A Read the Docs project hosting the built documentation, and
+- Pull request builds enabled.
+
+.. _Docusaurus: https://docusaurus.io/
+
+.. note::
+
+   The AI agent does the work that can be automated:
+   scaffolding the site, writing the ``.readthedocs.yaml`` configuration,
+   creating the GitHub repository, creating the Read the Docs project
+   through the :doc:`API </api/v3>`, and triggering the first build.
+
+   A few steps still require you in a browser:
+   creating a Read the Docs account (if you don't have one),
+   installing the Read the Docs GitHub App,
+   and generating an API token.
+   The agent will tell you when to do each, then resume.
+
+Prerequisites
+-------------
+
+Before you start, make sure you have:
+
+- An AI coding agent installed locally (Claude Code, Cursor, Copilot CLI, etc.) that can read and write files and run shell commands in your project folder.
+- The `GitHub CLI <https://cli.github.com/>`_ (``gh``) installed and authenticated (``gh auth login``).
+- `Node.js <https://nodejs.org/>`_ 20 or newer for local testing (optional, but recommended).
+- A `GitHub account <https://github.com/signup>`_.
+
+You do **not** need a Read the Docs account yet — the agent will help you create one if needed.
+
+Step 1: Scaffold the project
+----------------------------
+
+Create an empty folder, open your AI agent inside it, and send this prompt:
+
+.. code-block:: text
+
+   Set up a Docusaurus documentation site in this folder, ready to host on Read the Docs.
+
+   1. Scaffold a new Docusaurus site into a `docs/` subdirectory using
+      `npx create-docusaurus@latest docs classic`.
+   2. Create a `.readthedocs.yaml` at the repository root that builds the site
+      with Node.js 22 using `build.jobs`. The install step should run
+      `npm install` inside `docs/`. The HTML build step should run `npm run build`
+      inside `docs/`, then copy `docs/build/` into `$READTHEDOCS_OUTPUT/html/`.
+   3. Add a `.gitignore` covering `node_modules/` and `docs/build/`.
+   4. Initialize a git repository, commit everything on `main`, then create a
+      public GitHub repository named `docusaurus-tutorial` with `gh repo create`
+      and push.
+
+The agent runs the scaffold, writes the configuration file, and pushes the repository.
+When it finishes, you will have a working Docusaurus project on GitHub and a
+``.readthedocs.yaml`` like this:
+
+.. code-block:: yaml
+   :caption: .readthedocs.yaml
+
+   version: 2
+
+   build:
+     os: "ubuntu-22.04"
+     tools:
+       nodejs: "22"
+     jobs:
+       install:
+         - cd docs/ && npm install
+       build:
+         html:
+           - cd docs/ && npm run build
+           - mkdir --parents $READTHEDOCS_OUTPUT/html/
+           - cp --recursive docs/build/* $READTHEDOCS_OUTPUT/html/
+
+.. tip::
+
+   Read the agent's plan before approving destructive commands.
+   If you already have files in the folder, ask it to scaffold into a subfolder instead.
+
+Step 2: Let the agent onboard you to Read the Docs
+--------------------------------------------------
+
+Now send this prompt to the same agent:
+
+.. code-block:: text
+
+   Help me get this project hosted on Read the Docs.
+
+   First, ask me whether I already have a Read the Docs account.
+
+   - If I don't, walk me through:
+       a. Signing up at https://app.readthedocs.org/accounts/signup/ with GitHub.
+       b. Installing the Read the Docs Community GitHub App at
+          https://github.com/apps/read-the-docs-community for THIS repository only.
+   - If I do, confirm the GitHub App is installed for this repository.
+     If not, walk me through installing it.
+
+   Then ask me to create a Read the Docs API token at
+   https://app.readthedocs.org/accounts/tokens/create/ and paste it.
+   Use that token with the Read the Docs API v3
+   (https://docs.readthedocs.com/platform/stable/api/v3.html) to:
+
+   1. POST /api/v3/projects/ to create the project, using the GitHub repository
+      URL from `gh repo view --json url`. Prefix the project name with my
+      GitHub username, e.g. `{username}-docusaurus-tutorial`.
+   2. PATCH /api/v3/projects/{slug}/ to enable pull request builds
+      (`external_builds_enabled: true`) and to set a short description and
+      a couple of tags like `docusaurus, documentation`.
+   3. POST /api/v3/projects/{slug}/versions/latest/builds/ to trigger the
+      first build, then poll the build endpoint until it finishes and report
+      the result.
+
+   When the build succeeds, give me the published documentation URL.
+   Treat the token as a secret — do not commit it or print it back to me.
+
+The agent will pause and ask whether you already have an account.
+Answer honestly; if you don't, follow the links it shares,
+come back, and confirm when you're done so it can continue.
+
+.. important::
+
+   Your API token is the equivalent of your password for the Read the Docs API.
+   Paste it only into a local AI agent you trust. Tokens can be revoked any
+   time at https://app.readthedocs.org/accounts/tokens/ if you suspect a leak.
+
+What happens during this step
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Behind the scenes, the agent calls these endpoints
+(all documented under :doc:`API v3 </api/v3>`):
+
+- ``POST /api/v3/projects/`` — creates the project linked to your GitHub repository.
+- ``PATCH /api/v3/projects/{slug}/`` — turns on pull request builds and sets the description and tags.
+- ``POST /api/v3/projects/{slug}/versions/latest/builds/`` — triggers the first build.
+- ``GET /api/v3/projects/{slug}/builds/{id}/`` — polls until the build finishes.
+
+If anything fails (for example the GitHub App is not installed,
+or the repository is not visible to your Read the Docs account),
+the API returns an explanatory error and the agent surfaces it back to you.
+
+Step 3: Verify the result
+-------------------------
+
+When the build finishes, open the documentation URL the agent gave you.
+You should see a default Docusaurus site served from Read the Docs.
+
+To confirm pull request builds work, ask the agent:
+
+.. code-block:: text
+
+   Create a new branch, change a heading in `docs/docs/intro.md`, push it,
+   and open a pull request. Then wait for the Read the Docs check and link me
+   to the preview build.
+
+When the check turns green, you can :doc:`review the preview </pull-requests>`
+the same way readers will see it.
+
+Step 4: Configure features that need the dashboard
+--------------------------------------------------
+
+A handful of Read the Docs features are not yet available through the API.
+Ask your agent to open the right pages for you:
+
+.. code-block:: text
+
+   List the Read the Docs features I should enable from the dashboard, with
+   the exact URL for each, for project `{slug}`:
+
+   - Visual diff
+   - Link previews
+   - Automation rule to build only when files under `docs/` or `.readthedocs.yaml` change
+   - Email notifications for failed builds
+
+For each one, the agent should point you at a URL like
+``https://app.readthedocs.org/dashboard/{slug}/addons/`` or
+``https://app.readthedocs.org/dashboard/{slug}/rules/``.
+Click through the link, flip the toggle or save the form, and you're done.
+
+See the related documentation pages if you want background:
+:doc:`Visual diff </visual-diff>`, :doc:`Link previews </link-previews>`,
+:doc:`Automation rules </automation-rules>`,
+:doc:`Build notifications </build-notifications>`.
+
+Step 5: Use the agent for ongoing maintenance
+---------------------------------------------
+
+Once your project is on Read the Docs, the agent is still useful.
+Some prompts to keep handy:
+
+Debug a failed build
+   .. code-block:: text
+
+      My latest Read the Docs build failed. Fetch the build log via
+      `GET /api/v3/projects/{slug}/builds/{id}/` and tell me what to fix.
+
+Change the Node.js version
+   .. code-block:: text
+
+      Update `.readthedocs.yaml` to use Node.js 24, commit, and push.
+      Watch the next build and report whether it succeeded.
+
+Add a new documentation version
+   .. code-block:: text
+
+      Create a `1.0.x` branch from `main` on GitHub. Then use the Read the Docs
+      API to activate the `1.0.x` version and set `stable` as the default version
+      for the project.
+
+Where to go from here
+---------------------
+
+You've used an AI agent to scaffold a Docusaurus site, host it on Read the Docs,
+and wire up pull request builds — without clicking through most of the dashboard.
+
+To keep going:
+
+- Compare what the agent did with the manual :doc:`Docusaurus tutorial </tutorial/docusaurus>`
+  so you understand the pieces it touched.
+- Read the :doc:`API v3 reference </api/v3>` to see what else the agent can automate.
+- Skim :doc:`/intro/doctools` if you want to try the same pattern with a different
+  documentation generator.
+- Browse :doc:`/guides/index` for deeper how-to guides on specific features.
+
+Happy documenting!