Preview the Besu documentation with MkDocs on your local machine and on Read the Docs.
Preview locally
We recommend previewing your work locally before pushing your changes in a PR. Since the final documentation is built with MkDocs, you must build the documentation locally with MkDocs to ensure the Markdown is correctly rendered. To preview the documentation locally:
Create a virtual environment for the project:
python3 -m venv env
Activate the virtual environment:
source env/bin/activate- An (env) now appears at the beginning of your prompt.
Install all the required dependencies in this virtual environment.
We use two requirements files because we have an insider (sponsored) version of material design theme and only readthedocs preview and build can use it.
You will have to use the non insider version for local preview. There's a few differences but it's mostly compatible and a good smoke test. The real preview is rendered in the PR, see next section.
The requirements.txt is for the common dependencies, the requirements-mkdocs-material.txt is for installing the mkdocs material theme.
Run command with both requirement files:pip install -r CI/requirements.txt -r CI/requirements-mkdocs-material.txt
Run the following command in the project directory:
mkdocs serve
In the output of this command, follow the link displayed on the line that looks like the following:
[I 190206 18:48:47 server:298] Serving on http://127.0.0.1:8000In this case, go to
http://127.0.0.1:8000. You can let this server run while you work on the documentation. It updates the local website automatically when you save changes in your Markdown files.
Deactivate the virtual environment if you work on another Python project, by running
deactivate. You can preview the same documentation site again starting from step 3 and skipping step 4, until you update Python.
Preview on Read the Docs
When you create a PR on a documentation repository, the PR triggers CircleCI checks to verify links, Markdown syntax, writing style, and more. The documentation is also built on Read the Docs (RTD) as a PR preview. This preview uses the insider version of material theme for MkDocs.
You can find the link to this preview in the checklist at the bottom of your PR page. The preview only works for registered and permitted RTD users. Ask for help on Discord if needed.
Thanks for taking the time to contribute to the docs!
Welcome to the documentation section of the Besu wiki
The following links are a set of guidelines for contributing to this repo. These are mostly guidelines, not rules. Use your best judgement, and feel free to propose changes to this wiki page.
Documentation contributions come in the form of writing new documentation, raising issues with the current doc, correcting mistakes, helping others in chat with doc content and more.
LF / Jira Accounts
Having the following accounts is necessary for contributing to besu-docs.
- If you want to contribute documentation/code, you can make a Linux Foundation (LF) account here.
- If you want to raise an issue, you can login to your Atlassian account here.
- Our Rocket Chat also requires a Linux Foundation (LF) account.
Useful contributing links
DCO is also needed for documentation
Still no luck?
What to do to contribute but are unsure of where to start, even after looking at our good-first-issues and help-wanted tags in our Jira?
...