Skip to content

Get involved

If you notice an inaccuracy, mistake, typo or want to supplement the information in this documentation, then you can help us to improve it. All of this documentation is available in the public domain on GitHub.

There are several ways:

  1. Creating an issue with a detailed description of the problem.
  2. Editing a single page in a browser.
  3. Manually creating a fork and doing multiply commits before creating a pull request.
  4. Installing and editing documentation locally on yours PC.

In each of these cases, a GitHub account required. If you don't want to register on GitHub, you can just contact us with any convenient way.

Easy way

On each page in the upper right corner of the text top there is a link with a picture of a pencil :material-pencil:. After clicking on this link, you will be asked to create a fork of the repository (if you have not done this before).

Create your fork

Creating a fork done with one green button. After that, the edit form with page source code will open.

For correct edit of page, please read the introduction into Mkdocs.

After editing the page, you must fill out a description of what you have done.

Please fill the commit message

Submitting a change will write it to a new branch in your fork, so you can send a pull request. We will review your pull request and accept it in the main branch.

Thus, this method is only suitable for simple edits on one page. There is another way to create pull requests to fix multiple pages at once.

Second way

This method allows you to make several edits on different pages before proposing them in a pull request.

  1. Create a fork of the repository if it has not been created yet. (Just click the "Fork" button in the upper right corner.)
  2. Go to the created fork and find the file you are interested in.
  3. Open the file and click the edit button.
  4. Make edits and commit with a clear description of the changes.
  5. Edit other files of interest to you in the same way.
  6. Go to the start page of the fork and click on the "Pull request" button.

After review and pull request will be merged, and you can drop a fork.

Hard way

This method involves installing the Git, IDE, Python and Material for MkDocs on yours PC.

  1. Install Python 3.
  2. Install Git client.
  3. Install an IDE, for example IntelliJ IDEA (Community edition would be enough).
  4. Create a fork of the repository and cloning it to local project. In IDEA: File -> New -> Project from version control;
  5. Install mkdocs-material and other dependencies. In console: 
    cd /path/to/project
mkdir venv
python -m venv ./venv
pip3 install -r requirements.txt
  6. Start the documentation server locally. In console: 
    cd /path/to/project
source venv/bin/activate
# Windows: \venv\Scripts\activate.bat
mkdocs serve --dirtyreload
  7. To check that the server has started, open in a browser: http://localhost:8000
  8. Create a local git branch in project.
  9. Make changes in documentation and test it in browser. Read the introduction.
  10. Commit and push changes. Please, use English in commit message.
  11. Create a Pull Request (PR) on Github from your fork. Please, use English in PR description.
  12. After the PR has been reviewed and merged to upstream you can remove branch and rebase a fork to the upstream.

Introduction into Mkdocs

This documentation built on mkdocs engine and mkdocs-material theme. Firstly, read how to layout and write your Markdown source files for an overview of how to write docs.

The menu formed using the plugin awesome-pages automatically. To set the desired page order in the menu, use the file .pages.yml in directory. For example:

title: Backend API
nav:
    - getting-started.md
    - how-to
    - resources
    - websocket

title sets the name for menu section. nav: sets the sub-items order.

Meta information

Each page must have meta information section at the beginning. Required fields: title and description. For example:

---
title: Get involved
description: Get involved into improving documentation and translations of the B2Field Platform
---

Title will be displayed in menu and in browser title.

Headers

The information on each page should be structured. On pages of the same type, the structure should be uniform.

Example

API resource page structure:

# Resource name

Path: `/path/to/resource\`.

Resource description.

Resource specific actions:

* [/path/to/resource/method1](#method1)
* [/path/to/resource/method2](#method2)

## method1

Method description.

### Parameters

| name  | description | type  | restrictions |
| :---- | :----       | :---- | :----        |
|param1 | description | int   | [1..100], not null |

### Examples

=== "cURL"

    ```shell
    curl -X POST 'https://api.navixy.com/v2/fsm/resource/sub_resource/action' \
        -H 'Content-Type: application/json' \ 
        -d '{"param1": "value1", "param2": "value2", "hash": "a6aa75587e5c59c32d347da438505fc3"}'
    ```

=== "HTTP GET"

    ```
    https://api.navixy.com/v2/fsm/resource/sub_resource/action?param1=value1&hash=a6aa75587e5c59c32d347da438505fc3
    ```

### Response

```json
{ "success": true }
```

!!! warning "Please note"
    If the response or structure has comments it is necessary to write these comments separately in the form of a list below.

### Errors

Special error codes.

## method2

...

For real example see /user and source.

Last update: December 17, 2020