Comments (12)
References #187
I'm interested in working on this. Should I try to land the tooling upstream in Paradox or do we want to iterate on it in this project before suggesting a fix for lightbend/paradox#26
from akka-http.
In my investigation so far I didn't manage to get a Scaladoc preprocessor working. These are the main examples I've looked at so far:
- https://github.com/szeiger/extradoc
- https://github.com/todesking/sbt-custom-doclet and https://github.com/todesking/scala-json-doclet
I wonder if for the Scala directives it would be in scope to use scala.meta or the approach of sbt-doctest to extract the directive scaladoc and the directive signature? That is we would be able to copy paste the markdown to the scaladoc but keep the directives documentation more or less as it currently is. This was why I created lightbend/paradox#26 although I should probably have discussed this here first.
from akka-http.
I think we should do the processing directly on the source files (probably through sbt). It is important that the published source artifact also contains all the examples because many if not most people will read the scaladoc either through an IDE (which will pick up the documentation from the source files) or by reading the source code to which the IDE will link to.
from akka-http.
First prototype for the scala side is here using jonas/akka-http@14b744a
A couple of notes:
- Basic directives should be split into multiple groups to match its overview page
- In the Scaladoc basic directives comes first but we should probably tweak
groupprio
to use the order in the listing by trait - Navigating the directive docs is somewhat painful since you completely loose context (at least in Chrome) when clicking a link to another directive and go back afterwards.
Next step will be to generate that code and feed it to unidoc.
from akka-http.
It would be interesting to see if the new scaladoc (example of the new output here) might fix some usability issues.
from akka-http.
I will try. That would be a good excuse to configure cross building for Scala 2.12.
from akka-http.
๐ An old version of the akka docs generated with 2.12 can be found here: akka-docs.virtual-void.net
from akka-http.
OK, got a bit further using scalameta to extract signatures and comments. This would require to have the tooling separate from sbt (until version 1.0) since scalameta only supports 2.11+.
from akka-http.
@jonas, scalafmt had the same issue, where it was not possible to use scalafmt from an sbt plugin because of the scalameta dependency. Until they have removed sbt plugin they had a workaround using a custom ivy configuration and instantiating needed classes via reflection. I have not looked into it in detail, but could be something, that might help to get it integrated into the build pipeline more seamlessly.
from akka-http.
Thanks for the pointers @2m. I briefly looked at scalafmt and its sbt plugin during prototyping but decided it was more fun to play with scalameta and figure out how to deal with running it later.
from akka-http.
@jonas It seems to be possible to use sbt 0.13.13 synthetic projects to run 2.11/2.12 code in sbt plugins. It's quite simple as long as you don't pass around too many parameters from the build. See https://github.com/olafurpg/scalafmt/issues/597#issuecomment-263054478 for an example implementation.
from akka-http.
@olafurpg Thanks, I will give it a try.
from akka-http.
Related Issues (20)
- Internal server error triggered by โAccept-Charsetโ header with unexpected value HOT 4
- Not possible to load project in IntelliJ 2023.2.1 HOT 1
- Duplicated 100 responses if there is an exception thrown by the unmarshaller HOT 1
- Several HTTP/2 client settings are never used anywhere
- failed: RouteDirectivesSpec -> should allow easy handling of futured ToResponseMarshallers
- Cannot Unmarshall Seq[String] Outside HOT 1
- Release 10.6.0-M1
- Release 10.6.0-M2
- CVE-2023-44487 HOT 3
- Release 10.5.3
- Release 10.6.0
- Failed: Http2ClientSpec should send RST_STREAM if entity stream is canceled HOT 2
- Failed: Http2ServerSpec send RST_STREAM if entity stream is canceled
- Remove dependency on `sbt-dependency-graph` HOT 1
- Release 10.6.1
- Failed: Native image tests HOT 1
- SSE (and maybe more) marshalling/unmarshalling require classic system HOT 1
- fail: CI is failing to publish docs HOT 2
- The akka.http.cors package is not exist HOT 1
- Release 10.6.2
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. ๐๐๐
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google โค๏ธ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from akka-http.