TensorFlow, belge katkılarını memnuniyetle karşılar; belgeleri iyileştirirseniz, TensorFlow kitaplığının kendisini de geliştirirsiniz. Tensorflow.org'daki belgeler aşağıdaki kategorilere ayrılır:
- API referansı — API referans belgeleri , TensorFlow kaynak kodundaki belge dizilerinden oluşturulur.
- Anlatı belgeleri —Bunlar öğreticiler , kılavuzlar ve TensorFlow kodunun parçası olmayan diğer yazılardır. Bu belge tensorflow/docs GitHub deposundadır.
- Topluluk çevirileri —Bunlar, topluluk tarafından çevrilen kılavuzlar ve öğreticilerdir. Tüm topluluk çevirileri tensorflow/docs deposunda yaşar.
Bazı TensorFlow projeleri , dokümantasyon kaynak dosyalarını kodun yanında, genellikle bir
docs/ dizinde ayrı bir havuzda tutar. Projenin
CONTRIBUTING.md dosyasına bakın veya katkıda bulunmak için bakıcıyla iletişime geçin.
TensorFlow dokümanlar topluluğuna katılmak için:
API referansı
Ayrıntılar için TensorFlow API belgeleri katılımcı kılavuzunu kullanın. Bu, kaynak dosyayı nasıl bulacağınızı ve sembolün belge dizisini nasıl düzenleyeceğinizi gösterir. Tensorflow.org'daki birçok API referans sayfası, sembolün tanımlandığı kaynak dosyaya bir bağlantı içerir. Belge dizileri Markdown'ı destekler ve (yaklaşık olarak) herhangi bir Markdown önizleyicisi kullanılarak önizlenebilir .
Sürümler ve dallar
Sitenin API referans sürümü varsayılan olarak en son kararlı ikili dosyadır; bu,
pip install tensorflow ile yüklenen paketle eşleşir.
Varsayılan TensorFlow paketi, ana tensorflow/tensorflow deposundaki kararlı
rX.x dalından oluşturulmuştur. Başvuru belgeleri Python , C++ ve Java kaynak kodundaki kod yorumlarından ve belge dizilerinden oluşturulur.
TensorFlow belgelerinin önceki sürümleri, TensorFlow Docs deposunda rX.x dalları olarak mevcuttur. Bu dallar, yeni bir sürüm yayınlandığında eklenir.
API belgeleri oluşturun
Python referansı
tensorflow_docs paketi, Python API referans belgeleri için oluşturucuyu içerir. Yüklemek:
pip install git+https://github.com/tensorflow/docs
TensorFlow 2 referans belgelerini oluşturmak için
tensorflow/tools/docs/generate2.py betiğini kullanın:
git clone https://github.com/tensorflow/tensorflow tensorflow
cd tensorflow/tensorflow/tools/docs
pip install tensorflow
python generate2.py --output_dir=/tmp/out
anlatı belgeleri
TensorFlow kılavuzları ve öğreticileri , Markdown dosyaları ve etkileşimli Jupyter not defterleri olarak yazılmıştır. Not defterleri, Google Colaboratory kullanılarak tarayıcınızda çalıştırılabilir. Tensorflow.org'daki anlatı belgeleri, tensorflow /docs
master dalından oluşturulmuştur. GitHub'da
rX.x yayın dallarında daha eski sürümler mevcuttur.
Basit değişiklikler
Markdown dosyalarında doğrudan belge güncellemeleri yapmanın en kolay yolu GitHub'ın web tabanlı dosya düzenleyicisini kullanmaktır. Tensorflow.org URL yapısına kabaca karşılık gelen Markdown'ı bulmak için tensorflow/docs deposuna göz atın. Dosya görünümünün sağ üst köşesindeki kalem simgesini tıklayın. Dosya düzenleyiciyi açmak için Dosyayı düzenleyin ve ardından yeni bir çekme isteği gönderin.
Yerel bir Git deposu kurun
Çok dosyalı düzenlemeler veya daha karmaşık güncellemeler için, bir çekme isteği oluşturmak üzere yerel bir Git iş akışı kullanmak daha iyidir.
Aşağıdaki Git adımları yalnızca yerel bir projeyi ilk kurduğunuzda gereklidir.
tensorflow/docs deposunu çatallayın
Tensorflow/docs GitHub sayfasında Çatal düğmesini tıklayın GitHub hesabınız altında kendi repo kopyanızı oluşturmak için. Bir kez çatallandığında, depo kopyanızı yukarı akış TensorFlow deposuyla güncel tutmaktan siz sorumlusunuz.
Deponuzu klonlayın
Uzak username /docs deponuzun bir kopyasını yerel makinenize indirin. Bu, değişiklik yapacağınız çalışma dizini:
git clone email@example.com:username/docs
cd ./docs
Güncel kalmak için bir yukarı akış deposu ekleyin (isteğe bağlı)
Yerel
tensorflow/docs ile senkronize tutmak için, en son değişiklikleri indirmek üzere bir yukarı akış uzaktan kumandası ekleyin.
Uzaktan kumanda ekleyin:
git remote add upstream firstname.lastname@example.org:tensorflow/docs.git# View remote repos
git remote -vorigin email@example.com:username/docs.git (fetch) origin firstname.lastname@example.org:username/docs.git (push) upstream email@example.com:tensorflow/docs.git (fetch) upstream firstname.lastname@example.org:tensorflow/docs.git (push)
Güncellemek için:
git checkout master
git pull upstream master
git push# Push changes to your GitHub account (defaults to origin)
GitHub iş akışı
1. Yeni bir şube oluşturun
tensorflow/docs güncelledikten sonra, yerel ana daldan yeni bir dal oluşturun:
git checkout -b feature-name
git branch# List local branches master * feature-name
2. Değişiklikler yapın
Dosyaları favori düzenleyicinizde düzenleyin ve lütfen TensorFlow dokümantasyon stil kılavuzunu takip edin.
Dosya değişikliğinizi gerçekleştirin:
# View changes
git status# See which files have changed
git diff# See changes within files
git add path/to/file.md
git commit -m "Your meaningful commit message for the change."
Gerekirse daha fazla taahhüt ekleyin.
3. Bir çekme isteği oluşturun
Yerel şubenizi uzak GitHub deponuza yükleyin (github.com/ username /docs):
git push
İletme tamamlandıktan sonra, yukarı akış deposuna otomatik olarak bir çekme isteği göndermek için bir mesaj bir URL görüntüleyebilir. Değilse, tensorflow/docs deposuna veya kendi deponuza gidin; GitHub sizden bir çekme isteği oluşturmanızı ister.
4. Gözden Geçirme
Bakımcılar ve diğer katkıda bulunanlar, çekme talebinizi gözden geçirecektir. Lütfen tartışmaya katılın ve istenen değişiklikleri yapın. Çekme isteğiniz onaylandığında, yukarı akış TensorFlow dokümanlar deposuyla birleştirilir.
GitHub deposundan tensorflow.org'u güncellemek için ayrı bir yayınlama adımı vardır. Tipik olarak, değişiklikler bir araya toplanır ve site düzenli bir kadansta güncellenir.
Etkileşimli not defterleri
Not defteri JSON dosyasını GitHub'ın web tabanlı dosya düzenleyicisiyle düzenlemek mümkün olsa da, hatalı biçimlendirilmiş JSON dosyayı bozabileceğinden önerilmez. Bir çekme isteği göndermeden önce not defterini test ettiğinizden emin olun.
Google Colaboratory , dizüstü bilgisayar belgelerini düzenlemeyi ve çalıştırmayı kolaylaştıran, barındırılan bir not defteri ortamıdır. GitHub'daki not defterleri, örneğin GitHub'da bulunan not defteri gibi Colab URL'sine giden yol iletilerek Google Colab'a yüklenir: https://github.com/tensorflow/docs/blob/master/site/en/tutorials/keras /classification.ipynb
şu URL'den Google Colab'a yüklenebilir: https://colab.research.google.com/github/tensorflow/docs/blob/master/site/en/tutorials/keras/classification.ipynb
GitHub'da bir not defterine göz atarken bu URL değiştirme işlemini gerçekleştiren bir Colab'de Aç Chrome uzantısı vardır. Bu, depo çatalınızda bir not defteri açarken kullanışlıdır, çünkü üst düğmeler her zaman TensorFlow Docs
master dalına bağlanır.
Defter biçimlendirme
Bir not defteri biçimlendirme aracı, Jupyter not defteri kaynak farklarını tutarlı ve gözden geçirilmesini kolaylaştırır. Not defteri yazma ortamları dosya çıktısı, girinti, meta veri ve diğer belirtilmemiş alanlar açısından farklılık gösterdiğinden;
nbfmt , TensorFlow docs Colab iş akışı için bir tercihle birlikte düşünülmüş varsayılanları kullanır. Bir not defterini biçimlendirmek için TensorFlow docs not defteri araçlarını kurun ve
nbfmt aracını çalıştırın:
# Install the tensorflow-docs package: $ python3 -m pip install -U [--user] git+https://github.com/tensorflow/docs $ python3 -m tensorflow_docs.tools.nbfmt [options] notebook.ipynb [...]
TensorFlow doküman projeleri için çıktı hücresi olmayan not defterleri yürütülür ve test edilir; kaydedilmiş çıktı hücrelerine sahip not defterleri olduğu gibi yayınlanır.
nbfmt , not defteri durumuna uyar ve çıktı hücrelerini açıkça kaldırmak için
--remove_outputs seçeneğini kullanır.
Yeni bir not defteri oluşturmak için TensorFlow docs not defteri şablonunu kopyalayın ve düzenleyin.
Colab'da düzenle
Google Colab ortamında, metin ve kod bloklarını düzenlemek için hücreleri çift tıklayın. Metin hücreleri Markdown kullanır ve TensorFlow docs stil kılavuzunu takip etmelidir.
Dosya > İndir .pynb ile Colab'den not defteri dosyalarını indirin. Bu dosyayı yerel Git deponuza gönderin ve bir çekme isteği gönderin.
Yeni bir not defteri oluşturmak için TensorFlow not defteri şablonunu kopyalayın ve düzenleyin.
Colab-GitHub iş akışı
Bir not defteri dosyası indirmek ve yerel bir Git iş akışı kullanmak yerine, çatallı GitHub deponuzu doğrudan Google Colab'dan düzenleyebilir ve güncelleyebilirsiniz:
- Çatallı username /docs deponuzda, yeni bir dal oluşturmak için GitHub web kullanıcı arayüzünü kullanın.
- Düzenlemek için not defteri dosyasına gidin.
- Not defterini Google Colab'da açın: URL takasını veya Colab'de Aç Chrome uzantısını kullanın.
- Not defterini Colab'da düzenleyin.
- Değişiklikleri, Colab'den Dosya > GitHub'a bir kopyasını kaydet... ile deponuza uygulayın. Kaydet iletişim kutusu uygun depoya ve şubeye bağlanmalıdır. Anlamlı bir taahhüt mesajı ekleyin.
- Kaydettikten sonra deponuza veya tensorflow/docs deposuna göz atın, GitHub sizden bir çekme isteği oluşturmanızı ister.
- Çekme isteği, bakımcılar tarafından gözden geçirilir.
Çeviriler
TensorFlow ekibi, tensorflow.org için çeviriler sağlamak için topluluk ve satıcılarla birlikte çalışır. Not defterlerinin ve diğer teknik içeriğin çevirileri tensorflow/docs-l10n GitHub deposunda bulunur. Lütfen çekme isteklerini TensorFlow GitLocalize projesi aracılığıyla gönderin.
İngilizce belgeler gerçeğin kaynağıdır ve çeviriler bu kılavuzları mümkün olduğunca yakından takip etmelidir. Bununla birlikte, hizmet ettikleri topluluklar için çeviriler yazılır. İngilizce terminoloji, ifade, stil veya ton başka bir dile çevrilmiyorsa, lütfen okuyucuya uygun bir çeviri kullanın.
Dil desteği, site metrikleri ve talebi, topluluk desteği, İngilizce yeterliliği , izleyici tercihi ve diğer göstergeler dahil ancak bunlarla sınırlı olmamak üzere bir dizi faktör tarafından belirlenir. Desteklenen her dilin bir maliyeti olduğundan, bakımı yapılmayan diller kaldırılır. Yeni diller için destek TensorFlow blogunda veya Twitter'da duyurulacak.
Tercih ettiğiniz dil desteklenmiyorsa, açık kaynak katkıda bulunanlar için bir topluluk çatalı sağlayabilirsiniz. Bunlar tensorflow.org'da yayınlanmaz.