search

atnos-org / eff

Eff monad for cats - https://atnos-org.github.io/eff
MIT License
582 stars 78 forks source link

sbt-microsites based documentation for eff? #89

Closed pjan closed 7 years ago

pjan commented 7 years ago

I often struggle with browsing the eff documentation. At the same time, contributing to the documentation is not straightforward.

Any plans on moving to sbt-microsites (which also uses tut)?

etorreborre commented 7 years ago

No there is no plan like that. Last time I used tut I found it really slow because it was interpreting the doc all the time. What is your main struggle with the current documentation (which I think needs to be reorganised)?

pjan commented 7 years ago

Main thing I struggle with is navigation; not all pages are well-linked, some pages only have a link at the bottom of a single one, some pages require a lot of scrolling.

Sure, microsites or tut have some time/compilation overhead, but the number of times you evaluate this is limited, and publishing can be fully automated through github/travis.

reactormonk commented 7 years ago

So the feature request is a good navbar?

benhutchison commented 7 years ago

On specific doc request from me is ability to link to the individual docs for bundled effects, I'd like to be able to send someone a link to the eg "Choose" effect.

http://atnos-org.github.io/eff/org.atnos.site.OutOfTheBox.html#choose does work (when not already on the same page), but it currently isnt very discoverable (such as having a nav menu)

etorreborre commented 7 years ago

This works ok for me with Chrome. Which browser are you using?

benhutchison commented 7 years ago

Im using Chrome. It only worked if I wasn't already in another part the same page (which I was and thus mistakenly concluded it didnt work). But nav links to these sections headings would be fine.

etorreborre commented 7 years ago

@benhutchison I have added a search box + a navigation tree.

benhutchison commented 7 years ago

👍 the menu really helps to see everything that's available. Reminded me about the Cookbook. I must write an example using Monix tasks for that once Ive figured out the best way to control async boundaries ...

Search is a work in progress... I tried searching for term "bracket"; matches the correct page but just takes to "Out of the Box" heading.

etorreborre commented 7 years ago

Yes that could be improved :-). I am actually thinking of splitting this page into several and this will help.

etorreborre commented 7 years ago

@benhutchison better Out-of-the-box page re-directing to specific pages for each effect.

@pjan is that better like that for you? Can I close the issue?

pjan commented 7 years ago

Much better. Thanks @etorreborre!