These are chat archives for sbt/sbt

21st
Apr 2015
Simeon H.K. Fitch
@metasim
Apr 21 2015 12:32
@dwijnand I too miss the old docs format. I’m sure someone worked really hard to port it over to whatever the new generator engine is, but I found having the built-in search, right-hand TOC, and ability to select different SBT versions very helpful in the old (Sphinx?) version.
Josh Suereth
@jsuereth
Apr 21 2015 12:33
yeah, we have some TODOs about the search part
so the ToC On the left was also super valuable?
Simeon H.K. Fitch
@metasim
Apr 21 2015 12:34
Yeh, especially when you got down to third-level pages.
My memory is that the TOC was kinda context aware.
Josh Suereth
@jsuereth
Apr 21 2015 12:34
yeah, it was generated per-page, a sphinx feature
We're using "pamflet" now
IF you're in the PDF download, it's pretty nice
Simeon H.K. Fitch
@metasim
Apr 21 2015 12:35
Helped me when I got lost in some sub-topic, which I tend to do :-)
Josh Suereth
@jsuereth
Apr 21 2015 12:35
Why don't you guys open a ticket on github.com/sbt/website about it
also, pamflet is pretty nice and simple project, it may even be a simple addition, I dunno
@eed3si9n is the new docs guy
Simeon H.K. Fitch
@metasim
Apr 21 2015 12:36
Gotcha. Don’t mean it as a criticism, just a subjective experience.
In some ways it’s the TOC I miss more than the search.
I loose my place in the current page having to scroll down to check something in the TOC.
That said, hats off to @eed3si9n, who already does so much for the community.
Josh Suereth
@jsuereth
Apr 21 2015 12:49
Ha, that IS criticism and EXACTLY the kind we want :)
i.e. constructive criticism
if you said "the new docs suck" that'd be bad, because it doesn't tell us HOW or WHAT to fix. In any case, I think adding a ToC is a great idea. I'd open a ticket
and if you have time to look at pamflet, it's a fun little scala codebase
Simeon H.K. Fitch
@metasim
Apr 21 2015 12:57
10-4 :-)
Should I log an issue against Pamflet (new feature) or against sbt docs?
Josh Suereth
@jsuereth
Apr 21 2015 13:02
maybe both?
Simeon H.K. Fitch
@metasim
Apr 21 2015 13:02
heh. ok
Josh Suereth
@jsuereth
Apr 21 2015 13:02
sbt/website first
Simeon H.K. Fitch
@metasim
Apr 21 2015 13:03
thx
eugene yokota
@eed3si9n
Apr 21 2015 13:16
what sphinx displays on the right hand side is a list of internal headers, instead the TOC of the site
apparently the original maintainer(s) of sbt website has asked Pamflet that a while back - n8han/pamflet#13
Simeon H.K. Fitch
@metasim
Apr 21 2015 13:17
OK. I was speaking from fuzzy memory. I’ll have to revisit the old docs to figure out what I’m thinking of.
eugene yokota
@eed3si9n
Apr 21 2015 13:18
the case has "sbt" tag on it
Simeon H.K. Fitch
@metasim
Apr 21 2015 13:20
So it seems there’s been some banter over this already.
eugene yokota
@eed3si9n
Apr 21 2015 13:21
there was the first wave of effort to migrate docs to Pamflet when it first came out, but it blocked with a bunch of feature requests like in-page navigation and search. when I joined, I pushed through Pamflet ignoring whatever happened in the past
Simeon H.K. Fitch
@metasim
Apr 21 2015 13:21
Interesting that in my memory I thought the in-page TOC covered the whole site. Sorry for polluting your mind space with my confusion! :o
Heh. A “do-er” at heart!
eugene yokota
@eed3si9n
Apr 21 2015 13:22
as @jsuereth said, we welcome feedback and contributions around docs
I updated this chatroom's description to specifically include the word "documentation" in it too
Simeon H.K. Fitch
@metasim
Apr 21 2015 13:24
I’d like to help out… just need to figure out the right bite-sized chunk that fits in with the day job (blah blah blah; standard excuse).
Do you have a prioritized list of docs stuff (task board) you want addressed?
(wf
(waffle.io?)
eugene yokota
@eed3si9n
Apr 21 2015 13:26
there used to be private trello board listing some tasks
i think the main items are in https://github.com/sbt/website/issues
Simeon H.K. Fitch
@metasim
Apr 21 2015 13:29
What is the “community” tag for?
eugene yokota
@eed3si9n
Apr 21 2015 13:30
something we'd like to see happen, but might not be able to, but think that the community should be able to handle
Simeon H.K. Fitch
@metasim
Apr 21 2015 13:30
‘k
eugene yokota
@eed3si9n
Apr 21 2015 13:30
i can make waffle list for website
but the top priority is version dropdown
Simeon H.K. Fitch
@metasim
Apr 21 2015 13:31
As in how it was with Sphinx?
eugene yokota
@eed3si9n
Apr 21 2015 13:31
i think it's a matter of making a few javascript changes
yea. that widget needs to link between old and new site
eugene yokota
@eed3si9n
Apr 21 2015 13:37
Simeon H.K. Fitch
@metasim
Apr 21 2015 13:38
Awesome!
Is #135 straightforward?
wait, the one about SBT_OPS
sbt/website/#135
(guess you can’t cross link issues).
eugene yokota
@eed3si9n
Apr 21 2015 13:40
sbt/website#135
the OP says it's not a doc issue, so maybe I should close it
Simeon H.K. Fitch
@metasim
Apr 21 2015 13:44
@eed3si9n Thanks for the dialog. I’ll try to step up and lend a hand. Pretty easy when the SBT docs are already in such great shape. ;-)
eugene yokota
@eed3si9n
Apr 21 2015 13:50
no problem
another pie in the sky idea around docs would be to incorporate it to sbt so you can search/read them from the shell
Simeon H.K. Fitch
@metasim
Apr 21 2015 13:55
I actually poked at writing a plugin to do that for scaladoc/javadoc. Kinda like sbt-man, but not relying on an external service.
eugene yokota
@eed3si9n
Apr 21 2015 13:55
I would love to have correct sbt-man
Simeon H.K. Fitch
@metasim
Apr 21 2015 13:56
scaladocs don’t seem to have an index file in them like javadocs do, so I stalled on figuring out how to index them.
Didn’t want to blindly unpack all of the javadoc/scaladoc .jar files.
Really need an index because without command completion it’s usability is hampered.
Josh Suereth
@jsuereth
Apr 21 2015 13:57
scaladocs need a lot,r eally :)
and I thinkt here is an index, it's used by the javascript
i think it's in javascript, even
Simeon H.K. Fitch
@metasim
Apr 21 2015 13:58
Yeh, that rings right.
Definitely different from javadoc.
Josh Suereth
@jsuereth
Apr 21 2015 13:58
yes
soemtimes in good ways
eugene yokota
@eed3si9n
Apr 21 2015 13:59
fun thing about scaladoc + sbt is that we have Package.scala, which then produces Package.html on the same directory where package.html exists
Josh Suereth
@jsuereth
Apr 21 2015 13:59
nice...
eugene yokota
@eed3si9n
Apr 21 2015 13:59
git on Mac goes bonkers
Josh Suereth
@jsuereth
Apr 21 2015 13:59
That only matters for OSX
Can OSX just use ext4 filesystem?
or resierfs
eugene yokota
@eed3si9n
Apr 21 2015 14:00
there's been talks on butter or whatever FS since ages on Mac podcasts
Dale Wijnand
@dwijnand
Apr 21 2015 14:35
on top of what's been said about the docs, personally I like the bold of the headers, the fact that the text starts closer to the centre, and the #f2f2eb background instead of white
in the old docs over the current docs
not too sure if they can quantify github issues in sbt/website, perhaps more talking points for a dev chat, but I'm happy to throw them into issues
Simeon H.K. Fitch
@metasim
Apr 21 2015 14:41
“bling"
Is the width fixed in Pamflet?
Wondering what determines “closer to center”.
Me, I see wasted space. But I think I’m in the minority there.
eugene yokota
@eed3si9n
Apr 21 2015 14:44
the default behavior, i think is fixed
Simeon H.K. Fitch
@metasim
Apr 21 2015 14:44
It’s all such a matter of taste .
eugene yokota
@eed3si9n
Apr 21 2015 14:45
the idea is to immerse you into book-like experience whether you like it or not
and the background not being white helps make the code blocks pop
Simeon H.K. Fitch
@metasim
Apr 21 2015 14:49
@dwijnand Looks like it’s centered if you include the TOC.
But that doesn’t help if you’re scrolled down.
Are you saying you /like/ the background color of the old site?
Dale Wijnand
@dwijnand
Apr 21 2015 14:51
yes
Simeon H.K. Fitch
@metasim
Apr 21 2015 14:51
me too.
eugene yokota
@eed3si9n
Apr 21 2015 14:52
the off-centered-ness could be a bug/feature of our own custom css
Simeon H.K. Fitch
@metasim
Apr 21 2015 14:52
Also concur that having the code blocks a different background is helpful.
eugene yokota
@eed3si9n
Apr 21 2015 14:57
accessibility-wise though i think sticking to simple black/white is safe approach
that's what news paper website would do
Dale Wijnand
@dwijnand
Apr 21 2015 14:57
really? only black/white? :-/
eugene yokota
@eed3si9n
Apr 21 2015 14:59
not sure what current color scheme is, but generally sticking to black/white would give you better chance of being accessible since different devices have different dynamic range and contrast
at least for blob of text
Simeon H.K. Fitch
@metasim
Apr 21 2015 21:26
Trying to built the sbt/website docs and am getting an exception from the Markdown processor. Tried checking out older versions of the site and the issue is still triggered. Any hints/ideas?: sbt/website#143
Simeon H.K. Fitch
@metasim
Apr 21 2015 21:32
Do the plugins make any calls to external commands (i.e. ruby)?
eugene yokota
@eed3si9n
Apr 21 2015 21:33
sbt-site makes calls to Ruby
it also uses Pandoc
but I think you're blowing up on Pamflet
Pamflet internally calls knockoff - https://github.com/tristanjuricek/knockoff/
Simeon H.K. Fitch
@metasim
Apr 21 2015 21:39
Off the top of your head, do you know how to explicitly specify the sbt path to java?
(in which sbt runs)
/usr/local/etc/sbtopts?
eugene yokota
@eed3si9n
Apr 21 2015 21:41
maybe I'm not understanding the question
Simeon H.K. Fitch
@metasim
Apr 21 2015 21:45
Should have asked: does sbt just take whatever java is in the PATH?
I'll figure it out.
eugene yokota
@eed3si9n
Apr 21 2015 21:45
it depends on what sbt is really
Simeon H.K. Fitch
@metasim
Apr 21 2015 21:45
The Mac homebrew version.
Simeon H.K. Fitch
@metasim
Apr 21 2015 21:46
Didn't know if it was something you could specify in .sbtconfig, etc.
eugene yokota
@eed3si9n
Apr 21 2015 21:46
# java version (default: java from PATH, currently $(java -version 2>&1 | grep version))
-java-home <path>         alternate JAVA_HOME
never used that before, so ymmv
Simeon H.K. Fitch
@metasim
Apr 21 2015 21:48
Heh... my problem was that I ran sbt --help instead of sbt -help.
Wouldn't you know.. you get something different.
Well ain't that interesting... it's a Java 8 vs. Java 7 thing!
eugene yokota
@eed3si9n
Apr 21 2015 21:53
happy you found a solution, :worried: that it's Java 8
Simeon H.K. Fitch
@metasim
Apr 21 2015 21:53
Spooky.
Going to close the issue.
Don't think I have it in me to hunt down the problem, but hope by logging it someone else might find the issue should they hit it as well.
Thanks for the help.
eugene yokota
@eed3si9n
Apr 21 2015 21:57
np. likely the rabbit hole goes down to Knockoff
Simeon H.K. Fitch
@metasim
Apr 21 2015 22:02
I wonder if planet42/Laika would be better. I like its object model.
eugene yokota
@eed3si9n
Apr 21 2015 22:07
i'd be hard pressed to switch to another doc engine, since I've put in some work on pamflet itself including globalization feature, and it's a lot of work to migrate
Simeon H.K. Fitch
@metasim
Apr 21 2015 22:14
And every one has it's own disjoint set of strengths and weaknesses.
Josh Suereth
@jsuereth
Apr 21 2015 22:24
I've used -java-home, works pretty ok
Simeon H.K. Fitch
@metasim
Apr 21 2015 22:28
@jsuereth Yeh, worked great.
@eed3si9n, Looking at the "versions" issue. I may be doing something wrong, but it appears that src/nanoc/layouts/default.html isn't what is used for the actual documentation pages (just the higher level organization pages). Is that right, and if so, what's the template source for the main documentation pages?
eugene yokota
@eed3si9n
Apr 21 2015 22:32
nanoc layouts are just for the landing pages
Simeon H.K. Fitch
@metasim
Apr 21 2015 22:33
So it's OK to put javascript in there even though they are markdown files?
eugene yokota
@eed3si9n
Apr 21 2015 22:34
raw html is allowed on markdown
Simeon H.K. Fitch
@metasim
Apr 21 2015 22:34
and hard-code the relative paths to the scripts
IN the landing page I was doing <script src="<%= @items['/set-versions/'].path %>"></script>
Which I'm assuming I can't do in the markdown (or are they preprocessed).
eugene yokota
@eed3si9n
Apr 21 2015 22:35
nanoc is the processor that does the processing on the landing page
the dropdown isn't necessary there I think
Simeon H.K. Fitch
@metasim
Apr 21 2015 22:36
'k
eugene yokota
@eed3si9n
Apr 21 2015 22:36
I just want to navigate old docs to the new one
Simeon H.K. Fitch
@metasim
Apr 21 2015 22:37
Oh, so not from new to old....
Not sure I understand the requirement then :/
eugene yokota
@eed3si9n
Apr 21 2015 22:38
new from old would be useful too, but you don't have to worry about the landing page I think
since someday we'll have something newer than 0.13
Simeon H.K. Fitch
@metasim
Apr 21 2015 22:40
Have to run to dinner. Will followup on the actual issue to make sure I understand what it is you want (what the requirements are). I think I'm misunderstanding the goal (i.e. make it work like it did before).
eugene yokota
@eed3si9n
Apr 21 2015 22:40
i'll fill in more details on the Github issue