Собираем документацию ProGit, под Windows

Предисловие


Добрый день.

Вот уж, около полгода, наша компания перешла с системы контроля версий SVN на Git. О преимуществах или недостатках я писать не буду, их обсудили не раз. Ребята, которые этим занимались в нашей команде, написали несколько внутренних статей с основными сценариями: создание бранчей, мерджи и т.п.
Но жизнь преподносит свои сюрпризы и выход за основные сценарии всегда обозначался фразой WTF или говоря по русски «я думал Git сделает так, почему он сделал по другому?»

И всё сводилось к тому, что нужно читать документацию по Гиту. (А на чтение документации, всегда нет времени.)
По этому поводу была статья Завершён перевод книги «Pro Git» на хабре.
Но как оказалось, в документацию ещё вносятся изменения. Не часто, но всё же, тут хорошо видно, когда вносились последние.

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

Git + Pandoc + Windows


Для этого нам необходимо установить Git Extensions, в меню Commands выбираем Clone Repository., указывая ссылку на репозиторий 'https://github.com/progit/progit.git'


И жмём Clone.
P.S. Для скачивания доки, используется анонимный доступ, поэтому никаких ключей не потребуется.

Но далее меня ожидал сюрприз, документация оказалась в неизвестном формате markdown, а для того, чтобы создать вариант для EBook, предлагалось сделать так:

Making Ebooks
On Fedora you can run something like this:

$ yum install ruby calibre rubygems ruby-devel rubygem-ruby-debug
$ gem install rdiscount
$ makeebooks en  # will produce a mobi

Перспектива настраивать Линуксовую виртуалку, только лишь для того, чтобы собрать документацию — не радовала. Возможно есть и другие решения, дальше лишь мой велосипед.
О великий интернет! Там на просторах, мне удалось найти утилиту Pandoc, которая может превратить файлы markdown формата, в docx, pdf, txt и т.д.
Возможности и синтаксис можно посмотреть тут.
Скачиваем, устанавливаем, заходим в папку E:\sources.git\!\progit\ru
Если посмотреть, то синтаксис при конвертации простой

pandoc -S  01-introduction\01-chapter1.markdown -o gitbook.docx

Из нюансов:
  1. Нужно было, подхватить при генерации несколько файлов.
  2. Линки на картинки, были указаны в формате
     Insert 18333fig0101.png
     Рисунок 1-1. Схема локальной СУВ.
    
    , а надо
    ![ Рисунок 1-1. Схема локальной СУВ.](..\figures\18333fig0101-tn.png)
    


Поэтому захотелось автоматизировать процесс и был написан VBScript (я не гуру этого языка, мне лишь требовалось решить свою задачу). VBS не так сложен и для решения его вполне хватило.

1. Решается поиском всех файлов в папке с расширением markdown.
2. Решается с помощью RegExp.
Получится такой скрипт:
Const ForReading = 1
Const ForWriting = 2
Const ForAppending = 8

Set objFSO = CreateObject("Scripting.FileSystemObject")
Set objRegEx = CreateObject("VBScript.RegExp")

Dim sCurPath, tempFolder, files
sCurPath = objFSO.GetAbsolutePathName(".")
tempFolder = sCurPath + "\!"

if objFSO.FolderExists(tempFolder) then
    objFSO.DeleteFolder(tempFolder)
end if
objFSO.CreateFolder(tempFolder)

CopyFiles sCurPath, tempFolder

Dim cmd
cmd = "pandoc -S " + files + " -o gitbook.docx"
with createobject("wscript.shell")
  .Run(cmd), 0, True
end with

WScript.Echo("Completed")
 
Function CopyFiles(CurrentFolderName, TempFolderName)
    On Error Resume Next
     
    Dim ObjFolder
    Dim ObjSubFolders
    Dim ObjSubFolder
    Dim ObjFiles
    Dim ObjFile	
 
    Set ObjFolder = objFSO.GetFolder(CurrentFolderName)
    Set ObjFiles = ObjFolder.Files
     
    For Each ObjFile In ObjFiles
    IF objFSO.GetExtensionName(ObjFile.name) = "markdown" Then

        Set openedFile = objFSO.OpenTextFile(ObjFile.Path, ForReading)
        Set outputfile = objFSO.CreateTextFile(TempFolderName + "\" + ObjFile.name, True)

        files = files + "!\" + ObjFile.name + " "
        objRegEx.IgnoreCase = True
        objRegEx.MultiLine = True
        objRegEx.Global = True
        objRegEx.Pattern = "Insert (.*).png\n*\s*(.*)$"

        text = openedFile.ReadAll
        openedFile.Close
        result = objRegEx.Replace(text, "![$2](../figures/$1-tn.png)")
        outputfile.Write result
        outputfile.Close

    End If
    Next
     
    'Getting all subfolders
    Set ObjSubFolders = ObjFolder.SubFolders
     
    For Each ObjFolder In ObjSubFolders
        'Getting all Files from subfolder
        CopyFiles ObjFolder.Path, TempFolderName
    Next
     
End Function


Запускаем скрипт из папки E:\sources.git\!\progit\ru, получаем gitbook.docx.

Заключение


  1. Место откуда запускать скрипт важно, поскольку учитывается путь к картинкам.
  2. Чтобы собрать pdf нужен latex, поэтому не пробовал.
  3. Если файл нужен в другом формате, можно уже использовать другие утилиты, чтобы конвертировать docx в pdf, fb2 и т.д…
  4. Документацию я так читать и не начал, но уже на шаг ближе :).


Cсылки


Скачать доку
Поделиться публикацией

Комментарии 8

    +1
    А где ссылка на уже готовую документацию?)
      0
      Вы правы, добавил в конец статьи.
      0
      > неизвестном формате markdown
      Очень, между прочим, распространённый на github формат. Синтаксис очень прост, переводить в txt просто смешно, т.к. он изначально текстовый и очень понятный :). В html думаю, не особо сложно.
        0
        jakyll же…
        +1
        h3. Гитхаб сам умеет переводить markdown в красивый html

        # Заходим на github.com/progit/progit/tree/master/ru
        # Далее тыкаем на github.com/progit/progit/tree/master/ru/01-introduction
        # А внутри на github.com/progit/progit/blob/master/ru/01-introduction/01-chapter1.markdown
        # PROFIT!!!

        _________________________________________________________________________________

        ps: Простите мой француский, но для каких целей козе баян? У меня просто в голове мысля не помещается — зачем нам в век интернета собирать некую доку в файл — для просмотра в далекой деревне или на самолёте разве?
        pps: Да плюс ещё и на русском, хотя это конечно холивар — не все умеют как тов. Мутко «спикать фром хис харт ин инглиш» :)
          0
          Ну кто на работу на самолёте летает, можно и в самолёте.
          Мне удобнее в метро читать с файла, а не с инета.

          Но за ваш вариант спасибо, про такие изящества не знал.
            0
            но без картинок.
              0
              Insert 18333fig0101.png Рисунок 1-1. Схема локальной СУВ.

              Это минус конечно :(

              Надо с товарищами связаться и предложить добавлять картинки не своим «способом», а markdown-совместимым:

          Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

          Самое читаемое