README.md · OSCHINA-MIRROR/limodou-parm

Введение в Parm

Конвертируйте синтаксис Markdown в документы HTML, поддерживая семантический интерфейс пользователя (Semantic-UI) и структуру CSS-фреймворка Bootstrap.

Установка

Сначала установите Par и Parm на свой компьютер.

pip install parm

Затем создайте свои документы Markdown. Например, напишите их в:

/project/docs

Инициализация среды

Далее перейдите в папку docs. Если вы запускаете программу впервые, вам следует инициализировать среду проекта Parm, просто выполнив:

parm init

При выполнении этой команды вас могут спросить, хотите ли вы инициализировать информацию о конфигурации. Если вы выберете «Y», то перейдёте в интерактивную командную строку, где нужно будет ввести некоторую информацию, которую можно изменить позже в файле conf.py. Parm будет использовать её для преобразования документов Markdown.

Эта команда скопирует некоторые статические файлы и шаблоны из модуля Parm. Но сейчас вам не нужно об этом беспокоиться.

Для версии 0.9 она также скопирует демонстрационные страницы, такие как index.md, introduction.md. Вы можете сразу запустить parm make и увидеть результат.

Создание оглавления

Теперь вы можете начать преобразование документов. Поскольку Parm поддерживает оглавление (TOC), вы можете написать содержание темы в файле index.md. Для версии 0.9 он уже создан для вас, поэтому вы можете просто открыть и отредактировать его.

Содержание выглядит так:

## Введение

{% toc max_depth=2 %}
file1.md
file2.md
...
{% endtoc %}

В версии 0.9 вам не нужны заголовки H1, потому что информация о проекте уже записана в conf.py, и вы можете изменить её.

Вы должны поместить все файлы, которые хотите включить в список, в тег toc. Также вы можете установить аргумент max_depth, который означает уровень заголовка каждого файла Markdown, например, H1, H2 и т. д. Вы также можете пропустить max_depth — по умолчанию будет 1.

Можно добавить несколько разделов TOC в index.md и дать заголовок H2 для каждого.

Сборка

Запустите:

parm make

чтобы начать конвертацию.

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

parm make -d output_directory

и результат будет выведен в output_directory.

Преобразование reStructuredText в Markdown

Parm также поддерживает преобразование формата reStructuredText в формат Markdown. Просто перейдите в каталог документов и выполните следующую команду:

parm rst2md <output_directory>

Но вы знаете, что формат reStructuredText богаче, чем Markdown, поэтому я расширил некоторые новые стили для формата Markdown в проекте Par. Однако некоторые стили не поддерживаются Par, поэтому вам придётся изменить их вручную.

Если вы хотите преобразовать reStructuredText в Markdown, сначала установите docutils.

Просто попробуйте, надеюсь, вам понравится.

О программе rst2md

Я обнаружил проект https://github.com/cgwrench/rst2md на GitHub и изменил код, чтобы он соответствовал стилю Par. Но я обнаружил, что rst2md кажется недостаточно удобным.

Как добавить поддержку Disqus

После инициализации проекта Parm он скопирует несколько шаблонов и статических файлов. Возможно, вы захотите добавить поддержку Disqus на каждую страницу. Позвольте мне показать вам, как это сделать.

Войдите в Disqus и получите встроенные коды

Для версии 0.9 Parm уже поддерживает Disqus, поэтому при создании conf.py вас спросят об имени учётной записи Disqus, которое будет сохранено в conf.py для последующего редактирования. Вам следует знать, как настроить его, если вы захотите изменить его позже.

Сначала войдите в Disqus, а затем вы получите два абзаца: один — код HTML, другой — код JavaScript. Например:

Код HTML

<div id="disqus_thread" style="margin:20px;"></div>
 <script type="text/javascript">
     /* * * CONFIGURATION VARIABLES: EDIT BEFORE PASTING INTO YOUR WEBPAGE * * */
     var disqus_shortname = 'YOUR_SITE_SHORT_NAME'; // required: replace example with your forum shortname

     /* * * DON'T EDIT BELOW THIS LINE * * */
     (function() {
         var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
         dsq.src = 'http://' + **Код на языке JavaScript**


И вы должны заменить два `ВАШ_САЙТ_SHORT_NAME` в соответствии с вашей учётной записью disqus.

Для версии 0.9 вы можете просто заменить `disqus` конфигурационную переменную, этого достаточно.

Вышеприведённые коды уже сохранены в `conf.py`, например:

#disqus disqus_text = ''' ...<первый абзац> '''

disqus_js = ''' ...<второй абзац> '''


### Измените layout.html

Откройте файл шаблона `your_parm_project/templates/layout.html` и измените два места:

После

```

добавьте:

<!-- disqus -->
{{<< conf.disqus_text}}

и перед

</body>

добавьте:

{{<< conf.disqus_js}}

Когда после выполнения вышеописанных действий, снова выполните parm make -d output_directory.

Для версии 0.9 приведённый выше код уже существует в шаблоне layout.html.

Измените введение Index Info

Введение — это параграф для отображения названия проекта и сводной информации, вы можете изменить его в conf.py:

introduction = u'''
<h1 class="ui header">%s
<a class="ui black label">%s</a>
</h1>
<h2 class="ui header">Здесь показано описание вашего проекта.</h2>
''' % (project, version)

О теме

Для версии 0.8 parm уже поддерживает две темы: bootstrap, semantic. Но я предпочитаю семантическую, потому что я уделил ей больше внимания. Если вы хотите изменить тему, вы можете просто изменить :

theme = 'semantic'

Навигация по меню

По умолчанию навигация по меню имеет только домашнюю запись, вы можете изменить её в conf.py в соответствии с описанием:

menus = [
    ('home', 'Home', 'index.html'),
]

Как исключить файлы

В версии 0.9 после инициализации проекта parm должен быть файл exclude.txt, вы можете изменить его, чтобы исключить файлы или каталоги, которые вы не хотите копировать в выходной каталог. Один шаблон может быть в одной строке. Шаблон похож на шаблон сопоставления имён файлов, например, доступны следующие шаблоны:

conf.py
*.pyc
templates

Как разместить свои документы на страницах github

клонируйте свой проект в новый каталог, например yourproject-doc
git checkout --orphan gh-pages
git rm -rf .
создайте документы в своём репозитории и напишите свои документы

визуализируйте html в каталог документов, например каталог будет:

проект(мастер)\
   документы\  <------вы здесь
project-doc(gh-страницы)\

parm make -d ../../yourproject-doc

в yourproject-doc git add .
git commit -a -m "init doc"
git push origin gh-pages
Посетите свои документы по адресу http://yourname.github.io/yourproject

Вы также можете посмотреть документацию https://help.github.com/articles/creating-project-pages-manually, чтобы понять, как использовать gh-pages.

Markdown Extensions

Parm добавляет некоторые расширения markdown, поддержка TOC является одним из них, другие:

Комментарий к коду

Синтаксис такой:

{% code-comment target=element %}
key : value
key : value
{% endcode-comment %}

Для target будет целевой элемент селектора, это может быть <pre> или идентификатор элемента.

А key может быть lineno или ключевые слова, определённые в коде, и это отобразит метку и Когда вы наводите на него мышь, появляется подсказка, содержимое которой берётся из value.

Например:

Сначала определите свой код следующим образом:

from os import path
path.join('a', 'b')

Затем определите комментарий к коду следующим образом:

{% code-comment target=test %}
path : path submodule
2 : line 2
{% endcode-comment %}

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

Включить файл

Иногда вам нужно показать некоторые коды. Один из способов — ввести их непосредственно в документ, используя ```, и т. д. Но в Parm вы также можете включить код из исходного файла, поэтому эта функция будет очень удобна, и даже если код изменится, вам не нужно беспокоиться о синхронизации кода, просто создайте документ снова. И вы можете использовать include для этого.

Основной синтаксис тега include должен быть следующим:

{% include file=filename, lines=lines_range, language=lanaguage, class=class %}
lines_content
{% endinclude %}

file (обязательно): имя исходного файла; его путь будет относиться к текущему файлу документа Markdown.

lines (необязательно): определяет диапазон строк в исходном файле, это может быть несколько диапазонов, например:

```
1-20 30-
```

Это означает, что будут включены строки с номерами от 1 до 20 и от 30.

Поэтому, если вы вообще опустите lines, будет включён весь файл.

```
2 5
```

Также является правильным синтаксисом. Это просто простые шаблоны строк.

language (необязательно): укажите язык.

class (необязательно): дополнительный атрибут class будет добавлен к <pre> тегу. Если вы хотите, чтобы Parm показывал номера строк, вы должны использовать class=linenums. Этот класс используется в библиотеке google highlight js.

lines_content (необязательно): если вы не хотите использовать номера строк для указания диапазона строк кода, вы также можете использовать регулярное выражение, поэтому просто определите его в lines_content.

Формат следующий:

```
begin_regular_expression...begin_regular_expression
```

Символы ... используются для разделения регулярного выражения begin и регулярного выражения end. Можно опустить только одно из них. И строка, соответствующая шаблону begin или end, будет включена в вывод, поэтому, если вы хотите пропустить их, вы можете добавить ! в конце шаблона.

Например, содержимое файла:

```
$(function(){
    $('.div').on('click', function(e){
        e.preventDefault();
        $.ajax({
            url:'/test',
            dataType:'json',
            success:function(result){
                show_message(result);
            }
        });
    });
});
```

```
{% include file=test.js %}
\$\('\.div'\)...\$\.ajax
{% endinclude %}
```

Будет показано следующее:

```
    $('.div').on('click', function(e){
        e.preventDefault();
        $.ajax({
```

Но

```
{% include file=test.js %}
\$\('\.div'\)!...\$\.ajax!
{% endinclude %}
```

Покажет только следующие строки:

```
        e.preventDefault();
```

Лицензия

Данное программное обеспечение выпущено под лицензией BSD.

ДЕМО

Вы можете посмотреть: http://limodou.github.io/parm или http://limodou.github.io/uliweb-doc

OSCHINA-MIRROR/limodou-parm

Установка

Инициализация среды

Создание оглавления

Сборка

Преобразование reStructuredText в Markdown

О программе rst2md

Как добавить поддержку Disqus

Войдите в Disqus и получите встроенные коды

Измените введение Index Info

О теме

Навигация по меню

Как исключить файлы

Как разместить свои документы на страницах github

Markdown Extensions

Комментарий к коду

Включить файл

Лицензия

ДЕМО

Опубликовать ( 0 )

Введение

Обновления

Участники

Недавние действия

OSCHINA-MIRROR/limodou-parm .gitee-modal { min-width: 500px !important; } .gitee-modal .close { right: 0.6rem !important; }

Установка

Инициализация среды

Создание оглавления

Сборка

Преобразование reStructuredText в Markdown

О программе rst2md

Как добавить поддержку Disqus

Войдите в Disqus и получите встроенные коды

Измените введение Index Info

О теме

Навигация по меню

Как исключить файлы

Как разместить свои документы на страницах github

Markdown Extensions

Комментарий к коду

Включить файл

Лицензия

ДЕМО

Опубликовать ( 0 )

Введение

Обновления

Участники

Недавние действия

OSCHINA-MIRROR/limodou-parm