Reorganized Plutus user guide on the Docusaurus platform initial deployment

.github/workflows/haddock.yml → .github/workflows/publish-docs.yml

@@ -23,10 +23,20 @@ jobs:
           nix build .#combined-haddock
           mkdir dist
           cp -RL ./result/share/doc/* ./dist/
+      - name: Build Docusaurus Site
+        working-directory: docusaurus
+        run: |
+          yarn
+          yarn build
+      - name: Copy Docusaurus Site to Dist
+        run: |
+          mkdir dist/docs
+          cp -RL docusaurus/build/* ./dist/docs/
       - uses: JamesIves/github-pages-deploy-action@v4
         with:
           folder: dist
           target-folder: ${{ github.ref_name }}
-          # We publish our haddock, which is non-trivially big. 
+          # Publish Docusaurus and Haddock static builds to the same branch
+          # We publish our haddock, which is non-trivially big.
           # So keeping the whole history is expensive, and anyway we don't need it.
           single-commit: true

docusaurus/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docusaurus/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ 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.

docusaurus/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docusaurus/docs/adr/_category_.json

@@ -0,0 +1,8 @@
+{
+    "label": "Architectural decision records",
+    "position": 60,
+    "link": {
+      "type": "generated-index",
+      "description": "This section provides documentation of the Plutus team's important architectural decisions made to date along with the context and consequences."
+    }
+  }

docusaurus/docs/adr/adr-index.md

@@ -0,0 +1,25 @@
+---
+sidebar_position: 5
+---
+
+# Architectural decision records
+
+We document our architectural and design decisions for all of our components. 
+To do that, there is a practice called architectural decision records (ADR), that we can integrate into our workflow. 
+An ADR is a document that captures an important architectural decision made along with its context and consequences.
+
+The goals are:
+
+- Making decisions transparent to internal/external stakeholders and contributors
+- Getting feedback on decisions that we're about to make or have made
+- Providing external contributors with a framework to propose architectural changes
+- Providing a big picture of all major decisions that were made.
+
+The general process for creating an ADR is:
+
+1. Cloning the repository
+2. Creating a new file with the format:
+    `[<ADR_NUMBER\>-<TITLE>.md]` in the directory `[doc/adr]`
+3. Adding the ADR in the table of contents tree of the documentation
+4. Committing and pushing to the repository.
+

docusaurus/docs/adr/adr1.md

@@ -0,0 +1,124 @@
+---
+sidebar_position: 10
+---
+
+# ADR 1: Record architectural decisions
+
+Date: 2022-06-08
+
+## Authors
+
+[koslambrou](mailto:[email protected])
+
+## Status
+
+Accepted
+
+## Context
+
+We are in search for a means to document our architectural and design decisions for all of our components. 
+To do that, there is a practice called architectural decision records (ADR) that we can
+integrate into our workflow.
+
+This does not replace actual architecture documentation, but provides people who are contributing with:
+
+- the means to understand architectural and design decisions that were made
+- a framework for proposing changes to the current architecture.
+
+For each decision, it is important to consider the following factors:
+
+- what we have decided to do
+- why we have made this decision
+- what we expect the impact of this decision to be
+- what we have learned in the process.
+
+## Decision
+
+- We will use ADRs to document, propose, and discuss any important or significant architectural and design decisions.
+- The ADR format will follow the format described in the [Implications](#implications) section.
+- We will follow the convention of storing those ADRs as rST or Markdown formatted documents stored under the [docs/adr] directory, as exemplified in Nat Pryce's [adr-tools](https://github.com/npryce/adr-tools). 
+This does not imply that we will be using [adr-tools] itself, as we might diverge from the proposed structure.
+- We will keep rejected ADRs.
+- We will strive, if possible, to create an ADR as early as possible in relation to the actual implementation.
+
+## Implications
+
+ADRs should be written using the template described in the [ADR template](#adr-template) which comes from Chapter 6.5.2 (*A Template for Documenting Architectural Decisions*) of *Documenting Software Architectures: Views and Beyond (2nd Edition)*.
+
+However, the mandatory sections are *Title*, *Status*, *Issue/Context*, *Decision*, *Implications/Consequences*. The rest are optional.
+
+Another good reference is the article [Architecture Decision Records](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) by Michael Nygard (Nov. 15, 2011).
+
+## ADR template
+
+What follows is the ADR format (adapted from the book).
+
+### Title
+
+These documents have names that are short noun phrases.
+
+For example, 'ADR 1: Deployment on Ruby on Rails 3.0.10' or 'ADR 9: LDAP for Multitenant Integration.'
+
+### Authors
+
+List each author’s name and email.
+
+### Status
+
+State the status of the decision, such as 'draft' if the decision is still being written, as 'proposed' if the project stakeholders haven’t agreed with it yet, or 'accepted' once it is agreed. If a later ADR changes or reverses a decision, it may be marked as 'deprecated' or 'superseded' with a reference to its replacement. (This is not the status of implementing the decision.)
+
+### Issue (or context)
+
+This section describes the architectural design issue being addressed. This description should leave no questions as to why this issue needs to be addressed now. The language in this section is value-neutral. It is simply describing facts.
+
+### Decision
+
+Clearly state the solution chosen. It is the selection of one of the positions that the architect could have taken. It is stated in full sentences, with active voice. 'We will …'
+
+### Tags
+
+Add one or more tags to the decision. Useful for organizing the set of decision.
+
+### Assumptions
+
+Clearly describe the underlying assumptions in the environment in which a decision is being made. These could be cost, schedule, technology, and so on. Note that constraints in the environment (such as a list of accepted technology standards, an enterprise architecture, or commonly employed patterns) may limit the set of alternatives considered.
+
+### Argument
+
+Outline why a position was selected. This is probably as important as the decision itself. The argument for a decision can include items such as implementation cost, total cost of ownership, time to market, and availability of required development resources.
+
+### Alternatives
+
+List alternatives (that is, options or positions) considered.
+
+Explain alternatives with sufficient detail to judge their suitability; refer to external documentation if necessary. Only viable positions should be described here. While you don’t need an exhaustive list, you also don’t want to hear the question 'Did you think about… ?' during a final review, which might lead to a loss of credibility and a questioning of other architectural decisions. Listing alternatives espoused by others also helps them know their opinions were heard. Finally, listing alternatives helps the architect make the right decision, because listing alternatives cannot be done unless those alternatives were given due consideration.
+
+### Implications (or consequences)
+
+Describe the decision’s implications. For example, it may: 
+
+* Introduce a need to make other decisions
+* Create new requirements
+* Modify existing requirements
+* Pose additional constraints to the environment
+* Require renegotiation of scope
+* Require renegotiation of the schedule with the customers
+* Require additional training for the staff.
+
+Clearly understanding and stating the implications of the decisions has been a very effective tool in gaining buy-in. All consequences should be listed here, not just the 'positive' ones. A particular decision may have positive, negative, and neutral consequences, but all of them affect the team and project in the future.
+
+### Related decisions
+
+List decisions related to this one. Useful relations among decisions include causality (which decisions caused other ones), structure (showing decisions’ parents or children, corresponding to architecture elements at higher or lower levels), or temporality (which decisions came before or after others).
+
+### Related requirements
+
+Map decisions to objectives or requirements, to show accountability. Each architecture decision is assessed as to its contribution to each major objective. We can then assess how well the objective is met across all decisions, as part of an overall architecture evaluation.
+
+### Affected artifacts
+
+List the architecture elements and/or relations affected by this decision. You might also list the effects on other design or scope decisions, pointing to the documents where those decisions are described. You might also include external artifacts upstream and downstream of the architecture, as well as management artifacts such as budgets and schedules.
+
+### Notes
+
+Capture notes and issues that are discussed during the decision process. They can be links to a external document, a PR, a Github issue, etc.