Skip to content

Commit

Permalink
Reorganized Plutus user guide on the Docusaurus platform initial depl…
Browse files Browse the repository at this point in the history
…oyment (#6177)

* Initial Docusaurus Setup

* uploaded docs files and images

* added code files and images

* cleaned up mermaid diagrams for platform page

* committed yarn.lock file

* Add markdown link styling

* Update Plutus styling and add GA plugin

* updating yarn.lock file

* CSV Rendering component

* adding cost model parameters page that imports CSV files

* Fix gradient overflow on tables for dark mode

* changing title to Plutus user guide

* Update favicon and social card assets

* Remove landing page and set /docs to base path

* Update literal include roots

* Rename Haddock workflow and update to include Docusaurus build

* Update docusaurus/README.md

Co-authored-by: olgahryniuk <[email protected]>

* Update docusaurus/docs/adr/adr-index.md

Co-authored-by: olgahryniuk <[email protected]>

* Update docusaurus/docs/adr/adr-index.md

Co-authored-by: olgahryniuk <[email protected]>

* Update docusaurus/docs/adr/adr-index.md

Co-authored-by: olgahryniuk <[email protected]>

* Update docusaurus/docs/adr/adr1.md

Co-authored-by: olgahryniuk <[email protected]>

* Update docusaurus/docs/adr/adr2.md

Co-authored-by: olgahryniuk <[email protected]>

* Update docusaurus/docs/essential-concepts/language-versions.md

Co-authored-by: olgahryniuk <[email protected]>

* Update docusaurus/docs/essential-concepts/language-versions.md

Co-authored-by: olgahryniuk <[email protected]>

* Update docusaurus/docs/essential-concepts/language-versions.md

Co-authored-by: olgahryniuk <[email protected]>

* Update docusaurus/docs/essential-concepts/language-versions.md

Co-authored-by: olgahryniuk <[email protected]>

* Update docusaurus/docs/adr/adr1.md

Co-authored-by: olgahryniuk <[email protected]>

* Update docusaurus/docs/adr/adr1.md

Co-authored-by: olgahryniuk <[email protected]>

* Update docusaurus/docs/adr/adr1.md

Co-authored-by: olgahryniuk <[email protected]>

* Update docusaurus/docs/adr/adr1.md

Co-authored-by: olgahryniuk <[email protected]>

* Update docusaurus/docs/adr/adr1.md

Co-authored-by: olgahryniuk <[email protected]>

* Update docusaurus/docs/adr/adr1.md

Co-authored-by: olgahryniuk <[email protected]>

* Update docusaurus/docs/adr/adr1.md

Co-authored-by: olgahryniuk <[email protected]>

* Update docusaurus/docs/adr/adr1.md

Co-authored-by: olgahryniuk <[email protected]>

* Update docusaurus/docs/adr/adr1.md

Co-authored-by: olgahryniuk <[email protected]>

* Update docusaurus/docs/adr/adr1.md

Co-authored-by: olgahryniuk <[email protected]>

* Update docusaurus/docs/adr/adr1.md

Co-authored-by: olgahryniuk <[email protected]>

* Update docusaurus/docs/adr/adr1.md

Co-authored-by: olgahryniuk <[email protected]>

* committing after running pre-commit run --all-files command to fix build errors

---------

Co-authored-by: ianhanssoniohk <[email protected]>
Co-authored-by: olgahryniuk <[email protected]>
  • Loading branch information
3 people authored Jun 5, 2024
1 parent a2c6bc0 commit f1f2e9f
Show file tree
Hide file tree
Showing 78 changed files with 17,771 additions and 1 deletion.
Original file line number Diff line number Diff line change
Expand Up @@ -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
20 changes: 20 additions & 0 deletions docusaurus/.gitignore
Original file line number Diff line number Diff line change
@@ -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*
41 changes: 41 additions & 0 deletions docusaurus/README.md
Original file line number Diff line number Diff line change
@@ -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.
3 changes: 3 additions & 0 deletions docusaurus/babel.config.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
module.exports = {
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
};
8 changes: 8 additions & 0 deletions docusaurus/docs/adr/_category_.json
Original file line number Diff line number Diff line change
@@ -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."
}
}
25 changes: 25 additions & 0 deletions docusaurus/docs/adr/adr-index.md
Original file line number Diff line number Diff line change
@@ -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.

124 changes: 124 additions & 0 deletions docusaurus/docs/adr/adr1.md
Original file line number Diff line number Diff line change
@@ -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.
Loading

1 comment on commit f1f2e9f

@github-actions
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Performance Alert ⚠️

Possible performance regression was detected for benchmark 'Plutus Benchmarks'.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 1.05.

Benchmark suite Current: f1f2e9f Previous: a2c6bc0 Ratio
validation-decode-escrow-redeem_1-2 333.1 μs 310.6 μs 1.07

This comment was automatically generated by workflow using github-action-benchmark.

CC: @input-output-hk/plutus-core

Please sign in to comment.