Перейти к содержанию

Руководство по стилю

Введение

В этом документе описаны рекомендации по стилю для разработки документации на семейство серверов М1

Форматирование

Заголовки

# Заголовок первого уровня

## Заголовок второго уровня

### Заголовок третьего уровня

Cписки

- Элемент списка
- Еще один элемент списка

Примеры кода

Блоки кода на языке Python:

```py title="add_numbers.py" linenums="1" // язык_название блока_включение нумерации

Function to add two numbers

def add_two_numbers(num1, num2): return num1 + num2 

# Example usage
result = add_two_numbers(5, 3)
print('The sum is:', result)

Example codeblock for JavaScript with lines highlighted:

concatenate_strings.js
1
2
3
4
5
6
7
8
// Function to concatenate two strings
function concatenateStrings(str1, str2) {
  return str1 + str2;
}

// Example usage
const result = concatenateStrings("Hello, ", "World!");
console.log("The concatenated string is:", result);

#include <stdio.h>

int main(void) {
  printf("Hello world!\n");
  return 0;
}

#include <iostream>

int main(void) {
  std::cout << "Hello world!" << std::endl;
  return 0;
}

# Code block content

Вкладки

This is some examples of content tabs.

Generic Content

This is some plain text

  • First item
  • Second item
  • Third item
  1. First item
  2. Second item
  3. Third item

Ctrl+Alt+Del+Clear+Print Screen

Open styled details
Nested details!

And more content again.

We can escape everything! ❤😄

mySnippet: |- This is a snippet. It contains a link to the API Overview. myOtherSnippet: |- This is another snippet. It contains a link to the Client API Cookbook.

Оформление кода

Python

add_numbers.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
def example_function(param1, param2):
    Описание функции.

    Args:
        param1 (тип): Описание параметра 1.
        param2 (тип): Описание параметра 2.

    Returns:
        тип: Описание возвращаемого значения.
    # Ваш код здесь
    pass
add_numbers.py
1
2
3
4
5
6
7
# Function to add two numbers
def add_two_numbers(num1, num2):
    return num1 + num2

# Example usage
result = add_two_numbers(5, 3)
print('The sum is:', result)

Markdown

# Заголовок 1 уровня

## Заголовок 2 уровня

- Элемент списка
- Еще один элемент списка

Примеры

Пример 1

Описание примера 1.

Пример 2

Описание примера 2.

Заключение

Следуя этим рекомендациям, вы сможете поддерживать единый стиль в проекте и улучшить читаемость кода и документации.

Руководство по оформлению Markdown файлов

Markdown - это облегчённый язык разметки, который преобразует текст в структурированный HTML. Следующее руководство поможет вам разобраться, как использовать Markdown.

Заголовки

# Заголовок первого уровня
## Заголовок второго уровня
### Заголовок третьего уровня
#### Заголовок четвёртого уровня
##### Заголовок пятого уровня
###### Заголовок шестого уровня
Пример:

Заголовок первого уровня

Заголовок второго уровня

Заголовок третьего уровня

Заголовок четвёртого уровня

Заголовок пятого уровня
Заголовок шестого уровня

Параграфы и переносы строк

Это параграф. Чтобы создать новый параграф, оставьте пустую строку между двумя строками текста.

Это первая строка  
И это вторая строка, но они находятся в одном параграфе. Для переноса строки используйте два пробела в конце предыдущей строки.
Пример:

Это параграф. Чтобы создать новый параграф, оставьте пустую строку между двумя строками текста.

Это первая строка
И это вторая строка, но они находятся в одном параграфе. Для переноса строки используйте два пробела в конце предыдущей строки.

Выделение текста

*курсив*  
_курсив_

**жирный**  
__жирный__

***жирный курсив***  
___жирный курсив___

~~зачеркнутый~~
Пример:

курсив
курсив

жирный
жирный

жирный курсив
жирный курсив

~~зачеркнутый~~

Списки

Нумерованный список

1. Пункт первый
2. Пункт второй
3. Пункт третий
Пример:
  1. Пункт первый
  2. Пункт второй
  3. Пункт третий

Маркированный список

- Пункт первый
- Пункт второй
- Пункт третий
Пример:
  • Пункт первый
  • Пункт второй
  • Пункт третий

Вложенные списки

Также можно делать вложенные списки, добавляя 4 пробела перед пунктом: 

1. Пункт первый
    - Подпункт первый
    - Подпункт второй
2. Пункт второй
Пример:
  1. Пункт первый
    • Подпункт первый
    • Подпункт второй
  2. Пункт второй

Ссылки

[Текст ссылки](https://www.example.com)
Пример:

Текст ссылки

Изображения

![Текст описания](https://www.example.com/image.jpg)
Пример:

Текст описания

Блоки кода

Строка кода

`строка кода`
Пример:

строка кода

Блок кода

Удалите символы \ 

\```
Блок кода
\```
Пример: 
Блок кода

Подсветка кода

Для блоков кода можно указывать язык программирования.

Используется подсветка синтаксиса из библиотеки linguist, которая включает множество различных языков.

Удалите символы \ 

\```python
print("Привет, мир!")
\```
Пример: 
print("Привет, мир!")

Цитаты

> Первый уровень цитирования
>> Второй уровень цитирования
>>> Третий уровень цитирования
Пример:

Первый уровень цитирования

Второй уровень цитирования

Третий уровень цитирования

Горизонтальная линия

---
Пример:

Таблицы

| Заголовок 1 | Заголовок 2 |
| ----------- | ----------- |
| Ячейка 1    | Ячейка 2   |
| Ячейка 3    | Ячейка 4   |
Пример:
Заголовок 1 Заголовок 2
Ячейка 1 Ячейка 2
Ячейка 3 Ячейка 4

Таблица как HTML

<table>
    <tr>
        <th>Заголовок 1</th>
        <th>Заголовок 2</th>
    </tr>
    <tr>
        <td>Ячейка 1.1</td>
        <td>Ячейка 2.1</td>
    </tr>
    <tr>
        <td>Ячейка 1.2</td>
        <td>Ячейка 2.2</td>
    </tr>
</table>
Пример:
Заголовок 1 Заголовок 2
Ячейка 1.1 Ячейка 2.1
Ячейка 1.2 Ячейка 2.2

Чек-листы

- [x] Задача 1
- [ ] Задача 2
- [ ] Задача 3
Пример:
  • Задача 1
  • Задача 2
  • Задача 3

Внутренние ссылки

[Перейти к Заголовку 1](#title1)

## <a id="title1">Заголовок 1</a>
Какой-то контент
Пример:

Перейти к Заголовку 1

Заголовок 1

Какой-то контент

Ссылка на заголовок на английском

[Some title 1](#some-title-1)

## Some Title 1
Some content
Пример:

Some title 1

Some Title 1

Some content

Автоматические ссылки

<http://example.com/>

<address@example.com>
Пример

http://example.com/

address@example.com

HTML

Markdown поддерживает использование прямого HTML внутри документа, так что вы можете использовать любые HTML-теги для более сложного оформления: 

<kbd>CTRL</kbd> + <kbd>P</kbd>
Пример:

CTRL + P

HTML-коды

Например, вы можете использовать HTML-код &macr; для добавления черты над буквой: 

A&macr;
Пример:

A¯

Комментарии

Вы можете вставить комментарии в свой markdown-файл, которые не будут отображаться в окончательном отформатированном виде: 

[//]: # (Это комментарий, он не будет отображаться)
Пример:

Эмодзи (Github)

Вы можете использовать эмодзи в своих Markdown-файлах. Существует множество эмодзи, которые вы можете использовать, вот некоторые из них: 

:smile:
:laughing:
:blush:
Пример:

😄 😆 😊