mirror of https://github.com/hyperledger/besu
Update doc contribution guidelines (#796)
* Updated search urls * Added math support * Doc Style guide * removed useless extensions * splitting doc guidelines into 3 parts Signed-off-by: Adrian Sutton <adrian.sutton@consensys.net>pull/2/head
Nicolas MASSART
6 years ago
committed by
GitHub
parent
e923ddda65
commit
1c543bff6f
@ -0,0 +1,110 @@ |
||||
# Pantheon Documentation Style Guide |
||||
|
||||
## Purpose of this Document |
||||
|
||||
This document contains guidelines to ensure the Pantheon documentation is consistent and well organised. |
||||
|
||||
This is a living document and will evolve to better suit Pantheon users and contributors needs. |
||||
|
||||
> **Note:** Although not everything in this style guide is currently followed in the Pantheon |
||||
documention, these guidelines are intended to be applied when writing new content and revising |
||||
existing content. |
||||
|
||||
**The primary audience for this document is:** |
||||
|
||||
* Members of the Pantheon team |
||||
* Developers and technical writers contributing to the Pantheon documentation |
||||
|
||||
## Mission Statement |
||||
|
||||
The Pantheon documentation contributes to a consistent and easy to understand experience for end users. |
||||
We're focused on creating a great experience for both new and expert users of Ethereum clients. |
||||
|
||||
## General Guidelines |
||||
|
||||
The guiding principles for the Pantheon documentation are: |
||||
1. Be consistent |
||||
1. Keep it simple but technically correct |
||||
1. Be proactive and suggest good practices |
||||
1. Be informative and exhaustive. |
||||
|
||||
### 1. Be Consistent |
||||
|
||||
Consistency is important to help our end users build a mental model of how Pantheon works. |
||||
By being consistent with our word choices, visual formatting, and style of communication it helps |
||||
users know what to expect when they refer to or search Pantheon documentation. |
||||
|
||||
### 2. Keep It Simple But Technically Correct |
||||
|
||||
Avoid technical jargon and always assume our end users may not be Ethereum experts. |
||||
|
||||
This doesn't mean explaining all Ethereum concepts in our documentation. Explain Pantheon functionality |
||||
and when an understanding of complex Ethereum concepts is required refer users to relevant resources. |
||||
|
||||
For example, to explain how the EVM works, link to ethdocs.org documentation such as |
||||
http://ethdocs.org/en/latest/introduction/what-is-ethereum.html#ethereum-virtual-machine |
||||
|
||||
Simple explanations must still be technically correct. |
||||
|
||||
### 3. Be Proactive And Suggest Good Practices |
||||
|
||||
Being proactive means anticipating user needs and guiding them through a process. |
||||
This most often takes the form of notes or tip messages alongside the main explanation. |
||||
Put yourself in the user's shoes and consider what questions you would have when reading the documentation. |
||||
|
||||
Do not assume required steps are implied. Err on the side of including them if you are unsure. |
||||
|
||||
Documenting good practices is also important. |
||||
For example, instruct users to secure private keys and protect RPC endpoints a production environments. |
||||
|
||||
### 4. Be Informative But Concise |
||||
|
||||
We seek a balance between providing enough relevant information to help our users develop a solid |
||||
mental model of how Pantheon works without forcing them to read too much text or redundant detail. |
||||
|
||||
To provide additional detail, use sub-sections. |
||||
|
||||
## Writing Style Guide |
||||
|
||||
We use the [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/) as our general guide |
||||
to writing technical documentation. |
||||
We take guidance from it but do not apply every rule. |
||||
For example, we use title case rather than sentence case. |
||||
|
||||
The Micrsoft Style Guide aims for natural, simple, and clear communication. |
||||
|
||||
Here are some important points we follow: |
||||
|
||||
### Active Voice |
||||
Use active voice. Use _you_ to create a more personal friendly style. Avoid gendered pronouns (_he_ or _she_). |
||||
|
||||
### Contractions |
||||
Use contractions. For example, don’t. |
||||
|
||||
Use common contractions, such as it’s and you’re, to create a friendly, informal tone. |
||||
|
||||
### Recommend |
||||
It's acceptable to use "we recommend" to introduce a product recommendation. |
||||
Don't use "PegaSys recommends" or "it is recommended." |
||||
|
||||
Example: Instead of _This is not recommended for production code_ use _We don't recommend this for production code_. |
||||
|
||||
### Directory vs Folder |
||||
Use _directory_ over _folder_ because we are writing for developers. |
||||
|
||||
### Title Case For Headings |
||||
Use title case for headings. |
||||
|
||||
Note: This is a case where we are not following the Microsoft Writing Style Guide. |
||||
|
||||
### Assumed Knowledge For Readers |
||||
We have two distinct audiences to consider when developing content: |
||||
|
||||
- New to Ethereum and Ethereum clients |
||||
- Experienced with Ethereum clients other than Pantheon. |
||||
|
||||
### Avoid Abbreviations |
||||
|
||||
Try not to use abbreviations [except for well known ones and some jargon](MKDOCS-MARKDOWN-GUIDE.md#abbreviations). |
||||
Don't use "e.g." but use "for example". |
||||
Don't use "i.e." but use "that is". |
||||
@ -0,0 +1,392 @@ |
||||
# MkDocs And Markdown Guide |
||||
|
||||
Pantheon documentation is written using [Markdown](https://daringfireball.net/projects/markdown/) syntax. |
||||
|
||||
However, we use two flavors of this syntax: |
||||
|
||||
- One for pages inside the [/docs](/docs) directory that will be rendered by [MkDocs] as described below |
||||
in the [Installed Markdown Extensions](#installed-markdown-extensions) section. |
||||
- Another using the [Github syntax](https://guides.github.com/features/mastering-markdown/) |
||||
for pages outside of this documentation directory. These are mainly files to support our [open source |
||||
community](https://github.com/PegaSysEng/pantheon/community). |
||||
|
||||
## MkDocs Documentation Website |
||||
|
||||
The [Pantheon documentation website](https://docs.pantheon.pegasys.tech/) is maintained by PegaSys from |
||||
the content of the [/docs](/docs) directory. |
||||
|
||||
### /docs Directory |
||||
|
||||
The [/docs](/docs) directory in the Pantheon repository contains all the documentation that |
||||
is generated into a static HTML website using [MkDocs] and the [Mkdocs Material] theme and hosted by [readthedocs.org]. |
||||
|
||||
The documentation is automatically updated using [WebHooks](https://docs.readthedocs.io/en/stable/webhooks.html) |
||||
linking GitHub to the [readthedocs.org] site when you merge a pull-request in the master branch of Pantheon. |
||||
|
||||
The system also detects tags in the Github repository and takes care of making the latest stable release |
||||
and previous versions available. |
||||
|
||||
If any issues occur, contact the maintainers of the [Pantheon documentation project](https://readthedocs.org/projects/pantheon/). |
||||
|
||||
### MkDocs Configuration |
||||
|
||||
[MkDocs] is a Python tool that generates the static HTML website that is published. |
||||
|
||||
Our [MkDocs] setup uses a [Mkdocs Material] theme to render the html pages. It also comes with a number of useful extensions. |
||||
|
||||
[MkDocs] in configured in the [mdkocs.yml](/mkdocs.yml) file. |
||||
|
||||
This file configures: |
||||
|
||||
- Site meta data and variables |
||||
- Theme configuration |
||||
- Page navigation |
||||
- Extensions |
||||
- Plugins |
||||
|
||||
If you add pages to the documentation (rather than updating existing pages), update the "nav" section |
||||
to add your page and specify the page name. |
||||
|
||||
### Preview The Documentation |
||||
|
||||
We recommended previewing your work locally before pushing your changes within a pull-request. |
||||
As the final documentation is build with [MkDocs], you have to build your docs locally with this tool |
||||
to ensure the Markdown is correctly understood and displayed. |
||||
|
||||
To preview Pantheon documentation locally: |
||||
|
||||
- [Install Python](https://www.mkdocs.org/#installing-python) |
||||
- [Install PIP](https://www.mkdocs.org/#installing-pip) |
||||
- Install all the required dependencies : |
||||
```bash |
||||
pip install -r docs/requirements.txt |
||||
``` |
||||
- Run the following command in the project directory : |
||||
```bash |
||||
mkdocs serve |
||||
``` |
||||
- Follow the link displayed on the output of this command that |
||||
looks like `[I 190206 18:48:47 server:298] Serving on http://127.0.0.1:8000`, |
||||
here connect to [http://127.0.0.1:8000] |
||||
|
||||
You can let this doc server run while you work on the doc, it updates the local website |
||||
automatically when you save changes in your Markdown files. |
||||
|
||||
## Formatting Markdown For Doc Site |
||||
|
||||
Final documentation rendering is essential, but the format of the Markdown files is also very important. |
||||
|
||||
Formatting the Markdown code helps reviewers and writers easily navigate in the code and review your changes. |
||||
|
||||
A few basic rules: |
||||
|
||||
- Each file must contain a header composed of [meta-data](https://squidfunk.github.io/mkdocs-material/extensions/metadata/) |
||||
and ended by a specific comment. |
||||
Ex: |
||||
```markdown |
||||
title: Installation overview |
||||
description: Overview and requirements to install Pantheon |
||||
<!--- END of page meta data --> |
||||
``` |
||||
- [As for other code](https://google.github.io/styleguide/javaguide.html#s4.4-column-limit), |
||||
each line of Markdown code must be limited to 100 columns long to be readable on any editor. |
||||
Lines have to be wrapped without cutting the line in the middle of a word. A line break displays as a space. |
||||
- No HTML markup can be used inside a Markdown document. |
||||
We provide [a lot of extensions](#installed-markdown-extensions) that are able to do the same thing |
||||
without HTML. If you think one is missing, just discuss it with the team on [Gitter] and we'll decide together |
||||
if it's worth adding an extension. |
||||
- Only one first level title can be present on a page. |
||||
- Format tables so they are also readable in the source code. |
||||
You can quickly achieve this by using a tool like http://markdowntable.com/ |
||||
|
||||
## Installed Markdown Extensions |
||||
|
||||
>**Important** |
||||
> Extensions are only available for the docs under [/docs](/docs) directory. |
||||
|
||||
As markdown can be a bit limited when it comes to some specific rendering of code, TOCs, and other documentation |
||||
elements, we configured some extensions for these items. |
||||
Extensions enable you to use simple Markdown syntax to achieve some complex rendering. |
||||
|
||||
>**Important** |
||||
> Never use HTML tags directly in the Markdown files to try to render content. |
||||
For consistency reasons we only allow the specific renderings available in the extensions. |
||||
|
||||
Here is a list of the available extensions: |
||||
|
||||
### TOC |
||||
|
||||
This extension automatically displays a table of content of the current page on the right side of the page. |
||||
It displays titles to the third level (`###`). After the third level, titles won't be displayed in the TOC. |
||||
|
||||
This extension also displays a link on the right of any title called "permalink". |
||||
This link can be used to point directly to the title from another website. |
||||
|
||||
### Highlight |
||||
|
||||
This extension enables automatic syntax highlighting of code blocks. Define the language to ensure correct |
||||
highlighting. If you don't provide the language name, the extension attempts to automatically discover it |
||||
but this can lead to errors. |
||||
|
||||
Example: |
||||
````markdown |
||||
```json |
||||
{ |
||||
"jsonrpc" : "2.0", |
||||
"id" : 51, |
||||
"result" : { |
||||
"startingBlock" : "0x5a0", |
||||
"currentBlock" : "0xad9", |
||||
"highestBlock" : "0xad9" |
||||
} |
||||
} |
||||
``` |
||||
```` |
||||
|
||||
Pygment is the implementation for this extension, refer to Pygment website for a |
||||
[list of the supported languages](http://pygments.org/languages/). |
||||
|
||||
### Include |
||||
|
||||
If you have content to be repeated on multiple pages, you can create it in a common page in and include |
||||
it in all required pages. |
||||
|
||||
Example: |
||||
To include the content of the "test_accounts.md" page in the "/docs/global" directory in another page, use: |
||||
```markdown |
||||
{!global/test_accounts.md!} |
||||
``` |
||||
|
||||
### Admonition |
||||
|
||||
The [Admonition extension](https://squidfunk.github.io/mkdocs-material/extensions/admonition/#admonition) |
||||
enables information, warning, and danger blocks. |
||||
|
||||
Example: |
||||
````markdown |
||||
!!! note |
||||
This is a multi line note |
||||
in the Pantheon documentation. |
||||
```` |
||||
|
||||
The 4 spaces indentation is required for the content to be part of the admonition. |
||||
|
||||
We generally use the following [types](https://squidfunk.github.io/mkdocs-material/extensions/admonition/#types) |
||||
in our documentation: |
||||
|
||||
- **Note** : Used to add information about a subject that doesn't directly needs to be taken in account |
||||
to use this specific part. |
||||
Example: "Available since v0.8.3" |
||||
- **Abstract** : Used at the beginning of a long article. Also known as "TL;DR", this can help users jump |
||||
into the content knowing that they will find their answer somewhere in the page. |
||||
- **Info** : Used to provide detail about a specific part of the documentation. |
||||
Ex: "The miner coinbase account is one of the accounts defined in the genesis file." |
||||
- **Tip** : Used to provide information that could help improve the use of the tool, make it faster. |
||||
Example: "To restart the private network in the future, start from 4. Restart First Node as Bootnode." |
||||
- **Warning** : Used to warn the users about something important. |
||||
Ex: "This will be deprecated in next version." |
||||
- **Danger** : Used to alert the user about a potential dangerous effect such as a risk of destroying |
||||
something or losing assets. |
||||
Ex: "Never use the development private keys for production use". |
||||
- **Example** : used to display an example. We usually use it with a single or tabbed code-block: |
||||
````markdown |
||||
!!! example |
||||
This example shows how to use the `net_listening` RPC method. |
||||
|
||||
```bash tab="curl HTTP request" |
||||
$ curl -X POST --data '{"jsonrpc":"2.0","method":"net_listening","params":[],"id":53}' <JSON-RPC-http-endpoint:port> |
||||
``` |
||||
|
||||
```bash tab="wscat WS request" |
||||
{"jsonrpc":"2.0","method":"net_listening","params":[],"id":53} |
||||
``` |
||||
|
||||
```json tab="JSON result" |
||||
{ |
||||
"jsonrpc" : "2.0", |
||||
"id" : 53, |
||||
"result" : true |
||||
} |
||||
``` |
||||
```` |
||||
|
||||
### Footnotes |
||||
|
||||
The [Footnotes extension](https://squidfunk.github.io/mkdocs-material/extensions/footnotes/) enables |
||||
adding footnotes. |
||||
|
||||
Footnotes display content at the end of the page and a numbered link inside the text to go to this content. |
||||
The extension also adds a link at the end of the footnote back to the text. |
||||
|
||||
### Definitions List |
||||
|
||||
The [def_list extension](https://python-markdown.github.io/extensions/definition_lists/) enables listing definitions |
||||
directly in the Markdown. |
||||
|
||||
### Abbreviations |
||||
|
||||
Generally we avoid the use of abbreviations but some like "PoW" for proof-of-work or "dApp" for |
||||
decentralized application are now part of the Ethereum jargon. The [Abbreviation extension](https://python-markdown.github.io/extensions/abbreviations/) |
||||
enables a tool tip hint to be provided for abbreviations. |
||||
|
||||
Place abbreviations at the beginning of the Markdown file just after the meta-data header. |
||||
|
||||
Example: |
||||
```markdown |
||||
description: This is an example page |
||||
<!--- END of page meta data --> |
||||
|
||||
*[PoA]: Proof of Work |
||||
|
||||
Clique is a PoA mechanism used in the Rinkeby test network |
||||
``` |
||||
|
||||
### Math |
||||
|
||||
[Arithmatex extension](https://squidfunk.github.io/mkdocs-material/extensions/pymdown/#arithmatex-mathjax ) |
||||
enables writing math formulas in the documentation using the provided syntax. |
||||
|
||||
Example: |
||||
```markdown |
||||
$\sigma=\displaystyle\prod_{k=1}^t\sigma_{i_k}^{L_{i_k}(0)}$ |
||||
|
||||
Constructing the threshold signature $\sigma$ from $t$ individual |
||||
signatures $\sigma_{i_k}$, $k=1,\dots,t$ and the Lagrange polynomials |
||||
$L_{i_1}, \dots,L_{i_t}$ associated to the set $I=\{i_1,\dots,i_t\}$ of signers. |
||||
``` |
||||
|
||||
### Better Emphasis |
||||
|
||||
The [Betterem extension](https://facelessuser.github.io/pymdown-extensions/extensions/betterem/) is |
||||
automatically applied to your bold and italic content. |
||||
|
||||
### Keyboard Shortcuts |
||||
|
||||
The [Keys syntax](https://facelessuser.github.io/pymdown-extensions/extensions/keys/) extension enables |
||||
displaying keyboard shortcuts. |
||||
|
||||
Example: |
||||
```markdown |
||||
++ctrl+C++ |
||||
``` |
||||
|
||||
### Folding Details Blocks |
||||
|
||||
You can use a folding block to hide content. The block can be closed by default or open. |
||||
This pattern helps reduce the content length and enables a faster overview of the whole page. |
||||
|
||||
Ex: |
||||
```markdown |
||||
???+ note "Folding details" |
||||
This is the detail of my content. |
||||
The plus sign makes it unfolded by default. |
||||
Remove the plus sign and it will be folded by default. |
||||
``` |
||||
|
||||
### Emojis |
||||
|
||||
Emojis are fun, but they can also be useful to draw the reader's attention. |
||||
Try to use only neutral emojis like :warning: |
||||
|
||||
Refer to a [supported full list of available emojis](https://www.webfx.com/tools/emoji-cheat-sheet/) |
||||
to find the suitable code. |
||||
|
||||
Example: |
||||
`:warning:` displays :warning: |
||||
|
||||
### Magic Links |
||||
|
||||
If you want an URL to be displayed as a link, simply write it and this extension automatically displays it as |
||||
a link. You don't need to surround it with Markdown links syntax. |
||||
|
||||
### Highlight Content |
||||
|
||||
The [Mark extension](https://facelessuser.github.io/pymdown-extensions/extensions/mark/) enables highlighting of |
||||
content. |
||||
|
||||
Text surrounded by double equals is highlighted in yellow. |
||||
|
||||
Example: |
||||
```markdown |
||||
==This is highlighted text== |
||||
``` |
||||
|
||||
### Strike Through |
||||
|
||||
The [tilde syntax](https://squidfunk.github.io/mkdocs-material/extensions/pymdown/#tilde) extensions enables text |
||||
strike through to be displayed. |
||||
|
||||
Example: |
||||
```markdown |
||||
~~This is the wrong way to do~~ |
||||
``` |
||||
|
||||
### Symbols |
||||
|
||||
The [Smart symbols syntax](https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/) enables |
||||
the inclusion of symbols. |
||||
|
||||
Ex: |
||||
`-->` will draw a nice right arrow. |
||||
|
||||
### Task lists |
||||
|
||||
The [Task list syntax](https://squidfunk.github.io/mkdocs-material/extensions/pymdown/#tasklist) extension |
||||
enables displaying a list as a checklist. |
||||
|
||||
### Code Samples And Examples With [SuperFences] |
||||
|
||||
#### Format The Code |
||||
|
||||
For writing code examples inside the documentation, refer to the developer style guides: |
||||
|
||||
- Java : refer to our [coding convention](CODING-CONVENTIONS.md). |
||||
- JSON : use https://jsonformatter.curiousconcept.com/ to format your JSON code. |
||||
- TOML : we follow version 0.5.0 language definition. |
||||
- JavaScript : see [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html). |
||||
|
||||
#### Including Code in the Documentation |
||||
|
||||
We use code-blocks provided by the [SuperFences] extension to present code samples and examples in the |
||||
documentation. |
||||
|
||||
A basic code-block uses triple back ticks and the language name to enable syntax highlighting. |
||||
|
||||
For example, a JSON result is written as: |
||||
|
||||
````markdown |
||||
```json |
||||
{ |
||||
"jsonrpc": "2.0", |
||||
"id": 1, |
||||
"result": true |
||||
} |
||||
``` |
||||
```` |
||||
|
||||
[SuperFences] enables additional functionality such as the tabbed code-block. |
||||
|
||||
For example, to group the usage syntax and a usage example in the same block with tabs: |
||||
|
||||
````markdown |
||||
```bash tab="Syntax" |
||||
$ pantheon rlp encode [--from=<FILE>] [--to=<FILE>] [--type=<type>] |
||||
``` |
||||
|
||||
```bash tab="File Example" |
||||
$ pantheon rlp encode --from=ibft_extra_data.json --to=extra_data_for_ibft_genesis.txt --type=IBFT_EXTRA_DATA |
||||
``` |
||||
|
||||
```bash tab="Standart Input/Output Example" |
||||
$ cat extra_data.json | pantheon rlp encode > rlp.txt |
||||
``` |
||||
```` |
||||
|
||||
[SuperFences] also adds line numbers to the code sample which makes it easier when discussing the code the sample. |
||||
|
||||
|
||||
[MkDocs]: https://www.mkdocs.org/ |
||||
[readthedocs.org]: https://readthedocs.org/ |
||||
[Mkdocs Material]: https://squidfunk.github.io/mkdocs-material/ |
||||
[Gitter]: https://gitter.im/PegaSysEng/pantheon |
||||
[SuperFences]: https://squidfunk.github.io/mkdocs-material/extensions/pymdown/#superfences |
||||
Loading…
Reference in new issue