New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs improvements: Auto Type class hierarchy graphs #1125

Merged
merged 6 commits into from Nov 16, 2018

Conversation

Projects
None yet
4 participants
@raulraja
Copy link
Member

raulraja commented Nov 15, 2018

This PR adds a hierarchy graph to each of the type class documents which is driven by arrow-reflect, ank:outFile new directive and the nomnoml js library.

Ex. on MonadCombine:

monadcombine

  1. We use arrow-reflect as the source of data where we extract the type class hierarchy.
  2. The doc site provides functions that turn these reflect calls into a nomnoml diagram that looks like the example below.
  3. These functions to construct the diagram are invoked by ank through kotlin:ank:outFile(fileName) directive which replaces the code fence entirely with an empty string and writes the result of the evaluated code into the specified file.
  4. The diagram file is stored alongside the page and loaded by the nomnoml js library to render the actual diagram on an html canvas.

All processing except the chart rendering happens at build time since it runs in the ank process.

Ex: Nomnoml generated code:

#font: monoidregular
#arrowSize: 1
#bendSize: 0.3
#direction: down
#gutter: 5
#edgeMargin: 0
#edges: rounded
#fillArrows: false
#fontSize: 10
#leading: 1.25
#lineWidth: 1
#padding: 8
#spacing: 40
#stroke: #485C8A
#title: MonadCombine
#zoom: 1
#.typeclass: fill=#FFFFFF visual=class bold
[<typeclass>MonadCombine|separate|unite]
[<typeclass>MonadFilter]<-[<typeclass>MonadCombine]
[<typeclass>Alternative]<-[<typeclass>MonadCombine]
[<typeclass>Monad]<-[<typeclass>MonadFilter]
[<typeclass>FunctorFilter]<-[<typeclass>MonadFilter]
[<typeclass>Applicative]<-[<typeclass>Monad]
[<typeclass>Functor]<-[<typeclass>Applicative]
[<typeclass>Invariant]<-[<typeclass>Functor]
[<typeclass>Functor]<-[<typeclass>FunctorFilter]
[<typeclass>Applicative]<-[<typeclass>Alternative]
[<typeclass>MonoidK]<-[<typeclass>Alternative]
[<typeclass>SemigroupK]<-[<typeclass>MonoidK]

Produces

monadcombine

@raulraja

This comment has been minimized.

Copy link
Member

raulraja commented on 22b51ac Nov 15, 2018

screen shot 2018-11-15 at 1 56 52 am

This comment has been minimized.

Copy link
Member

calvellido replied Nov 15, 2018

So cool!

This comment has been minimized.

Copy link

juanpedromoreno replied Nov 15, 2018

👏 👏

@raulraja raulraja requested a review from arrow-kt/maintainers Nov 15, 2018


private val lineSeparator: String = System.getProperty("line.separator")
private val lineSeparator: String = "\n" //System.getProperty("line.separator")

This comment has been minimized.

@pakoito

pakoito Nov 15, 2018

Member

Cleanup!

@pakoito
Copy link
Member

pakoito left a comment

Approved! Awesome work, the docs will get a massive quality jump.

@codecov

This comment has been minimized.

Copy link

codecov bot commented Nov 15, 2018

Codecov Report

Merging #1125 into master will increase coverage by <.01%.
The diff coverage is 44.73%.

Impacted file tree graph

@@             Coverage Diff              @@
##             master    #1125      +/-   ##
============================================
+ Coverage     42.78%   42.78%   +<.01%     
  Complexity      813      813              
============================================
  Files           400      400              
  Lines         10977    11000      +23     
  Branches       1248     1256       +8     
============================================
+ Hits           4696     4706      +10     
- Misses         5919     5927       +8     
- Partials        362      367       +5
Impacted Files Coverage Δ Complexity Δ
...les/ank/arrow-ank/src/main/kotlin/arrow/ank/ank.kt 0% <ø> (ø) 0 <0> (ø) ⬇️
...arrow-ank/src/main/kotlin/arrow/ank/interpreter.kt 0% <0%> (ø) 0 <0> (ø) ⬇️
...rc/main/kotlin/arrow/reflect/TypeClassExtension.kt 77.41% <62.5%> (-7.2%) 3 <0> (ø)
...reflect/src/main/kotlin/arrow/reflect/TypeClass.kt 75% <70%> (-25%) 1 <0> (ø)
...tics/src/main/kotlin/arrow/optics/instances/map.kt 91.66% <0%> (+2.77%) 0% <0%> (ø) ⬇️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update b5d9e9b...4eb2d3b. Read the comment docs.

@raulraja raulraja merged commit b8acbbc into master Nov 16, 2018

2 checks passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
continuous-integration/travis-ci/push The Travis CI build passed
Details
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment