Sphinx HTML Çıktılarını Otomatik Olarak GitHub Pages'e Göndermek

Sphinx ile HTML, EPUB ve PDF gibi pek çok biçimde çıktı almak mümkün. EPUB ve PDF gibi tek dosyalık çıktıları paylaşması kolay olsa da HTML gibi onlarca dosyadan oluşan çıktıları başkalarıyla paylaşmak kendi internet siteniz yoksa biraz zor.

Burada imdadımıza GitHub Pages yetişiyor. Ama her seferinde internet sayfalarını GitHub Pages'e göndermek için gh-pages dalına geçmek, kaynak metinleri çekmek, çalışılan kopyayı temizlemek ve tekrar master'a dönmek gibi birden çok işlem yapılması gerekiyor. Bu, bir seferden sonra sıkıcı gelecek bir iş. Bu yüzden otomatikleştirilmesi elzem.

libuv'un geliştiricisi tüm bunları bizden daha önce düşündüğü için yapmamız gerekenler sadece küçük bir uyarlamadan ibaret olacak ve sadece şu komutu çalıştırmamız kafi gelecek:

make gh-pages

Bu komutu çalıştırmadan önce unutmamanız gereken yaptığınız tüm değişiklikleri kaynak deponuza göndermek veya değişikliklerinizi geri almak.

Ayrıca bu güzel ve işinizi kolaylaştıracak komutu kullanmaya başlamadan önce sadece tek seferlik çalıştırmanız gereken komutlar var:

$ cd repo
$ git checkout --orphan gh-pages
$ git rm -rf .
$ echo "First commit" > index.html
$ git add .
$ git commit -m "Just to create the branch."
$ git push origin gh-pages

Bu işlemleri farklı bir dizinde yapın, deponuzun ana dizininde değil. Ben yanlışlıkla böyle yaptığım için birkaç da silme yapmam gerekti. Dizinle işiniz bittiğinde silebilirsiniz. Bundan sonra tüm işlemleri yine deponuzun kendi dizininde yapabilirsiniz.

Şimdi gh-pages dalımızın kurulumu tamamlandı, oluşturduğumuz geçici index.html dosyasını silip, gerçek sayfalarımızı yüklemeye hazırız.

GH_PAGES_SOURCES isimli bir değişken ekleyerek Makefile dosyasındaki değişikliklere başlayalım. Bu değişken belgelendirme kaynak dosya ve dizinlerini içerecek. Bu genellikle .rst uzantılı dosyaların bulunduğu dizin olacaktır ama belgelerinizde harici kodlar ve resim dosyaları da kullanıyorsanız bunları da belirtmelisiniz. Bu değişkenin libuv kitabındaki şekli aşağıdaki gibi:

GH_PAGES_SOURCES = source code libuv Makefile

Ben de şu şekilde değiştirerek kullanıyorum:

GH_PAGES_SOURCES = icerik Makefile

Makefile dosyasında boşluk yerine sekme kullanmayı unutmadan gh-pages isminde bir hedef oluşturuyoruz şimdi de:

gh-pages:
    git checkout gh-pages
    rm -rf build _sources _static
    git checkout master $(GH_PAGES_SOURCES)
    git reset HEAD
    make html latexpdf epub
    mv -fv build/html/* ./
    mv -fv build/latex/AnIntroductiontolibuv.pdf "./An Introduction to libuv.pdf"
    mv -fv build/epub/AnIntroductiontolibuv.epub "./An Introduction to libuv.epub"
    rm -rf $(GH_PAGES_SOURCES) build
    git add -A
    git ci -m "Generated gh-pages for `git log master -1 --pretty=short --abbrev-commit`" && git push origin gh-pages ; git checkout master

Kendi projenizde yararlanırken elinizde birden çok örnek olabilmesi için benim uyarladığım küçük bazı değişiklikler içeren halini de ekliyorum:

gh-pages:
    git checkout gh-pages
    rm -rf _build
    git checkout master $(GH_PAGES_SOURCES)
    git reset HEAD
    make html
    rsync -avh _build/html/* ./
    rm -rf $(GH_PAGES_SOURCES) _build
    git add -A
    git commit -v -m "Generated gh-pages for `git log master -1 --pretty=short --abbrev-commit`" && git push origin gh-pages ; git checkout master

Şimdi kısaca neler döndüğünü anlatmaya çalışayım. Bildiğiniz gibi artık iki dalımız var, birincisi asıl belgelendirmeyi oluşturduğumuz master dalı, ikincisi de bu belgelerden elde ettiğimiz HTML çıktılarını yayınladığımız gh-pages dalı.

checkout komutuyla dalı değiştiriyoruz. Sonrasında eski verileri silerek, belge oluşturulması sırasında bunların kullanılmayacağından emin oluyoruz. gh-pages dalı HTML çıktılarından başka hiçbir veriye sahip olmadığı için bunları master dalından çekiyoruz. Daha sonra da bunlardan HTML çıktısını oluşturuyor ve oluşturduğumuz HTML dosyalarını inşa dizininden gh-pages dalının ana dizinine taşıyoruz. Sonra tüm kaynak dizinlerini ve artık içinde hiçbir şey kalmamış olan inşa dizinini siliyoruz. En son olarak da tüm değişiklerin depoya ulaşmasını sağlıyoruz.

İşte bu kadar. Tüm bunlarla her seferinde tek tek uğraşmak yerine asıl amacınız olan belge yazmaya yoğunlaşabilirsiniz. Belgenizi diğerleriyle paylaşmak için kullanabileceğiniz aslanlar gibi bir make gh-pages komutunuz var ne de olsa artık.

Bu yazının yıldızları için:

Yorumlar

Bu blogdaki popüler yayınlar

Diğer Dillerde Hoşçakal

Fedora 24'te GRUB 2 Önyükleyici Temasını Değiştirme

Müfettiş Gadget'taki Kötü Adamın Yüzü Açığa Çıkmış