Mkdocs, bu açık kaynaklı yazılım sayesinde dokümantasyon oluşturun

Bir sonraki yazıda Mkdocs'a bir göz atacağız. Yazılım geliştirir ve ararsanız dokümantasyon oluşturmak için bir platform projelerinizden biri için. Veya personel için dahili belgeler oluşturması gereken bir şirkette çalışıyorsanız. Bazı notları kaydetmek isteyen ileri düzey bir kullanıcı olsanız bile. MkDocs, denemeniz gereken bir araçtır.

Bu yazılım, dokümantasyon platformları oluşturmayı amaçlayan statik bir site üreticisidir. Oldukça basit, bakması güzel ve kurulumu ve dağıtımı kolay. Dır-dir python ile yazılmış ve basitçe dosyalarınızı Markdown biçiminde oluşturmanızı gerektirir. Ardından, tek bir YAML yapılandırma dosyası kullanarak, sizin için çalışan statik bir web sitesi oluşturabilirsiniz.

Daha sonra, MkDocs kullanarak eksiksiz bir dokümantasyon web sitesi edinmenin ne kadar kolay olduğunu göreceğiz. Daha birçokları var site üreteçleri benzer statik, ama bu en basitinin bir konfigürasyonuna ve uygulamasına sahiptir.

Normal bir kullanıcı da bu yazılımı şu amaçlarla kullanabilir: not almak için yerel bir platform oluşturun kendisi veya benzeri herhangi bir şey için.

MkDocs'u yükleyin

Yerel olarak yükleyin

MkDocs'u kurmanın oldukça kolay olduğunu görelim. Yapabileceğiz pip kullanarak kurun. Sadece bir terminal açmanız (Ctrl + Alt + T) ve içine yazmanız yeterlidir:

pip install mkdocs

Kurulumdan sonra, çalışma dizininizde aşağıdaki komutu çalıştırın. bir site başlatmak:

mkdocs new mkdocspro

Ve sonra hizmet etmeye başla Çalıştırmak:

cd mkdocspro

mkdocs serve

O zaman yapabilirsin localhost'a git: 8000 (veya 8000 numaralı bağlantı noktalı IP adresiniz / ana bilgisayar adınız) MkDocs'un nasıl çalıştığını görmek için.

Nginx sunucunuza yükleyin

Bu statik bir site oluşturucu olduğundan, PHP veya Python gibi arka uç motoruna gerek yok. MkDocs projesini bir dakika içinde web sunucunuzda (nginx, apache2) uygulayabileceksiniz. Örneğin, işte nginx sanal ana bilgisayar yapılandırması:

server {
        server_name ejemplo.com;

        root /var/www/mkdocspro/sitio;
        index index.html;

        location / {
                try_files $uri $uri/ =404;
        }
}

Değiştirir ejemplo.com sunucunuzda sahip olduğunuz etki alanıyla. Ayrıca değiştirmek zorunda kalacaksın / var / www / mkdocspro / site sunucunuzdaki sitenin alt klasörünün yolu ile. O zaman sadece sahibiz nginx'i yeniden başlat aşağıdaki komutla:

sudo service nginx restart

Şimdi example.com'a gidebilir ve işe yaradığını görebilirsiniz.

Mkdocs'ta başka bir tema yükleyin

Varsayılan Mkdocs teması özellikle iyi değil. Ancak bir dakika içinde başka bir tane kurabilirsiniz. Başka bir temanın kurulumuna bir örnek aşağıdaki gibi olacaktır. Hangi ile gidiyoruz malzeme teması yükle:

pip install mkdocs-material

Kurulumdan sonra temayı etkinleştirmek için yapmanız gerekecek mkdocs.yml dosyanızı düzenleyin ve buna benzer hale getirin. Bazı seçenekler eklenebilir:

site_name: Proyecto MkDocs
site_url: 'http://ejemplo.com'
repo_url: 'https://github.com/nombreusuario/proyectourlongithub'
edit_uri: edit/master
site_description: 'Aquí una descripción corta.'
google_analytics: ['UA-xxxxxxxxx-x', 'ejemplo.com']
extra:
  favicon: 'https://ejemplo/favicon.png'
  social:
    - type: 'github'
      link: 'https://github.com/xxxxxx'
    - type: 'facebook'
      link: 'https://facebook.com/xxxxxxx'
    - type: 'twitter'
      link: 'https://twitter.com/xxxxxxx'
  disqus: 'minombredisqus'
  theme: 'material'

Seçenekler oldukça açık. Ama işte bazı açıklamalar:

• repo_url: Git kod deposu URL'si. Git'i doğrudan MkDocs projenize entegre etmeyi planlıyorsanız, insanların sayfaları düzenlemesine veya projeyi çatallamasına izin vermek için bu seçeneği kullanabilirsiniz.
• edit_uri: Bu GitHub'da sayfaları düzenlemek için postfix. GitLab veya GitBucket kullanıyorsanız bunu değiştirebilirsiniz.
• google_analytics: MkDocs için kontrol paneli yoktur. Bu nedenle bilmek web sitenizi kim ziyaret ederse, Google Analytics kullanmalısınız. Bu seçenek, hesabınızı web sitesiyle ilişkilendirmek için takip numaranızı girmenize olanak sağlar.
• disqus: İstersen Disqus yorum sistemini etkinleştir web sitesinde kısa adınızı buraya yazabilirsiniz.
• tema: kullanmak istediğiniz temanın adı. Materyal temasında yaptığımız gibi, daha önce yüklemeniz gerekecek. Örnekte kullanacağımız isim bu olacaktır.

Yeni temadaki değişiklikleri görün

Dosyayı kaydettikten sonra, mkdocs derlemesini mkdocsproject klasörünün içinde çalıştırın. Web siteniz, Materyal temasının varsayılan görünümünü benimseyecektir:

Önemli: her değişiklikten sonra her zaman mkdocs build çalıştırdığınızdan emin olun dosyalarda yaptığınız. Aksi takdirde herhangi bir değişiklik görmeyeceksiniz.

çok var diğer temalar ve seçenekler Bu yazılımı yapılandırmak için. Onlara şuradan danışabilirsiniz: resmi belgeler MkDocs tarafından. İşte listesi olası seçenekler kullanabileceğimiz.