https://github.com/lightbend/sbt-paradox-apidoc
Apidoc (javadoc and scaladoc) support for the project documentation tool paradox
https://github.com/lightbend/sbt-paradox-apidoc
Last synced: about 1 year ago
JSON representation
Apidoc (javadoc and scaladoc) support for the project documentation tool paradox
- Host: GitHub
- URL: https://github.com/lightbend/sbt-paradox-apidoc
- Owner: lightbend
- License: apache-2.0
- Created: 2018-04-12T14:11:03.000Z (about 8 years ago)
- Default Branch: main
- Last Pushed: 2025-01-23T09:56:15.000Z (over 1 year ago)
- Last Synced: 2025-04-07T04:36:08.192Z (about 1 year ago)
- Language: Scala
- Homepage:
- Size: 269 KB
- Stars: 4
- Watchers: 8
- Forks: 10
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# sbt-paradox-apidoc
A [paradox](https://github.com/lightbend/paradox/) directive that automatically adds links for classes from documentation to scaladoc and javadoc.
## Usage
Add the plugin:
```scala
addSbtPlugin("com.lightbend.paradox" % "sbt-paradox-apidoc" % "")
```
Configure the `apidocRootPackage` within your paradox settings:
```
import com.lightbend.paradox.apidoc.ApidocPlugin.autoImport.apidocRootPackage
(...)
apidocRootPackage := "akka",
(...)
```
You can now create 'grouped' javadoc/scaladoc references in paradox like:
```
Look into the documentation for @apidoc[MyClass].
```
This will automatically find the FQCN of the class when it is unique. When the
name does not uniquely identify the class, the plugin will check for the
`scaladsl`/`javadsl` package convention found in Akka projects. If that doesn't
produce an unambigious result, you will have to use the FQCN.
## Examples
[See details in the tests](/src/test/scala/com/lightbend/paradox/apidoc/ApidocDirectiveSpec.scala)
* `@apidoc[Actor]` (Just one class exists.)
* classes: `akka.actor.Actor`
* Scala: `Actor` - `akka/actor/Actor.html`
* Java: `Actor` - `akka/actor/Actor.html`
* `@apidoc[Flow]` (Both scaladoc and javadoc exist.)
* classes: `akka.stream.scaladsl.Flow` - `akka.stream.javadsl.Flow`
* Scala: Flow - `akka/stream/scaladsl/Flow.html`
* Java: Flow - `akka/stream/javadsl/Flow.html`
* `@apidoc[Receptionist.Command]` (An inner class.)
* classes: `akka.actor.typed.receptionist.Receptionist$Command`
* Scala: Receptionist.Command - `akka/actor/typed/receptionist/Receptionist$$Command.html`
* Java: Receptionist.Command - `akka/actor/typed/receptionist/Receptionist.Command.html`
* `@apidoc[Marshaller]` (The scaladoc/javadoc split can be on different package depth.)
* classes: `akka.http.scaladsl.marshalling.Marshaller`, `akka.http.javadsl.marshalling.Marshaller`
* Scala: Marshaller - `akka/http/scaladsl/marshalling/Marshaller.html`
* Java: Marshaller - `akka/http/javadsl/marshalling/Marshaller.html`
* `@apidoc[typed.*.Replicator$]` (The classes exist in multiple places.)
* classes: `akka.cluster.ddata.Replicator$`, `akka.cluster.ddata.typed.scaladsl.Replicator$`, `akka.cluster.ddata.typed.javadsl.Replicator$`
` * Scala: Replicator - `akka/cluster/ddata/typed/scaladsl/Replicator$.html`
* Java: Replicator - `akka/cluster/ddata/typed/javadsl/Replicator.html`
* `@apidoc[akka.stream.(javadsl|scaladsl).Concat]` (The classes exist in even more places.)
* classes: `akka.stream.impl.Concat`, `akka.stream.scaladsl.Concat$`, `akka.stream.scaladsl.Concat`, `akka.stream.javadsl.Concat$`
* Scala: Concat - `akka/stream/scaladsl/Concat.html`
* Java: Concat - `akka/stream/javadsl/Concat.html`
* `@apidoc[ClusterClient$]` (Link to scala object.)
* classes: `akka.cluster.client.ClusterClient`
* Scala: ClusterClient - `akka/cluster/client/ClusterClient$.html`
* Java: ClusterClient - `akka/cluster/client/ClusterClient.html`
* `@apidoc[Source[ServerSentEvent, \_]]` (Show type parameters.)
* classes: `akka.stream.scaladsl.Source` - `akka.stream.javadsl.Source`
* Scala: Source\[ServerSentEvent, _\] - `akka/stream/scaladsl/Source.html`
* Java: Source\ - `akka/stream/javadsl/Source.html`
* `@apidoc[TheClass.method](Flow)` (Different link text than the class name.)
* classes: `akka.stream.scaladsl.Flow` - `akka.stream.javadsl.Flow`
* Scala: TheClass.method
`akka/stream/scaladsl/Flow.html`
* Java: TheClass.method
`akka/stream/javadsl/Flow.html`
* `@apidoc[method](Flow) { scala="#method():Unit" java="#method()" }` (Link to method anchors.)
* classes: `akka.stream.scaladsl.Flow` - `akka.stream.javadsl.Flow`
* Scala: method - `akka/stream/scaladsl/Flow.html#method():Unit`
* Java: method - `akka/stream/javadsl/Flow.html#method()`
* `@apidoc[method](Flow) { scala="#method[T]():Unit" java="#method()" }` (Link to method anchors.)
* classes: `akka.stream.scaladsl.Flow` - `akka.stream.javadsl.Flow`
* Scala: method - `akka/stream/scaladsl/Flow.html#method[T]():Unit`
* Java: method - `akka/stream/javadsl/Flow.html#method()`
* `@apidoc[method](Flow) { scala="#method%5BT%3C:S]():Unit" java="#method()" }` (Link to method anchors. Where the method has type bounds.)
* classes: `akka.stream.scaladsl.Flow` - `akka.stream.javadsl.Flow`
* Scala: method - `akka/stream/scaladsl/Flow.html#method[T<:S]():Unit`
* Java: method - `akka/stream/javadsl/Flow.html#method()`
* `@apidoc[method](Flow) { scala="#method(String=%3EInt):Unit" java="#method()" }` (Link to method anchors. Using higher-order function arguments)
* classes: `akka.stream.scaladsl.Flow` - `akka.stream.javadsl.Flow`
* Scala: method - `akka/stream/scaladsl/Flow.html#method(String=>Int):Unit`
* Java: method - `akka/stream/javadsl/Flow.html#method()`
### When only Scaladoc is generated
If the project does not publish Javadoc, the corresponding Javadoc base URL can be cleared and the Java links will point to the `javadsl` package in the Scaladocs.
Example:
```scala
"javadoc.akka.stream.alpakka.base_url" -> ""
```
## License
The license is Apache 2.0, see LICENSE.
## Maintanance notes
**This project is NOT supported under the Lightbend subscription.**