Ural penguins - Сообщения с тегом reStructuredText

Vim (и не только) для reStructuredText

2015-08-13T17:24:00Z

reStructuredText - очень удобная разметка, которая используется при написании документации (sphinx), README для гитхаба, битбакета, PyPi и всего прочего вплоть до научных статей (пример) или же статей для блога :)

Так-как документация отымает бОльшую часть времени от разработки, то хорошо бы настроить окружение под нее. В конечном счете это сэкономит кучу времени.

TagBar

majutsushi/tagbar - это плагин который показывает тэги документа в отдельном окне. Для настройки нам понадобится добавить его в Vim и установить клавишу вызова (например F8).

.vimrc добавляем tagbar

Plug 'majutsushi/tagbar'
nmap <F8> :TagbarToggle<CR>

Все что tagbar не умеет делать “из коробки” можно подключить в виде отдельных расширений (полный список тут) или написать свое.

Для reStructuredText есть jszakmeister/rst2ctags. Подключается он довольно просто:

клонируем git репу в локальную папку
и указываем путь до нее в .vimrc

.vimrc конфиг rst2ctags

let g:tagbar_type_rst = {
    \ 'ctagstype': 'rst',
    \ 'ctagsbin' : '/home/uralbash/.vim/config/common/rst2ctags/rst2ctags.py',
    \ 'ctagsargs' : '-f - --sort=yes',
    \ 'kinds' : [
        \ 's:sections',
        \ 'i:images'
    \ ],
    \ 'sro' : '|',
    \ 'kind2scope' : {
        \ 's' : 'section',
    \ },
    \ 'sort': 0,
\ }

После этого по нажатию F8 будет открываться “содержание” вашего документа, как показано на рисунках ниже.

Пример jszakmeister/rst2ctags в Vim

Пример jszakmeister/rst2ctags в Vim с более простой структурой разделов

Таким образом упрощается навигация по документу и структурирование разделов.

Riv.vim

Rykka/riv.vim - это что то на подобии python-mode для reStructuredText. Всякие ништяки для rST.

Добавляем Rykka/riv.vim в Vim

Plug 'Rykka/riv.vim', { 'for': 'rst' }

В командном режиме появятся следующие функции:

Riv2BuildPath           RivCreateHyperLink      RivHelpTodo
RivListType2            RivShiftRight           RivTitle2
Riv2HtmlAndBrowse       RivCreateInterpreted    RivInstruction
RivListType3            RivSpecification        RivTitle3
Riv2HtmlFile            RivCreateLink           RivIntro
RivListType4            RivSuperCEnter          RivTitle4
Riv2HtmlProject         RivCreateLiteralBlock   RivItemClick
RivNormEqual            RivSuperEnter           RivTitle5
Riv2Latex               RivCreateLiteralInline  RivItemToggle
RivNormLeft             RivSuperMEnter          RivTitle6
Riv2Odt                 RivCreateStrong         RivLinkNext
RivNormRight            RivSuperSEnter          RivTodoAsk
Riv2Pdf                 RivCreateTime           RivLinkOpen
RivPrimer               RivTableCreate          RivTodoDate
Riv2S5                  RivCreateTransition     RivLinkPrev
RivProjectHtmlIndex     RivTableFormat          RivTodoDel
Riv2Xml                 RivDeleteFile           RivLinkShow
RivProjectIndex         RivTableNextCell        RivTodoPrior
RivCheatSheet           RivDirectives           RivListDelete
RivProjectList          RivTablePrevCell        RivTodoToggle
RivCreateContent        RivFoldAll              RivListNew
RivQuickStart           RivTestFold0            RivTodoType1
RivCreateDate           RivFoldToggle           RivListSub
RivReload               RivTestFold1            RivTodoType2
RivCreateEmphasis       RivFoldUpdate           RivListSup
RivScratchCreate        RivTestObj              RivTodoType3
RivCreateExplicitMark   RivGetLatest            RivListToggle
RivScratchView          RivTestTest             RivTodoType4
RivCreateFoot           RivHelpFile             RivListType0
RivShiftEqual           RivTitle0               RivTodoUpdateCache
RivCreateGitLink        RivHelpSection          RivListType1
RivShiftLeft            RivTitle1               RivVimTest

Плагин имеет множество разных функций которые лучше изучить при помощи команды :RivQuickStart.

Например команда :Riv2HtmlAndBrowse рендерит текущий документ и открывает его в браузере. А сочетание клавиш Ctrl+e s 1 делает текущую строку заголовком 1-го уровня, т.е. выполняет функцию RivTitle1.

rstcheck

myint/rstcheck - это отличный линтер для разметки reStructuredText, также помимо docutils он понимает sphinx-doc директивы и роли.

Установка

$ pip install --upgrade rstcheck

Проверка синтаксиса в директиве `code-block`

rstcheck умеет проверять синтаксис следующих языков в директиве .. code-block:::

Bash
Doctest
C (C99)
C++ (C++11)
JSON
Python
reStructuredText

Например я допустил ошибку в коде на Python:

====
Test
====

.. code-block:: python

    print(

В этом случае линтер ее обнаружит:

$ rstcheck bad_python.rst
bad_python.rst:7: (ERROR/3) (python) unexpected EOF while parsing

Еще пример с C++:

====
Test
====

.. code-block:: cpp

    int main()
    {
        return x;
    }

$ rstcheck bad_cpp.rst
bad_cpp.rst:9: (ERROR/3) (cpp) error: 'x' was not declared in this scope

И пример с опечаткой в rST:

====
Test
===

$ rstcheck bad_rst.rst
bad_rst.rst:1: (SEVERE/4) Title overline & underline mismatch.

Я добавляю rstcheck в travis-ci и после каждого коммита проверяю документацию на наличие ошибок. Пример можно посмотреть здесь.

Конфиг

Про некоторые кастомные роли и директивы rstcheck ничего не знает, что бы они не попадали в поток ошибок их можно заигнорировать при помощи конфига. Файл конфига с именем .rstcheck.cfg должен располагаться в текущей директории, например так:

docs
├── foo
│   └── bar.rst
├── index.rst
└── .rstcheck.cfg

Можно указать какие игнорировать директивы или роли, например для блога я использую некоторые кастомные вещи из модуля расширения ITCase/sphinx-links и ABlog:

[rstcheck]
ignore_directives=post,postlist
ignore_roles=github,l,man,pypi

Модуль для Python

Т.к. rstcheck это Python модуль, его можно использовать в своих скриптах:

>>> import rstcheck
>>> list(rstcheck.check('Example\n==='))
[(2, '(INFO/1) Possible title underline, too short for the title.')]

Vim

Для вима используйте scrooloose/syntastic:

let g:syntastic_rst_checkers = ['rstcheck']

Итог

Пишите документацию в целом и пишите больше в reStructuredText он прекрасен.

Блог в reStructuredText разметке

2015-08-12T12:06:00Z

Перевел тут блог с https://www.blogger.com/ на abakan/ablog. Блоггер это конечно хорошо, но у него крайне ограниченный WYSIWYG, тем более только из браузера. Ablog по сути это sphinx движок заточенный на блог со всеми плюшками, rST разметкой, RSS и disqus комментами.

Профит

Sphinx позволяет автоматизировать многие вещи
reStructuredText позволяет точно и красиво оформлять статьи, это как писать “курсач” в LaTeX заместо MS Office
писать в Vim :)
хоститься где угодно и хранить информацию у себя локально

Установка

Стабильная версия с PyPi

$ pip install ablog

Свежая версия из мастера

$ pip install git+https://github.com/abakan/ablog

Инициализация нового проекта

См.также

http://ablog.readthedocs.org/manual/ablog-quick-start/

Можно добавить настройки в conf.py уже существующего проекта:

# 1. Add 'ablog' to list of extensions
extensions = [
    '...',
    'ablog'
]

# 2. Add ablog templates path
import ablog

# 2a. if `templates_path` is not defined
templates_path = [ablog.get_html_templates_path()]

# 2b. if `templates_path` is defined
templates_path.append(ablog.get_html_templates_path())

Или создать новый проект:

$ ablog start

Сборка и запуск

Что бы собрать блог нужно выполнить:

$ ablog build

HTML страницы создаются в папке _website

Что запустить блог достаточно выполнить:

$ ablog serve

теперь он доступен по адресу http://127:0.0.1:8000/

Статьи

Главная страница блога это index.rst. У меня она выглядит так:

index.rst

.. postlist:: 100500
   :excerpts:
   :date: %d-%m-%Y
   :format: {date} | {title}

Статьи могут находится в любом месте проекта, Ablog их находит автоматически. Я отвожу для этого отдельную папку:

articles/
├── 2011
│   ├── breadcrumbs.rst
│   ├── capslock.rst
│   ├── content_assigment.rst
│   ├── couchdb.rst
│   ├── demo.rst
│   ├── fa_keyerror.rst
│   ├── fa_rest_controller.rst
│   ├── formalchemy.rst
│   ├── java_iceweasel.rst
│   ├── js_rrd.rst
│   ├── peyote.rst
│   ├── psycopg2.rst
│   ├── pylons_backslash.rst
│   ├── pylons_jscss_minificator.rst
│   ├── repoze.what.rst
│   ├── rrd_cut2.rst
│   ├── rrd_cut.rst
│   ├── rrdtool_ds18b20.rst
│   ├── snmp.rst
│   ├── sqlalchemy_mixin.rst
│   ├── sqlalchemy_trigger.rst
│   ├── sqlalchemy_uml.rst
│   ├── sqlalchemy_why_postgres.rst
│   ├── thinkpad_trackpoint.rst
│   ├── wtforms.rst
│   ├── wtform_validation.rst
│   ├── xfce_button.rst
│   └── xfce_display.rst
├── 2012
│   ├── 3com.rst
│   ├── ajax_triple_select.rst
│   ├── arch_book.rst
│   ├── boyan.rst
│   ├── cms_pyramid2.rst
│   ├── cms_pyramid.rst
│   ├── debian_bc.rst
│   ├── fortune.rst
│   ├── http_header_pyramid.rst
│   ├── jinja_pylons_i18n.rst
│   ├── jinja_pyramid_i18n.rst
│   ├── jinja_silent_none.rst
│   ├── lisp_book.rst
│   ├── lisp.rst
│   ├── matplotlib_numpy_and_virtualenv.rst
│   ├── osm_example.rst
│   ├── osm_geotagging.rst
│   ├── paramiko.rst
│   ├── penguin_troll.rst
│   ├── penguin_vs_leo.rst
│   ├── pg_book.rst
│   ├── proxmox.rst
│   ├── proxy_apt.rst
│   ├── pycrypto_virtualenv.rst
│   ├── pylons_console.rst
│   ├── pylons_csv.rst
│   ├── pylons_yapsy.rst
│   ├── pypi.rst
│   ├── pyramid_as_django.rst
│   ├── pyramid_blog.rst
│   ├── pyramid_formalchemy.rst
│   ├── python_labirint.rst
│   ├── python_snmp.rst
│   ├── pyyandexmap.rst
│   ├── qtile.rst
│   ├── redactor-js.rst
│   ├── rrd_faketime.rst
│   ├── rrdtool.rst
│   ├── sa_big_table.rst
│   ├── shared_net.rst
│   ├── sphinx_github.rst
│   ├── sran.rst
│   ├── vi_book.rst
│   └── x220t_buttons.rst
├── 2013
│   ├── car_differ.rst
│   ├── dbsession_includeme.rst
│   ├── flag_jinja2.rst
│   ├── hdaps_music.rst
│   ├── hstore_plpython.rst
│   ├── jinja2_lorem_ipsum.rst
│   ├── linux_attack.rst
│   ├── matrix.rst
│   ├── penguin.rst
│   ├── python_vim.rst
│   ├── reason_names_of.rst
│   ├── sacrud_alfa_0_1_0.rst
│   ├── sacrud_demo.rst
│   ├── sacrud_howto.rst
│   ├── sacrud_release_0_0_3.rst
│   ├── sacrud_release_0_1_0.rst
│   ├── sacrud.rst
│   ├── vi_book.rst
│   ├── vim_book.rst
│   ├── wat.rst
│   └── where_to_start.rst
├── 2014
│   ├── alembic_pyramid.rst
│   ├── chameleon_deform.rst
│   ├── ci.rst
│   ├── cornice.rst
│   ├── django-hyango.rst
│   ├── go.rst
│   ├── ia32-libs-multiarch:i386.rst
│   ├── king_penguin.rst
│   ├── man_month_book.rst
│   ├── panel_pyramid_dt.rst
│   ├── sacrud_release_0.1.1.rst
│   ├── sacrud_release_0.1.2.rst
│   ├── scrum.rst
│   ├── sphinx.rst
│   ├── sqlalchemy_mptt_0_0_5.rst
│   ├── sqlalchemy_mptt.rst
│   └── sqlite_to_pg.rst
└── 2015
    └── ablog.rst

5 directories, 111 files

Что бы файл *.rst стал статьей в нем должна находится директива post. Например:

foo.rst

.. post:: 15 Apr, 2013
   :tags: tips, ablog, directive
   :category: Example, How To
   :author: Ahmet, Durden
   :location: Pittsburgh, SF
   :redirect: blog/old-page-name-for-the-post
   :excerpt: 2
   :image: 1

См.также

http://ablog.readthedocs.org/manual/posting-and-listing/#directive-post

Пример кода этой статьи:

articles/2015/ablog.rst

.. post:: 12 Aug, 2015 12:06
   :tags: Python, reStructuredText, Sphinx
   :category: Python
   :author: Uralbash
   :language: ru

.. _ablog:

Блог в reStructuredText разметке
================================

.. image:: /_static/2015/uralbash.ru.png
   :align: left
   :width: 500px

Перевел тут блог с https://www.blogger.com/ на :github:`abakan/ablog`. Блоггер
это конечно хорошо, но у него крайне ограниченный WYSIWYG, тем более только из
браузера. :l:`Ablog` по сути это :pypi:`sphinx` движок заточенный на блог со
всеми плюшками, rST разметкой, RSS и disqus комментами.

.. raw:: html

   <br clear="both"/>
   <test/>

Профит
------

* :pypi:`Sphinx` позволяет автоматизировать многие вещи
* ``reStructuredText`` позволяет точно и красиво оформлять статьи, это как
  писать "курсач" в LaTeX заместо MS Office
* писать в :l:`Vim` :)
* хоститься где угодно и хранить информацию у себя локально

Установка
---------

.. code-block:: bash
   :caption: Стабильная версия с PyPi

   $ pip install ablog

.. code-block:: bash
   :caption: Свежая версия из мастера

   $ pip install git+https://github.com/abakan/ablog

Инициализация нового проекта
----------------------------

.. seealso::

   http://ablog.readthedocs.org/manual/ablog-quick-start/

Можно добавить настройки в ``conf.py`` уже существующего проекта:

.. code-block:: python

   # 1. Add 'ablog' to list of extensions
   extensions = [
       '...',
       'ablog'
   ]

   # 2. Add ablog templates path
   import ablog

   # 2a. if `templates_path` is not defined
   templates_path = [ablog.get_html_templates_path()]

   # 2b. if `templates_path` is defined
   templates_path.append(ablog.get_html_templates_path())

Или создать новый проект:

.. code-block:: bash

   $ ablog start

Сборка и запуск
---------------

Что бы собрать блог нужно выполнить:

.. code-block:: bash

   $ ablog build

HTML страницы создаются в папке ``_website``

Что запустить блог достаточно выполнить:

.. code-block:: bash

   $ ablog serve

теперь он доступен по адресу http://127:0.0.1:8000/

Статьи
------

Главная страница блога это ``index.rst``. У меня она выглядит так:

.. code-block:: rst
   :caption: index.rst

   .. postlist:: 100500
      :excerpts:
      :date: %d-%m-%Y
      :format: {date} | {title}

Статьи могут находится в любом месте проекта, :l:`Ablog` их находит
автоматически. Я отвожу для этого отдельную папку:

.. code-block:: bash

   articles/
   ├── 2011
   │   ├── breadcrumbs.rst
   │   ├── capslock.rst
   │   ├── content_assigment.rst
   │   ├── couchdb.rst
   │   ├── demo.rst
   │   ├── fa_keyerror.rst
   │   ├── fa_rest_controller.rst
   │   ├── formalchemy.rst
   │   ├── java_iceweasel.rst
   │   ├── js_rrd.rst
   │   ├── peyote.rst
   │   ├── psycopg2.rst
   │   ├── pylons_backslash.rst
   │   ├── pylons_jscss_minificator.rst
   │   ├── repoze.what.rst
   │   ├── rrd_cut2.rst
   │   ├── rrd_cut.rst
   │   ├── rrdtool_ds18b20.rst
   │   ├── snmp.rst
   │   ├── sqlalchemy_mixin.rst
   │   ├── sqlalchemy_trigger.rst
   │   ├── sqlalchemy_uml.rst
   │   ├── sqlalchemy_why_postgres.rst
   │   ├── thinkpad_trackpoint.rst
   │   ├── wtforms.rst
   │   ├── wtform_validation.rst
   │   ├── xfce_button.rst
   │   └── xfce_display.rst
   ├── 2012
   │   ├── 3com.rst
   │   ├── ajax_triple_select.rst
   │   ├── arch_book.rst
   │   ├── boyan.rst
   │   ├── cms_pyramid2.rst
   │   ├── cms_pyramid.rst
   │   ├── debian_bc.rst
   │   ├── fortune.rst
   │   ├── http_header_pyramid.rst
   │   ├── jinja_pylons_i18n.rst
   │   ├── jinja_pyramid_i18n.rst
   │   ├── jinja_silent_none.rst
   │   ├── lisp_book.rst
   │   ├── lisp.rst
   │   ├── matplotlib_numpy_and_virtualenv.rst
   │   ├── osm_example.rst
   │   ├── osm_geotagging.rst
   │   ├── paramiko.rst
   │   ├── penguin_troll.rst
   │   ├── penguin_vs_leo.rst
   │   ├── pg_book.rst
   │   ├── proxmox.rst
   │   ├── proxy_apt.rst
   │   ├── pycrypto_virtualenv.rst
   │   ├── pylons_console.rst
   │   ├── pylons_csv.rst
   │   ├── pylons_yapsy.rst
   │   ├── pypi.rst
   │   ├── pyramid_as_django.rst
   │   ├── pyramid_blog.rst
   │   ├── pyramid_formalchemy.rst
   │   ├── python_labirint.rst
   │   ├── python_snmp.rst
   │   ├── pyyandexmap.rst
   │   ├── qtile.rst
   │   ├── redactor-js.rst
   │   ├── rrd_faketime.rst
   │   ├── rrdtool.rst
   │   ├── sa_big_table.rst
   │   ├── shared_net.rst
   │   ├── sphinx_github.rst
   │   ├── sran.rst
   │   ├── vi_book.rst
   │   └── x220t_buttons.rst
   ├── 2013
   │   ├── car_differ.rst
   │   ├── dbsession_includeme.rst
   │   ├── flag_jinja2.rst
   │   ├── hdaps_music.rst
   │   ├── hstore_plpython.rst
   │   ├── jinja2_lorem_ipsum.rst
   │   ├── linux_attack.rst
   │   ├── matrix.rst
   │   ├── penguin.rst
   │   ├── python_vim.rst
   │   ├── reason_names_of.rst
   │   ├── sacrud_alfa_0_1_0.rst
   │   ├── sacrud_demo.rst
   │   ├── sacrud_howto.rst
   │   ├── sacrud_release_0_0_3.rst
   │   ├── sacrud_release_0_1_0.rst
   │   ├── sacrud.rst
   │   ├── vi_book.rst
   │   ├── vim_book.rst
   │   ├── wat.rst
   │   └── where_to_start.rst
   ├── 2014
   │   ├── alembic_pyramid.rst
   │   ├── chameleon_deform.rst
   │   ├── ci.rst
   │   ├── cornice.rst
   │   ├── django-hyango.rst
   │   ├── go.rst
   │   ├── ia32-libs-multiarch:i386.rst
   │   ├── king_penguin.rst
   │   ├── man_month_book.rst
   │   ├── panel_pyramid_dt.rst
   │   ├── sacrud_release_0.1.1.rst
   │   ├── sacrud_release_0.1.2.rst
   │   ├── scrum.rst
   │   ├── sphinx.rst
   │   ├── sqlalchemy_mptt_0_0_5.rst
   │   ├── sqlalchemy_mptt.rst
   │   └── sqlite_to_pg.rst
   └── 2015
       └── ablog.rst

   5 directories, 111 files

Что бы файл ``*.rst`` стал статьей в нем должна находится директива ``post``.
Например:

.. code-block:: rst
   :caption: foo.rst

   .. post:: 15 Apr, 2013
      :tags: tips, ablog, directive
      :category: Example, How To
      :author: Ahmet, Durden
      :location: Pittsburgh, SF
      :redirect: blog/old-page-name-for-the-post
      :excerpt: 2
      :image: 1

.. seealso::

   http://ablog.readthedocs.org/manual/posting-and-listing/#directive-post

Пример кода этой статьи:

.. literalinclude:: /articles/2015/ablog.rst
   :language: rst
   :caption: articles/2015/ablog.rst

Тема
----

Тема по умолчанию `Alabaster <https://github.com/bitprophet/alabaster>`_, но
можно поменять стандартными способами в ``conf.py``:

.. no-code-block:: python
   :caption: conf.py установка темы

   import itcase_sphinx_theme

   ...

   # -- Options for HTML output ----------------------------------------------

   # The theme to use for HTML and HTML Help pages.  See the documentation for
   # a list of builtin themes.
   html_theme = 'itcase'

   # Theme options are theme-specific and customize the look and feel of a theme
   # further.  For a list of options available for each theme, see the
   # documentation.
   html_theme_options = {
       'github_button': False,
   }

   # Add any paths that contain custom themes here, relative to this directory.
   html_theme_path = [itcase_sphinx_theme.get_html_themes_path()]

   # The name for this set of Sphinx documents.  If None, it defaults to
   # "<project> v<release> documentation".
   html_title = "Ural penguins"

Я использую :github:`ITCase/itcase_sphinx_theme` с переопределенными шаблонами.
Для этого нужно указать где искать шаблоны и в каком порядке:

.. code-block:: python
   :caption: conf.py указание пути по шаблонов темы

   # Add any paths that contain templates here, relative to this directory.
   templates_path = ['_templates', ablog.get_html_templates_path()]

Добавляем в папку ``_templates`` нашего проекта шаблон ``layout.html``:

.. literalinclude:: /_templates/layout.html
   :language: html+jinja
   :caption: _templates/layout.html

Комменты
--------

.. seealso::

   http://ablog.readthedocs.org/manual/ablog-configuration-options/#disqus-integration

DISQUS ставится просто:

.. code-block:: python
   :caption: настройки DISQUS

   # -- disqus integration -------------------------------------------------------

   # you can enable disqus_ by setting ``disqus_shortname`` variable.
   # disqus_ short name for the blog.
   disqus_shortname = "uralbash"

Правда у меня завелось только после переопределения шаблона ``page.html``:

.. literalinclude:: /_templates/page.html
   :language: html+jinja
   :caption: _templates/page.html
   :emphasize-lines: 37

Деплой
------

.. note::

   http://ablog.readthedocs.org/manual/deploy-to-github-pages/

#. Создать репу с именем ``<username>.github.io``
#. Добавить имя в настройки, например:

   .. code-block:: python
      :caption: conf.py настройки github pages

      github_pages = "uralbash"

#. Сбилдить проект:

   .. code-block:: bash

      $ ablog build

#. Выложить на гитхаб:

   .. code-block:: bash

      $ ablog deploy

Итог
----

На мой взгляд лучшее решения для ``reStructuredText`` блога, местами сырой, но
активно развивается.

Тема

Тема по умолчанию Alabaster, но можно поменять стандартными способами в conf.py:

conf.py установка темы

import itcase_sphinx_theme

...

# -- Options for HTML output ----------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
html_theme = 'itcase'

# Theme options are theme-specific and customize the look and feel of a theme
# further.  For a list of options available for each theme, see the
# documentation.
html_theme_options = {
    'github_button': False,
}

# Add any paths that contain custom themes here, relative to this directory.
html_theme_path = [itcase_sphinx_theme.get_html_themes_path()]

# The name for this set of Sphinx documents.  If None, it defaults to
# "<project> v<release> documentation".
html_title = "Ural penguins"

Я использую ITCase/itcase_sphinx_theme с переопределенными шаблонами. Для этого нужно указать где искать шаблоны и в каком порядке:

conf.py указание пути по шаблонов темы

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates', ablog.get_html_templates_path()]

Добавляем в папку _templates нашего проекта шаблон layout.html:

_templates/layout.html

{% extends "base.html" %}

{% block breadcrumbs %}
  <div class="head" style="background-image: url('/_static/bg.jpg');
                  background-size: 100%;
                  background-repeat: no-repeat;
                  height: 200px">
    <a href="/">
      <div style="width:100%; height: 75%">
        <h1 style="padding-top:15px;padding-left:15px;font-size:60px">Ural penguins</h1>
      </div>
    </a>
    <table style="
        border-collapse: unset !important;
        border-spacing: 1 !important;">
        <tr>
            <td style="padding-right: 2px">
                <a href="/pages/pyramid/index.html">
                    <div style="background: white;width:100px;height:50px;line-height:50px;text-align:center;"
                        onmouseover="this.style.background='lightgrey';" onmouseout="this.style.background='white';">
                        Pyramid
                    </div>
                </a>
            </td>
            <td>
                <a href="/pages/nixos/index.html">
                    <div style="background: white;width:100px;height:50px;line-height:50px;text-align:center;"
                        onmouseover="this.style.background='lightgrey';" onmouseout="this.style.background='white';">
                        NixOS
                    </div>
                </a>
            </td>
        </tr>
    </table>
  </div>

    <script async src="//pagead2.googlesyndication.com/pagead/js/adsbygoogle.js"></script>
    <div class="badge" style="width:100%;height:80px">
    <!-- uralbash.ru -->
    <ins class="adsbygoogle"
         style="display:block"
         data-ad-client="ca-pub-2884502571619359"
         data-ad-slot="9876011339"
         data-ad-format="auto"></ins>
    <script>
    (adsbygoogle = window.adsbygoogle || []).push({});
    </script>
    </div>
{% endblock %}

{% block extrahead %}
  <style type="text/css">
    html, body {
      background: #545d5c !important;
    }
    .page__left .menu {
        width: 0px;
    }
    .page__right {
      background-color: #e7e7e7;
      margin: 0 0 0 30px;
    }
    .rst-content {
      padding: 13px;
    }
    .footer {
      padding: 13px;
    }
    /* unvisited link */
    ul.postlist-style-none a:link, .head a:link {
        color: #222;
        text-decoration: none;
    }

    /* visited link */
    ul.postlist-style-none a:visited, .head a:visited {
        color: #222;
        text-decoration: none;
    }

    /* mouse over link */
    ul.postlist-style-none a:hover, .head a:hover {
        color: #222;
        text-decoration: none;
    }

    ul.postlist-style-none a:active, .head a:active {
        color: #222;
        text-decoration: none;
    }
    ul.postlist-style-none li {
        list-style-type: none;
    }
    ul.postlist-style-none li p.first {
      color: red !important;
      font: 1.8em "Open Sans",Arial,sans-serif !important;
    }
    .first a {
      font-weight: bold;
    }
    .first em {
      font-style: normal !important;
    }
    .wrapper__inner {
      padding: 0px 30px 0 0 !important;
    }
    .strike {
      text-decoration: line-through;
    }
  </style>
{% endblock %}

{% block footer %}
  {{ super() }}
  <div class="footer__theme">
      <a href="https://github.com/sunpy/ablog" class="footer__theme-link">
        Ablog powered.
      </a>
  </div>
  <div class="footer__theme">
      <a href="http://uralbash.ru/blog/atom.xml" class="footer__theme-link">
        RSS/Atom
      </a>
  </div>
  <div class="footer__theme">
      <a href="https://uralbash.blogspot.com" class="footer__theme-link">
        Старый блог
      </a>
  </div>
{% endblock %}

Комменты

См.также

http://ablog.readthedocs.org/manual/ablog-configuration-options/#disqus-integration

DISQUS ставится просто:

настройки DISQUS

# -- disqus integration -------------------------------------------------------

# you can enable disqus_ by setting ``disqus_shortname`` variable.
# disqus_ short name for the blog.
disqus_shortname = "uralbash"

Правда у меня завелось только после переопределения шаблона page.html:

_templates/page.html

{%- extends "layout.html" %}
{% set fa = ablog.fontawesome %}
{%- block extrahead %}
  {{ super() }}
  {% if atom_feed %}
  <link rel="alternate" type="application/atom+xml"  href="{{ pathto(feed_path, 1) }}/atom.xml" title="{{ ablog.blog_title }}">
  {% endif %}
  {% if ablog.fontawesome_link_cdn%}
  <link href="http://netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.min.css" rel="stylesheet">
  {% elif ablog.fontawesome_css_file %}
  <link rel="stylesheet" href="{{ pathto('_static/' + ablog.fontawesome_css_file, 1) }}" type="text/css" />
  {% endif %}
  <style type="text/css">
    ul.ablog-archive {list-style: none; overflow: auto; margin-left: 0px}
    ul.ablog-archive li {float: left; margin-right: 5px; font-size: 80%}
    ul.post-list-style-disc {list-style-type: disc;}
    ul.post-list-style-none {list-style-type: none;}
    ul.post-list-style-circle {list-style-type: circle;}
  </style>
{% endblock %}

{% block body %}
  <script type="text/javascript" src="//yastatic.net/share/share.js" charset="utf-8"></script>
  <table>
    <tr>
      <td>
        <div class="yashare-auto-init" data-yashareL10n="ru"
          data-yashareType="medium"
          data-yashareQuickServices="vkontakte,facebook,twitter,odnoklassniki,moimir,gplus"
          data-yashareTheme="counter"></div>
      </td>
      <td>
        {% include "my_postcard.html" %}
      </td>
    </tr>
  </table>
  {{ body }}
  <div class="section">
  {% if pagename in ablog %}
    {% include "postnavy.html" %}
  {% endif %}
 {%- if not internal_build and (pagename != 'index') %}
  {# {% if ablog.disqus_shortname and ablog.blog_baseurl and ((pagename in ablog and (ablog[pagename].published or ablog.disqus_drafts)) or (not pagename in ablog and ablog.disqus_pages)) %} #}
    <div class="section">
    <br />
    <script type="text/javascript" src="//yastatic.net/share/share.js" charset="utf-8"></script><div class="yashare-auto-init" data-yashareL10n="ru" data-yashareType="medium" data-yashareQuickServices="vkontakte,facebook,twitter,odnoklassniki,moimir,gplus" data-yashareTheme="counter"></div>
    <h2>Comments</h2>

    <div id="disqus_thread"></div>
    <script type="text/javascript">
        /* * * CONFIGURATION VARIABLES: EDIT BEFORE PASTING INTO YOUR WEBPAGE * * */
        var disqus_shortname = '{{ ablog.disqus_shortname }}'; // required: replace example with your forum shortname
        var disqus_identifier = '{{ablog.page_id(pagename)}}';
        var disqus_title = '{{title|e}}';
        {# var disqus_url = '{{ablog.page_url(pagename)}}'; #}
        /* * * DON'T EDIT BELOW THIS LINE * * */
        (function() {
            var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
            dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js';
            (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
        })();
    </script>
    <noscript>Please enable JavaScript to view the <a href="http://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
    <a href="http://disqus.com" class="dsq-brlink">comments powered by <span class="logo-disqus">Disqus</span></a>
    </div>
  {% endif %}
  </div>
{% endblock %}

Деплой

Примечание

http://ablog.readthedocs.org/manual/deploy-to-github-pages/

Создать репу с именем <username>.github.io
Добавить имя в настройки, например:
conf.py настройки github pages
```
github_pages = "uralbash"
```
Сбилдить проект:
```
$ ablog build
```
Выложить на гитхаб:
```
$ ablog deploy
```

Итог

На мой взгляд лучшее решения для reStructuredText блога, местами сырой, но активно развивается.

Документация python проекта на практике

2014-09-22T15:15:00Z

Документация в python проектах пишется при помощи sphinx, он умеет используя расширение automodule читать докстринги и формировать документацию из кода.

Создать проект можно ответив на вопросы через sphinx-quickstart или использовать уже подготовленный шаблон который генерит дополнительно API пакета:

$ sphinx-apidoc -F -o docs sacrud

Creating file docs/sacrud_deform.rst.
Creating file docs/sacrud_deform.tests.rst.
Creating file docs/conf.py.
Creating file docs/index.rst.
Creating file docs/Makefile.
Creating file docs/make.bat.

Автогенератор API обычно создает много лишнего и далеко не идеально генерит названия, поэтому удалим API тестов и попереимеуем все остальное.

Для сборки доков нужно в папке docs выполнить make html. Ниже структура получившихся файлов:

.
├── _build
│   ├── doctrees
│   │   ├── environment.pickle
│   │   ├── index.doctree
│   │   ├── readme.doctree
│   │   ├── sacrud_deform.doctree
│   │   └── sacrud_deform.tests.doctree
│   └── html
│       ├── genindex.html
│       ├── index.html
│       ├── _modules
│       │   ├── index.html
│       │   ├── sacrud_deform
│       │   │   ├── tests
│       │   │   │   └── test_form.html
│       │   │   └── widgets.html
│       │   └── sacrud_deform.html
│       ├── objects.inv
│       ├── py-modindex.html
│       ├── readme.html
│       ├── sacrud_deform.html
│       ├── sacrud_deform.tests.html
│       ├── search.html
│       ├── searchindex.js
│       ├── _sources
│       │   ├── index.txt
│       │   ├── readme.txt
│       │   ├── sacrud_deform.tests.txt
│       │   └── sacrud_deform.txt
│       └── _static
│           ├── ajax-loader.gif
│           ├── basic.css
│           ├── comment-bright.png
│           ├── comment-close.png
│           ├── comment.png
│           ├── default.css
│           ├── doctools.js
│           ├── down.png
│           ├── down-pressed.png
│           ├── file.png
│           ├── jquery.js
│           ├── minus.png
│           ├── plus.png
│           ├── pygments.css
│           ├── searchtools.js
│           ├── sidebar.js
│           ├── underscore.js
│           ├── up.png
│           ├── up-pressed.png
│           └── websupport.js
├── conf.py
├── index.rst
├── make.bat
├── Makefile
├── readme.rst
├── sacrud_deform.rst
├── _static
└── _templates

В директории build/html находится наша готовая документация в формате html. Добавим описание проекта на основную страницу. Для этого создаем readme.rst в директории docs и включаем его в index.rst, а в дальнейшем этот же readme.rst будет использоваться в README.rst в корне проекта для github и PyPi.

readme.rst

|Build Status| |Coverage Status| |Stories in Progress| |PyPI|

.. |Build Status| image:: https://travis-ci.org/ITCase/sacrud_deform.svg?branch=master
   :target: https://travis-ci.org/ITCase/sacrud_deform
.. |Coverage Status| image:: https://coveralls.io/repos/ITCase/sacrud_deform/badge.png?branch=master
   :target: https://coveralls.io/r/ITCase/sacrud_deform?branch=master
.. |Stories in Progress| image:: https://badge.waffle.io/ITCase/sacrud_deform.png?label=in%20progress&title=In%20Progress
   :target: http://waffle.io/ITCase/sacrud_defrom
.. |PyPI| image:: http://img.shields.io/pypi/dm/sacrud_deform.svg
   :target: https://pypi.python.org/pypi/sacrud_deform/

sacrud_deform
==============

Form generotor for SQLAlchemy models.

Install
=======

develop version from source

.. code-block:: bash

  pip install git+git://github.com/ITCase/sacrud_deform@develop

from pypi

.. code-block:: bash

  pip install sacrud_deform

Use
===

.. code-block:: python

        data = form_generator(dbsession=DBSession,
                                   obj=obj_of_model, table=MyModel,
                                   columns=columns_of_model)
        form, js_list = data.render()

Здесь вроде все понятно, но есть нюансы, если например в директиве .. code-block не указать язык или не дописывать “=” в заголовках то документация будет нормально генериться, но PyPi её не поймет и выведет что-то типа этого:

Нужно быть внимательным и проверять как PyPi подхватил README.rst. Дальше в наш index.rst добавим readme.rst что бы он был по презентабельнее.

index.rst

Welcome to sacrud_deform's documentation!
=========================================

.. include:: readme.rst

Contents:

.. toctree::
   :maxdepth: 4

   sacrud_deform


Indices and tables
==================

+ :ref:`genindex`
+ :ref:`modindex`
+ :ref:`search`

Теперь главная страница документации выглядит так:

В принципе уже хорошо, добавим это описание ещё для github и PyPi. Они по умолчанию берут файл README.rst из корня проекта и ничего про папку docs не знают. Можно было бы заинклудить readme.rst в корневой README.rst (..include:: docs/readme.rst), но github и PyPi инклуды не понимают, поэтому придется писать свой велосипед для копирования. Либо тупо делать это вручную. Я написал на коленке простой скрипт который это делает и заменяет директивы include содержанием их файлов.

make_README.py

import fileinput
import os
from shutil import copyfile

src = "readme.rst"
src_path = os.path.dirname(os.path.realpath(src))
dst = "../README.rst"
copyfile(src, dst)


def read_file(path):
    with open(path, 'r') as f:
        return f.read()

for line in fileinput.input(dst, inplace=1):
    splitted = line.rstrip().split('.. include:: ')
    if len(splitted) == 2:
        line = read_file(os.path.join(src_path, splitted[1]))
        print line
    else:
        print line.rstrip()

Теперь если запустить из папки docs команду python make_README.py, то в корне проекта появится или перезапишется файл README.rst.

Что бы это делалось автоматически при каждой сборке документации добавим в Makefile:

...

readme:
 python make_README.py

readme_html: html readme

При вызове make readme_html у нас будет собираться документация html и копипаститься readme.

Конфиг для sphinx лежит в папке документации с названием conf.py. В нем можно настраивать документацию как угодно, к примеру оформим тему как у проекта Pyramid.

Добавим в conf.py:

conf.py

import sys
import os

# Add and use Pylons theme
if 'sphinx-build' in ' '.join(sys.argv):  # protect against dumb importers
    from subprocess import call, Popen, PIPE

    p = Popen('which git', shell=True, stdout=PIPE)
    git = p.stdout.read().strip()
    cwd = os.getcwd()
    _themes = os.path.join(cwd, '_themes')

    if not os.path.isdir(_themes):
        call([git, 'clone', 'git://github.com/Pylons/pylons_sphinx_theme.git',
              '_themes'])
    else:
        os.chdir(_themes)
        call([git, 'checkout', 'master'])
        call([git, 'pull'])
        os.chdir(cwd)

    sys.path.append(os.path.abspath('_themes'))

    parent = os.path.dirname(os.path.dirname(__file__))
    sys.path.append(os.path.abspath(parent))
    wd = os.getcwd()
    os.chdir(parent)
    os.chdir(wd)

    for item in os.listdir(parent):
        if item.endswith('.egg'):
            sys.path.append(os.path.join(parent, item))

Этот код я скопировал из проекта Pyramid, он просто выкачивает их тему с github в директорию _themes. Далее укажем в конфиге название темы и где их искать.

# -- Options for HTML output ----------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for

# a list of builtin themes.

html_theme = 'pyramid'

# Add any paths that contain custom themes here, relative to this directory.

html_theme_path = ['_themes']

После сборки проект будет выглядеть так:

Вообщем конфиг умеет много чего, есть еще много разных расширений, можно писать свои, либо переопределять/добавлять директивы итд. Вот например как вставлять ссылки на сторонние проекты:

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions += [
    'sphinx.ext.intersphinx'
]

intersphinx_mapping = {
    'sacrud': ('http://sacrud.readthedocs.org/en/latest/', None),
}

Теперь можно писать так:

Use :py:class:`sacrud.common.TableProperty` decorator.

И наверно последний этап это добавление документации на readthedocs. Сложностей там особо нету, регаешься, добавляешь гитхаб профиль, синхронизируешь репы и выбираешь нужные. Хук на коммиты в таком случае вешается автоматически, единственное что нужно отметить что если в документации используется automodule нужно ставить галку virtualenv (в настройках readthedocs) иначе он просто будет пустым.

Готовый пример можно посмотреть здесь http://sacrud-deform.readthedocs.org/en/develop/

Хостим документацию Sphinx на github

2012-04-12T18:55:00Z

Немного допиленная версия этого http://djangonaut.blogspot.com/2009/05/sphinx-documentation-github-pages-3.html

По порядку:

создать репозитарий на github
добавить туда свой локальный репозитарий с проектом Sphinx
захостить репозитарий через сервис Pages
поправить Makefile в Sphinx проекте

docs_dir = doc
ghdocs:
 rm -rf $(docs_dir)
 $(MAKE) clean
 $(MAKE) html
 cp -r build/html $(docs_dir)
 mv $(docs_dir)/_static $(docs_dir)/static
 mv $(docs_dir)/_sources $(docs_dir)/sources
 perl -pi -e "s/_sources/sources/g;" $(docs_dir)/*.html
 perl -pi -e "s/_static/static/g;" $(docs_dir)/*.html
 git add .
 git commit -a -m "Updates $(project)."
 git checkout gh-pages
 cp -rf $(docs_dir)/* .
 git add .
 git commit -a -m 'Updates $(project) documentation.'
 git checkout master
 rm -rf $(docs_dir)
 git push origin gh-pages

Теперь при запуске make ghdocs будет автоматом генерироваться новая документация и пушаться на github.

Пример здесь http://uralbash.github.com/python-web-lectures/

Для автоматической замены директорий _static и _sources, можно установить модуль sphinxtogithub.

$ pip install sphinxtogithub

И добавить в проекте в config.py:

config.py

extensions = ["sphinxtogithub", ]

В этом случае нужно закомментировать в скрипте строчки:

mv $(docs_dir)/_static $(docs_dir)/static

mv $(docs_dir)/_sources $(docs_dir)/sources

Это необходимо делать потому-что github не понимает директории начинающиеся с подчеркивания.

Ural penguins - Сообщения с тегом reStructuredText

Vim (и не только) для reStructuredText

TagBar

Riv.vim

rstcheck

Установка

Проверка синтаксиса в директиве code-block

Конфиг

Модуль для Python

Vim

Итог

Блог в reStructuredText разметке

Профит

Установка

Инициализация нового проекта

Сборка и запуск

Статьи

Тема

Комменты

Деплой

Итог

Документация python проекта на практике

Хостим документацию Sphinx на github

Проверка синтаксиса в директиве `code-block`