Skip to content
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

New Proposal for the Cats Microsite #1369

Merged
merged 8 commits into from
Oct 21, 2016
Merged

New Proposal for the Cats Microsite #1369

merged 8 commits into from
Oct 21, 2016

Conversation

juanpedromoreno
Copy link
Contributor

@juanpedromoreno juanpedromoreno commented Sep 11, 2016

This PR brings a new proposal for the Typelevel Cats website microsite.

It's made thanks to the https://github.com/47deg/sbt-microsites plugin and:

  • Provides the override.css file and the images resources.
  • Removes the versioned site.
  • Modifies the src/main/tut resources according to: root files, typeclasses and datatypes.
  • Updates the current documentation.
  • Other minor tweaks to be able to generate the site successfully.

The generated site has been removed since is not needed from now on. As you can see in the contributing.md file, the site can be generated each time on the fly.

If you want to test locally you need Jekyll locally, depending on your platform, you might do this with:

yum install jekyll

apt-get install jekyll

gem install jekyll

Once you have installed it, you could perform the following steps:

  • Build the microsite:
sbt docs/makeMicrosite
  • Then, to visualize the website in your browser, in a shell, navigate to the generated site directory in docs/target/site
  • Start jekyll with jekyll serve
  • Navigate to http://localhost:4000/cats/

Please, review at your convenience. Thanks!

Join-effort from the 47Deg team :)

juanpedromoreno and others added 2 commits September 10, 2016 19:25
* Removes sbt-site and tut plugins since they are transitive dependencies from sbt-microsite plugin
* Updates some configurations that are deprecated in the old 0.8 version of the sbt-site plugin. sbt-microsite plugin is using the 1.0.0
* Modifies all the documentation structure according to the new proposal
@juanpedromoreno
Copy link
Contributor Author

cats

@kailuowang
Copy link
Contributor

Thanks very much!
Can you expand on "on the fly" a little bit more? What triggers generating the site and push it to gh-page branch? I could not find it on sbt-microsites doc.

@juanpedromoreno
Copy link
Contributor Author

juanpedromoreno commented Sep 11, 2016

Sure, I guess site publication are disabled right now.

# temporarily disable to stabilize travis

Therefore, in the meantime this publish should performed by hand in the same way until now (sbt ghpagesPushSite), but in this case from the docs/target/site path (that is generated on the fly when you run run makeMicrosite). Does it make sense?

https://github.com/typelevel/cats/blob/master/CONTRIBUTING.md#publishing-the-site-to-github

I'm sorry about the sbt-microsites plugin documentation, it's still a WIP (actively working on it), nevertheless we hope to have ready all the plugin docs by this week. At the same time, we are working to have gh-pages sbt plugin integrated as a part of the sbt-microsites plugin workflow (perhaps for the next snapshot version).

@kailuowang
Copy link
Contributor

Ah that makes sense. Thanks! Is there a plan to release sbt-microsites? Looks very helpful.

@juanpedromoreno
Copy link
Contributor Author

Yep, it'll be released very soon!

On Sun, Sep 11, 2016, 2:22 PM Kai(luo) Wang [email protected]
wrote:

Ah that makes sense. Thanks! Is there a plan to release sbt-microsites?
Looks very helpful.


You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub
#1369 (comment), or mute
the thread
https://github.com/notifications/unsubscribe-auth/AEp0DQNwFUytCmeqxqx7a-ii_TaZhVjUks5qo_J9gaJpZM4J5-xd
.

@ghost
Copy link

ghost commented Sep 11, 2016

@juanpedromoreno This looks very nice!!

One thing that the cats docs do not currently do/have is support for current/previous versions - eg
https://www.scala-js.org/doc/all-api.html and http://tpolecat.github.io/doobie-0.3.0/00-index.html

Had you thought about this as part of your new plugin?

@juanpedromoreno
Copy link
Contributor Author

@BennyHill Not yet, but we'll do. Thanks!

@ghost
Copy link

ghost commented Sep 11, 2016

@juanpedromoreno I know your plugin is still WIP, 0.1.0 etc - I just thought I should pipe in with something that was on a TODO list at some point, lest it be forgotten. Looks cools already, btw 😸

@codecov-io
Copy link

codecov-io commented Sep 12, 2016

Current coverage is 91.68% (diff: 100%)

Merging #1369 into master will not change coverage

@@             master      #1369   diff @@
==========================================
  Files           240        240          
  Lines          3608       3608          
  Methods        3540       3540          
  Messages          0          0          
  Branches         67         67          
==========================================
  Hits           3308       3308          
  Misses          300        300          
  Partials          0          0          

Powered by Codecov. Last update 9f981b1...ed35844

@kailuowang
Copy link
Contributor

LGTM, I am wondering if we should wait for sbt-microsites release before merging this one in.

@juanpedromoreno
Copy link
Contributor Author

👍 We're working in the sbt-microsites release at this moment, we'll let you know once everything is ready. Thanks!

@jhzab
Copy link
Contributor

jhzab commented Sep 15, 2016

Two small comments:

  1. Is there some mechanism to include the current release version in the index.md file? I think automating this makes sense.
  2. I was really surprised that I could actually build cats with the sbt default memory settings, but could not build the site with 1GB. (But that is also true for the current master.)

@juanpedromoreno
Copy link
Contributor Author

@jhzab For comment 1, potentially, it could be accomplished with tut, but I have to give a try.

For point 2, yep, you're right, compiling tut documents could take some time and memory (couple of GB of Xmx should be enough).

@kailuowang
Copy link
Contributor

@juanpedromoreno thanks again. It looks like sbt-microsites has been released. I wonder if you have time to update this PR? Otherwise I can pick it up.

@juanpedromoreno
Copy link
Contributor Author

Sure @kailuowang . I'll do it this afternoon. Thanks!

@juanpedromoreno
Copy link
Contributor Author

@kailuowang Done ;)

@adelbertc
Copy link
Contributor

Looks like the 2.11 build was failing, not sure why, I've restarted it.

@juanpedromoreno
Copy link
Contributor Author

juanpedromoreno commented Sep 25, 2016

It's green now, thanks @adelbertc

@kailuowang
Copy link
Contributor

👍 thanks a lot!

@ceedubs
Copy link
Contributor

ceedubs commented Sep 26, 2016

Thanks a bunch, @juanpedromoreno! This looks really nice. I'm hoping I can find the time to take a closer look this evening or tomorrow.

@juanpedromoreno
Copy link
Contributor Author

Hey @ceedubs @kailuowang, is there anything else I can do about this PR? Just let me know. Thanks!

@longcao longcao mentioned this pull request Oct 17, 2016
@kailuowang
Copy link
Contributor

@juanpedromoreno LGTM.

@ceedubs
Copy link
Contributor

ceedubs commented Oct 18, 2016

@juanpedromoreno I'm sorry for the long delay on this. Life has gotten busy. I won't get a chance to look at this in the next several days. It looks like @kailuowang already gave a 👍. @adelbertc or @tpolecat (or anyone else) would you want to review this?

@juanpedromoreno
Copy link
Contributor Author

Sure, no problem @ceedubs

addSbtPlugin("pl.project13.scala" % "sbt-jmh" % "0.2.11")
addSbtPlugin("org.scalastyle" %% "scalastyle-sbt-plugin" % "0.8.0")
addSbtPlugin("org.scoverage" % "sbt-scoverage" % "1.2.0")
addSbtPlugin("com.typesafe.sbt" % "sbt-git" % "0.8.5")
addSbtPlugin("org.scala-js" % "sbt-scalajs" % "0.6.11")
addSbtPlugin("com.github.tkawachi" % "sbt-doctest" % "0.4.1")
addSbtPlugin("org.xerial.sbt" % "sbt-sonatype" % "1.1")
addSbtPlugin("com.fortysevendeg" % "sbt-microsites" % "0.2.4")
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

0.2.5 now

@adelbertc
Copy link
Contributor

I have approximately negative web dev experience but I looked at the changes and looks OK to me? 👍 from me.

@kailuowang
Copy link
Contributor

Thanks @adelbertc merging with two thumbs up.

@kailuowang kailuowang merged commit fe026bc into typelevel:master Oct 21, 2016
@adelbertc
Copy link
Contributor

@juanpedromoreno @kailuowang How do we get this published on typelevel.org/cats ?

@juanpedromoreno
Copy link
Contributor Author

juanpedromoreno commented Oct 21, 2016

@adelbertc @kailuowang Any person with permission to push to gh-pages branch simply could do:

sbt docs/publishMicrosite

That's it ;)

@kailuowang
Copy link
Contributor

I can give it a try, will ask in gitter room first.

@kailuowang
Copy link
Contributor

Published! Many thanks again @juanpedromoreno

@kailuowang
Copy link
Contributor

I noticed that it generates a new file docs/src/main/tut/contributing.md
shall we add that to git or gitignore?

@juanpedromoreno
Copy link
Contributor Author

@kailuowang You can commit it or ignore it. It's copied (from the project root to the docs module) each time the microsite is built. The plugin needs to copy it for the tut compile phase (potentially contributing.md hasn't scala code, but the setting is generic for any kind of markdown file :/ ).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants