Kaynak nereye yerleştirilir, ör. görüntüleri, bu scaladoc kullanabilir?

Question

Şu anda Scala'da yazılmış bir API'nın belgelerini yazıyorum. Kodu daha anlaşılır hale getirmek için birkaç diyagramı dahil etmek istiyorum.

Scaladoc'un bir çağrısıyla otomatik olarak alınabilmesi için kaynakları (şemalar gibi) nereye koyacağımı ve kodun belgelerinde bu kaynaklara nasıl başvuracağımı merak ediyorum. Örneğin, sbt kullandığımı varsayalım. Kodum src/main/scala dizininde bulunur. 'Diyagram-foo.svg' sırayla projemde yer almalıdır

/** 
* Provides main classes of the bar API. 
* 
* ==Overview== 
* Main classes are depicted on the following diagram: 
* <img src="path/to/diagram-foo.svg" /> 
* 
*/ 
package object foo { 
} 

scaladoc görünür olmasını: İşte paketin foo için scala paketi nesnesinin bir örnektir? Daha sonra, img etiketindeki path/to/ etiketinin doğru değeri nedir?

Answer 1

UYARI Scaladoc hakkında çok az şey bildiğimden bir kesmek olabilir.

<img src="../path/to/diagram-foo.svg" /> yalnızca normal bir HTML olduğundan, yalnızca img'un düzeltilmesi için gerekli varlıkları belge hedef yoluna kopyalamanız yeterlidir.

(doc in Compile) ve src/main/doc-resources dizini ile istediğiniz copyDocAssetsTask özel görevini kullanabilirsiniz. Nokta, dokümantasyonun üretildiği dizine, yani (target in (Compile, doc)).value görüntü kopyalamaktır.

build.sbt:

lazy val copyDocAssetsTask = taskKey[Unit]("Copy doc assets") 

copyDocAssetsTask := { 
    println("Copying doc assets") 
    val sourceDir = file("src/main/doc-resources") 
    val targetDir = (target in (Compile, doc)).value 
    IO.copyDirectory(sourceDir, targetDir) 
} 

copyDocAssetsTask <<= copyDocAssetsTask triggeredBy (doc in Compile) 

Açıkçası dizin görüntüleri yer keyfi olduğunu ve aksi karar verirken, sadece buna göre özel bir görev güncelleyin.

Answer 2

sayesinde özellikle çok modül projeler üzerinde başkalarına, yardımcı olabilecek umarım bu bir uyarlamasını kullandı:

Birincisi, https://github.com/sbt/sbt-unidoc de unidoc tek bir konumda çok modüllü projelerin adresinin scaladoc birleşecek, hangi tipik olarak ne istersen. Ardından build.sbt aşağıdaki:

lazy val copyDocAssetsTask = taskKey[Unit]("Copy unidoc resources") 

copyDocAssetsTask := { 
    println("Copying unidoc resources") 
    val sourceDir = file("src/main/doc-resources") 
    val targetDir = (target in (Compile, doc)).value.getParentFile 
    println(s"from ${sourceDir.getAbsolutePath} to ${targetDir.getAbsolutePath}") 
    IO.copyDirectory(sourceDir, new java.io.File(targetDir, "unidoc")) 
} 

copyDocAssetsTask := (copyDocAssetsTask triggeredBy (unidoc in Compile)).value 

sonra bu sadece kaydeder (diyagram dahil etmek scaladoc ile sınıfa yolu için paket yapısı aşağıdaki alt dizinleri kök projesi yılında src/main/doc-resources altına belgelerinizi koymak senin scaladoc

örn içinde

<img src="DesignModel.svg" width="98%"/>: sizin gibi URL'ye ana dizinleri etrafında karışıklık) ve gömmek şeye sahip Bu scaladoc, çok modüllü yapıdaki herhangi bir projede com.someone.thing paketinde bir sınıftaysa, DesignModel.svg dosyası, kök projesinin içinde src/main/doc-resources/com/someone/thing içeriğine gider.