mirror of https://github.com/hyperledger/besu
An enterprise-grade Java-based, Apache 2.0 licensed Ethereum client https://wiki.hyperledger.org/display/besu
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
420 lines
15 KiB
420 lines
15 KiB
# 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 3.x](https://www.mkdocs.org/#installing-python) (see [readthedocs.yml](readthedocs.yml) file for
|
|
the exact version)
|
|
- [Install PIP](https://www.mkdocs.org/#installing-pip)
|
|
- Install all the required dependencies :
|
|
```bash
|
|
pip install -r docs/requirements.txt
|
|
```
|
|
>**note**
|
|
> If pip raises errors like `Could not find a version that satisfies the requirement` when executing
|
|
`pip`, you may have to use the `pip3` commend to explicitely run Python 3 specific pip depending if
|
|
you already have another python version installed or not and in what order you installed them.
|
|
- 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.
|
|
|
|
>**Important**
|
|
>
|
|
> Run `python --version` to make sure you are using version indicated in [readthedocs.yml](readthedocs.yml) file.
|
|
>
|
|
> If you are updating from a previous Python version you will also have to run pip install again and
|
|
check your path.
|
|
|
|
## 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.
|
|
|
|
### 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
|
|
}
|
|
```
|
|
````
|
|
|
|
#### Tabbed Code Blocks
|
|
|
|
[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
|
|
```
|
|
````
|
|
|
|
#### Line Numbers On Long Code Samples
|
|
|
|
[SuperFences] can also add [line numbers](https://facelessuser.github.io/pymdown-extensions/extensions/superfences/#showing-line-numbers)
|
|
to the code sample which makes it easier when discussing the code the sample.
|
|
|
|
The line numbers will only appear on the code block that uses the `linenums="1"` parameter.
|
|
|
|
Example:
|
|
````markdown
|
|
```javascript linenums="1"
|
|
// A very long javascript sample code
|
|
```
|
|
````
|
|
|
|
#### Code Syntax Highlight
|
|
|
|
Codehilite extension enables automatic syntax highlighting of code blocks. Define the language after
|
|
the code block delimiter 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/).
|
|
|
|
|
|
|
|
[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 |