Skip to content
This repository was archived by the owner on Feb 14, 2023. It is now read-only.

Commit d7da523

Browse files
alexandratranNicolasMassart
alexandratran
and
NicolasMassart
authored
Update entire doctools site content (#19)
* update entire doctools site content * fix link errors * more link corrections * some updates * some updates * more updates * fix links * markdown fixes * minor fix * fix path * minor edits * fix preview link * remove webhooks and an unused action * add advanced folder * minor fix * minor link fixes * fix a couple links * integrate reviewer feeddback Co-authored-by: Nicolas MASSART <[email protected]>
1 parent 79a8837 commit d7da523

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

41 files changed

+1685
-1244
lines changed

‎docs/howto/setup_new_doc_repos_images/about.png ‎docs/assets/images/about.png

File renamed without changes.

‎docs/howto/setup_new_doc_repos_images/create_from_template.png ‎docs/assets/images/create_from_template.png

File renamed without changes.

‎docs/howto/doctools_template_site_screenshot.png ‎docs/assets/images/doctools_template_site_screenshot.png

File renamed without changes.

‎docs/assets/images/github_pages_pr_preview.png

52.4 KB
Loading

‎docs/howto/setup_new_doc_repos_images/new_repos.png ‎docs/assets/images/new_repos.png

File renamed without changes.

‎docs/assets/images/rtd_pr_preview.png

254 KB
Loading

‎docs/changelog.md

-47
This file was deleted.

‎docs/contribute/fix-cicd-errors.md

+144
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
---
2+
description: How to fix PR errors
3+
---
4+
5+
# Fix CI/CD errors
6+
7+
Documentation sites that use the [old system](../overview/index.md#old-documentation-system) use
8+
[CircleCI](https://circleci.com/) to verify links, Markdown syntax, writing style, and more on all documentation changes.
9+
This section describes the four CI error types and how to fix them:
10+
11+
- [`build` errors](#build-errors)
12+
- [`linkchecker` errors](#linkchecker-errors)
13+
- [`markdownlint` errors](#markdownlint-errors)
14+
- [`vale` errors](#vale-errors)
15+
16+
Submitting or updating a PR automatically runs all CI checks, displaying a checklist at the bottom of the PR page.
17+
18+
Manually re-running a failed job on CircleCI requires a ConsenSys account.
19+
Anyone can run the CI checks on their local machine using the [local tests helper scripts](https://github.com/Consensys/doc.common/tree/master/build_tools/scripts).
20+
21+
!!! important
22+
23+
The [new documentation system](../overview/index.md#new-documentation-system) doesn't use
24+
CircleCI, but runs [Markdown](#markdownlint-errors) and [link](#linkchecker-errors) tests that you can view and fix
25+
in a similar way.
26+
27+
## `build` errors
28+
29+
The `build` job builds the documentation using MkDocs in `strict` mode, failing on both errors and warnings.
30+
Select the `build` **Details**, which takes you to the CircleCI site.
31+
Check the error message under **Run MkDocs** and make any required fixes.
32+
33+
The best way to reproduce the error is by running `mkdocs build -s` locally in a [virtual environment](../preview/old-system.md).
34+
35+
## `linkchecker` errors
36+
37+
The `linkchecker` job verifies links.
38+
Select the `linkchecker` **Details**, which takes you to the CircleCI site.
39+
The error message under **Run markdown link checker** displays all the broken links and their HTTP error codes.
40+
41+
HTTP error codes include:
42+
43+
- `404` - The page doesn't exist anymore.
44+
Update the link.
45+
- `4xx` - Refer to the [full list of HTTP codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes).
46+
- `5xx` - The web server is experiencing issues.
47+
You may re-run the job later.
48+
49+
!!! example
50+
51+
```bash
52+
FILE: ./docs/index.md
53+
[✓] Concepts/Overview.md → Status: 200
54+
[✖] https://consensys.net/quorum/developers → Status: 503
55+
[✖] https://consensys.net/quorum/contact-us → Status: 503
56+
57+
3 links checked.
58+
59+
ERROR: 2 dead links found!
60+
[✖] https://consensys.net/quorum/developers → Status: 503
61+
[✖] https://consensys.net/quorum/contact-us → Status: 503
62+
```
63+
64+
These errors mean the two links in `./docs/index.md` to the `consensys.net` site don't work because the server has issues.
65+
The `503` code means `Service Unavailable`.
66+
67+
## `markdownlint` errors
68+
69+
The `markdownlint` job verifies Markdown syntax.
70+
Select the `markdownlint` **Details**, which takes you to the CircleCI site.
71+
72+
The error message under **Run Markdownlint** displays Markdown errors that you must fix.
73+
These errors are also displayed in the `markdownlint.out` artifact.
74+
75+
The log under **Run Markdownlint info checks** displays warnings that you should be aware of but don't prevent the tests
76+
from passing.
77+
These warnings are also displayed in the `markdownlint_info.out` artifact.
78+
79+
!!! example
80+
81+
```bash
82+
`docs/Reference/Responsible-Disclosure.md:18:1 MD007/ul-indent Unordered list indentation [Expected: 2; Actual: 4]`
83+
```
84+
85+
This indicates that you have an error in the file `docs/Reference/Responsible-Disclosure.md` at line 18, character 1.
86+
The error code is [`MD007`](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md007---unordered-list-indentation)
87+
and the description message is `Unordered list indentation [Expected: 2; Actual: 4]` indicating that there are four
88+
spaces used to indent the line instead of the expected two.
89+
Fix by removing the two spaces.
90+
91+
Frequent Markdown errors in the ConsenSys documentation include:
92+
93+
- Not trimming end-of-line spaces.
94+
You can configure your editor to automatically fix this.
95+
- Not adding blank lines around lists, code blocks, or titles.
96+
- Using the wrong title level (for example, starting a page with `##` instead of `#`, or jumping from `#` to `###`).
97+
- Not defining the language on code blocks.
98+
- Manually incrementing ordered list elements.
99+
All ordered lists elements must start with `1.`; the numbers increment automatically in the rendered Markdown.
100+
- Using inconsistent unordered list markers.
101+
You can use `*` or `-` to start unordered list elements, but they must be the same everywhere on a page.
102+
- Using HTML when Markdown can do the job.
103+
Don't use HTML unless it's a matter of life and death!
104+
105+
View the [full list of `markdownlint` errors and fixes](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md).
106+
107+
## `vale` errors
108+
109+
The `vale` job verifies the documentation against basic writing guidelines configured in the
110+
[common submodule `vale` directory](https://github.com/ConsenSys/doc.common/tree/master/build_tools/vale).
111+
112+
Select the `vale` **Details**, which takes you to the CircleCI site.
113+
The error message under **Run Vale** displays writing errors that you must fix, and warnings that you should be aware of
114+
but don't prevent the tests from passing.
115+
116+
!!! example
117+
118+
```bash
119+
docs/Reference/CLI/CLI-Syntax.md
120+
1349:34 error Did you really mean Vale.Spelling
121+
'attestions'?
122+
1436:19 warning 'is used' may be passive write-good.Passive
123+
voice. Use active voice if you
124+
can.
125+
126+
✖ 1 error, 1 warnings and 0 suggestions in 1 file.
127+
128+
Exited with code exit status 1
129+
CircleCI received exit code 1
130+
```
131+
132+
This indicates that you have one error and one warning in the file `docs/Reference/CLI/CLI-Syntax.md`.
133+
134+
The error is a typo on the word `attestions` that should be `attestations`.
135+
The warning reminds you to use [active voice](https://docs.microsoft.com/en-us/style-guide/grammar/verbs#active-and-passive-voice)
136+
where possible.
137+
138+
If you're introducing a new product term not recognized by Vale:
139+
140+
1. [Make a documentation contribution](index.md) to the [`doc.common`](https://github.com/ConsenSys/doc.common)
141+
repository, adding the term to the Vale [`accept.txt`](https://github.com/ConsenSys/doc.common/blob/master/build_tools/vale/vale_styles/Vocab/Consensys/accept.txt)
142+
file.
143+
1. In the documentation repository in which you're making the original contribution,
144+
[update the submodule to the latest version](use-common-submodule.md#update-repositories-to-the-latest-submodule-version).

‎docs/contribute/index.md

+110
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
description: Documentation contribution guide
3+
---
4+
5+
# Contribute to the documentation
6+
7+
The following guidelines explain how to contribute to existing ConsenSys documentation repositories.
8+
You can also [create new documentation sites](../create/create-doc-site.md).
9+
10+
## Your first contribution
11+
12+
Start by choosing a [documentation repository](../overview/index.md#documentation-system-overview) and looking for
13+
issues that have a `Good First Issue` label.
14+
`Good First Issues` might require only a few lines of documentation, or have enough information for a newcomer to easily
15+
document.
16+
17+
When you've identified an issue you want to work on, assign it to yourself, or message us on that project's channel on
18+
[Discord](https://discord.gg/6cfyqRGbzq) and we'll assign it to you.
19+
20+
## Contribution workflow
21+
22+
The documentation contribution workflow consists of
23+
[forking repositories and submitting pull requests (PRs)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models#fork-and-pull-model).
24+
This facilitates social contribution, easy testing, and peer review.
25+
26+
To contribute changes:
27+
28+
1. [Fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) the documentation repository in which you want
29+
to make a change.
30+
31+
1. [Clone](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) your fork to
32+
your computer.
33+
For repositories using the [old system](../overview/index.md#old-documentation-system), add the
34+
`--recursive` option to retrieve the [common submodule](use-common-submodule.md).
35+
36+
```bash
37+
git clone [--recursive] <FORKED-REPO>
38+
```
39+
40+
1. [Add an upstream remote](https://docs.github.com/en/github/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-for-a-fork).
41+
42+
```bash
43+
git remote add upstream <ORIGINAL-REPO>
44+
```
45+
46+
1. [Create and checkout a topic branch](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging),
47+
naming it appropriately.
48+
We recommend using the issue number and short description, which is a reminder to fix only one issue in a PR.
49+
For example, `183-doc-cli-option`.
50+
51+
```bash
52+
git checkout -b <ISSUE-NUM>-<ISSUE-DESC>
53+
```
54+
55+
1. Open the documentation repository in a text editor of your choice, for example
56+
[IntelliJ](https://www.jetbrains.com/idea/), and make your changes.
57+
Refer to the [documentation style guide](style-guide.md) and the
58+
[MkDocs and Markdown guide](markdown/index.md) when making documentation changes.
59+
60+
1. [Preview your changes with MkDocs](../preview/old-system.md) to check that the changes render correctly.
61+
62+
1. Add and commit your changes, using a clear commit message.
63+
Push your changes to your remote fork (usually named `origin`).
64+
65+
```bash
66+
git add *
67+
git commit -m "<COMMIT-MESSAGE>"
68+
git push origin
69+
```
70+
71+
1. Navigate to the original ConsenSys documentation repository, and you'll see a banner prompting you to create a PR
72+
with your recent changes.
73+
Create a PR, filling out the description according to the template.
74+
Remember to [link the issue](https://help.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue)
75+
that the PR fixes in the description.
76+
77+
```text
78+
fixes #<ISSUE-NUM>
79+
```
80+
81+
1. The bottom of the PR page displays a list of checks that verify links, Markdown syntax, and more.
82+
If you have any [errors](fix-cicd-errors.md), make any required changes to your PR, repeating steps 5-7.
83+
84+
1. In the right sidebar of your PR, select the reviewer(s) who should review your PR (typically the original issue raiser).
85+
Ask the ConsenSys documentation team to review by selecting **ConsenSys/protocol-pliny** as a reviewer.
86+
If you don't know who to choose or can't because you're not a maintainer yet, select the reviewers listed by GitHub
87+
or keep the default value.
88+
89+
1. Make any required changes to your PR based on reviewer feedback, repeating steps 5-7.
90+
91+
1. After your PR is validated, all checks have passed, and your branch has no conflicts with the target branch, you can
92+
merge your PR.
93+
You can delete the topic branch after merging your PR.
94+
95+
!!! tip
96+
97+
You can use a Git client such as [Fork](https://fork.dev/) instead of the command line.
98+
99+
## Code of conduct
100+
101+
This project and everyone participating in it is governed by the
102+
[contributor covenant code of conduct](../reference/code-of-conduct.md).
103+
By contributing to documentation, you're expected to uphold this code.
104+
Please report unacceptable behavior to [`[email protected]`](mailto:[email protected]).
105+
106+
## Contributor License Agreement
107+
108+
When you submit a PR for your first contribution to a documentation repository, you must read and sign the
109+
[ConsenSys Individual Contributor License Agreement (CLA)](https://gist.github.com/rojotek/978b48a5e8b68836856a8961d6887992)
110+
when prompted before you can merge the PR.

0 commit comments

Comments
 (0)