Complete Migration from RDT to Docusaurus (IntersectMBO#6227)

- Delete the contents of doc/read-the-docs-site, only keeping the README with a migration notice.
- Move docusaurus folder into doc folder.
- Update the GH workflows for publishing the haddock site and docusaurus site.
- Delete GH web hook and update redirects on RTD site.
- Remove mentions of read-the-docs and combined-haddock from nix code
- Update release process, mentioning how to publish Docusaurus and the Haddock site
- Update links in Docusaurus mentioning the new haddock site

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -9,7 +9,7 @@ body:
     attributes:
       value: |
         Thanks for taking the time to fill out this bug report.
-        Please check the existing issues, [Plutus Docs](https://plutus.readthedocs.io/en/latest/) and [Cardano Stack Exchange](https://cardano.stackexchange.com/) before raising.
+        Please check the existing issues, [Plutus Docs](https://intersectmbo.github.io/plutus/docs) and [Cardano Stack Exchange](https://cardano.stackexchange.com/) before raising.
   - type: textarea
     id: summary
     attributes:

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -8,7 +8,7 @@ body:
     attributes:
       value: |
         Thanks for taking the time to fill out this feature request.
-        Please check the existing issues and [Plutus Docs](https://plutus.readthedocs.io/en/latest/) before raising.
+        Please check the existing issues and [Plutus Docs](https://intersectmbo.github.io/plutus/docs) before raising.
   - type: textarea
     id: description
     attributes:

.github/workflows/docusaurus-site.yml

@@ -0,0 +1,31 @@
+# This workflow builds and publishes the Docusaurus site to:
+# https://intersectmbo.github.io/plutus/docs
+
+name: "🦕 Docusaurus Site" 
+
+on:
+  workflow_dispatch:
+
+jobs:
+  publish:
+    name: Publish 
+    runs-on: [self-hosted, plutus-shared]
+    permissions:
+      contents: write
+    environment:
+      name: github-pages
+    steps:
+      - name: Checkout
+        uses: actions/checkout@main
+
+      - name: Build Site 
+        working-directory: doc/docusaurus
+        run: nix develop --command bash -c 'yarn && yarn build'
+
+      - name: Deploy Site 
+        uses: JamesIves/github-pages-deploy-action@v4.6.1
+        with:
+          folder: doc/docusaurus/build
+          target-folder: docs
+          single-commit: true
+

.github/workflows/haddock-site.yml

@@ -0,0 +1,59 @@
+# This workflow builds and publishes the Haddock site to:
+# https://intersectmbo.github.io/plutus/haddock/$version
+# And optionally to:
+# https://intersectmbo.github.io/plutus/haddock/latest
+
+name: "📜 Haddock Site"
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: |
+          The release version tag. For example if $version == "1.29.0.0" then the 
+          current contents of the branch tagged "1.29.0.0" will be deployed to: 
+          https://intersectmbo.github.io/plutus/haddock/$version
+        required: true
+        type: string
+
+      latest: 
+        description: |
+          If true, then the $version branch will also be deployed to:
+          https://intersectmbo.github.io/plutus/haddock/latest.
+          You want to leave this to true unless you are deploying old versions.
+        type: boolean
+        required: true 
+        default: true
+
+jobs:
+  publish:
+    name: Publish
+    runs-on: [self-hosted, plutus-shared]
+    permissions:
+      contents: write
+    environment:
+      name: github-pages
+    steps:
+      - name: Checkout
+        uses: actions/checkout@main
+        with:
+          ref: ${{ inputs.version }}
+
+      - name: Build Site
+        run: | 
+          nix develop --command ./scripts/combined-haddock.sh _haddock all
+
+      - name: Deploy Site
+        uses: JamesIves/github-pages-deploy-action@v4.6.1
+        with:
+          folder: _haddock
+          target-folder: haddock/${{ inputs.version }}
+          single-commit: true
+
+      - name: Deploy Site (latest)
+        if: ${{ inputs.latest == true }}
+        uses: JamesIves/github-pages-deploy-action@v4.6.1
+        with:
+          folder: _haddock
+          target-folder: haddock/latest
+          single-commit: true

CONTRIBUTING.adoc

@@ -415,7 +415,7 @@ The amount of time it's worth spending doing this is probably much more than you
 
 PRs should target `master` unless there is a very good reason not to.
 The only PRs to release branches should be backport PRs which should consist only of cherry-picks of commits from master (and any fixups that are needed).
-For more details, see link:./doc/read-the-docs-site/RELEASE{outfilesuffix}[Plutus Release Process].
+For more details, see link:./RELEASE{outfilesuffix}[Plutus Release Process].
 
 ==== What changes to include, and pull request sizes
 
@@ -605,12 +605,10 @@ If your PR contains a dozen drive-by refactorings, it's unlikely to be merged as
 
 === Continuous integration
 
-We have a few sources of CI checks at the moment:
+We have two sources of CI checks at the moment:
 
 - Hydra
-- ReadTheDocs
 - Github Actions
-- Buildkite
 
 The CI will report statuses on your PRs with links to the logs in case of failure.
 Pull requests cannot be merged without at least the Hydra CI check being green.
@@ -632,16 +630,11 @@ These will be automatically retried, but if you're in a hurry Michael has permis
 Nondeterministic failures are very annoying.
 Michael also has permissions to restart failed builds.
 
-==== ReadTheDocs
+==== Docusaurus
 
-The documentation site is built on ReadTheDocs.
-It will build a preview for each PR which is linked from the PR status.
-It's useful to take a look if you're changing any of the documentation.
+The documentation site is built with Docusaurus.
 
-Enter the development shell using `nix develop`.
-If you get a segfault, run `GC_DONT_GC=1 nix develop` instead.
-
-Then you can run `serve-docs` to host a local instance at http://0.0.0.0:8002 (Haddock is at http://0.0.0.0:8002/haddock).
+Refer to the [README.md](doc/docusaurus/README.md) for more information.
 
 ==== Github Actions
 

README.adoc

@@ -42,9 +42,11 @@ After setting it up you should just be able to depend on the `plutus` packages a
 
 === User documentation
 
-The main documentation is located https://intersectmbo.github.io/plutus/master/docs/[here].
+The main documentation is located https://intersectmbo.github.io/plutus/docs/[here].
 
-The latest documentation for the metatheory can be found https://ci.iog.io/job/input-output-hk-plutus/master/x86_64-linux.packages.plutus-metatheory-site/latest/download/1[here].
+The haddock documentation is located https://intersectmbo.github.io/plutus/haddock/[here].
+
+The documentation for the metatheory can be found https://intersectmbo.github.io/plutus/metatheory/[here].
 
 === Talks
 

cabal.project

@@ -18,8 +18,7 @@ index-state:
   -- Bump this if you need newer packages from CHaP
   , cardano-haskell-packages 2024-01-16T11:00:00Z
 
-packages: doc/read-the-docs-site
-          plutus-benchmark
+packages: plutus-benchmark
           plutus-conformance
           plutus-core
           plutus-ledger-api

docusaurus/README.md → doc/docusaurus/README.md

@@ -26,16 +26,6 @@ This command generates static content into the `build` directory and can be serv
 
 ### Deployment
 
-Using SSH:
+Go to the [docusaurus-site.yml](https://github.com/IntersectMBO/plutus/actions/workflows/docusaurus-site.yml) workflow and click `Run workflow` on the right.
 
-```
-$ USE_SSH=true yarn deploy
-```
-
-Not using SSH:
-
-```
-$ GIT_USER=<Your GitHub username> yarn deploy
-```
-
-If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
+This will build and publish the website to the `gh-pages` branch at https://intersectmbo.github.io/plutus/docs.

docusaurus/docs/getting-started-plutus-tx.md → doc/docusaurus/docs/getting-started-plutus-tx.md

@@ -28,4 +28,4 @@ Use `cardano-cli` to deploy your script.
 
 Use an off-chain framework, such as [cardano-transaction-lib](https://github.com/Plutonomicon/cardano-transaction-lib) and [lucid](https://github.com/spacebudz/lucid), to interact with your script. 
 
-All these are based on the [Cardano API](https://github.com/IntersectMBO/cardano-node/tree/master/cardano-api), a low-level API that provides the capability to do the off-chain work with a local running node.
+All these are based on the [Cardano API](https://github.com/IntersectMBO/cardano-api), a low-level API that provides the capability to do the off-chain work with a local running node.

docusaurus/docs/simple-example/off-chain-code.md → doc/docusaurus/docs/simple-example/off-chain-code.md

@@ -8,10 +8,10 @@ Since the main purpose of this example is to introduce Plutus Tx and Plutus Core
 
 In addition to the on-chain code, one typically needs the accompanying off-chain code and services to perform tasks like building transactions, submitting transactions, deploying smart contracts, querying for available UTXOs on the chain, etc.
 
-<!-- Correct the inaccurate info below about Plutus Apps -->
+<!-- TODO Correct the inaccurate info below about Plutus Apps -->
 
 A full suite of solutions is [in development](https://plutus-apps.readthedocs.io/en/latest/plutus/explanations/plutus-tools-component-descriptions.html).
 See the [plutus-apps](https://github.com/IntersectMBO/plutus-apps) repo and its accompanying [Plutus tools SDK user guide](https://plutus-apps.readthedocs.io/en/latest/) for more details.
 
 Some other alternatives include [cardano-transaction-lib](https://github.com/Plutonomicon/cardano-transaction-lib) and [lucid](https://github.com/spacebudz/lucid). 
-All these are based on the [Cardano API](https://github.com/IntersectMBO/cardano-node/tree/master/cardano-api), a low-level API that provides the capability to do the off-chain work with a local running node.
+All these are based on the [Cardano API](https://github.com/IntersectMBO/cardano-api), a low-level API that provides the capability to do the off-chain work with a local running node.

docusaurus/docs/simple-example/plutus-tx-code.md → doc/docusaurus/docs/simple-example/plutus-tx-code.md

@@ -7,7 +7,7 @@ sidebar_position: 20
 Recall that Plutus Tx is a subset of Haskell. 
 It is the source language one uses to write Plutus validators. 
 A Plutus Tx program is compiled into Plutus Core, which is interpreted on-chain. 
-The full Plutus Tx code for the auction smart contract can be found at [AuctionValidator.hs](https://github.com/IntersectMBO/plutus/blob/master/doc/read-the-docs-site/tutorials/AuctionValidator.hs).
+The full Plutus Tx code for the auction smart contract can be found at [AuctionValidator.hs](https://github.com/IntersectMBO/plutus-tx-template/blob/main/app/AuctionValidator.hs).
 
 <!-- will need to update the link and file location for the new docs platform implementation -->
 

docusaurus/docusaurus.config.ts → doc/docusaurus/docusaurus.config.ts

@@ -8,10 +8,10 @@ const config: Config = {
   favicon: "img/favicon.ico",
 
   // Set the production url of your site here
-  url: "https://plutus.readthedocs.io",
+  url: "https://intersectmbo.github.io",
   // Set the /<baseUrl>/ pathname under which your site is served
   // For GitHub pages deployment, it is often '/<projectName>/'
-  baseUrl: "/plutus/master/docs/",
+  baseUrl: "/plutus/docs/",
 
   // GitHub pages deployment config.
   // If you aren't using GitHub pages, you don't need these.