Switching tabs as well as other fragments #107

raboof · 2017-04-19T11:58:59Z

Expanding on the proposal in #95, added support for having other parts of
the documentation change as well when switching groups.

Expanding on the proposal in lightbend#95, added support for having other parts of the documentation change as well when changing a group.

raboof · 2017-04-19T12:07:55Z

Refs #106

pvlugter · 2017-04-19T23:40:58Z

The text switching on the spans looks good. Having a general purpose span directive is useful. My first thought for frequently used text groups is whether it would be useful to have it add extra named span directives, rather than just using span classes. Say specifying the possible groups in the build, since these are normally something like Java/Scala and used across the docs, and then having a named span directive like @scala[Scala only text]. So that it will warn you if use an unintended group or have a typo, and the syntax is more direct. Maybe using the group name directly doesn't work and it needs something else, like @for-scala or @scala-only or some other convention. Knowing what the possible groups are at the highest level, to add overall switches at the page level, could also be useful.

raboof · 2017-04-20T08:04:06Z

I like the idea of configuring 'supergroups' in the build (instead of the directive I added for that) and generating directives for them. Using the group name as directive name should be fine (you'll just have to make sure not to choose group names that clash with other directives) - otherwise @scala-group[Scala only snippet] might work.

This will also help when adding overall switches, too, indeed - and perhaps when implementing #14 we'll actually need it for generating a PDF for each possible selection.

2m

LGTM. Just a couple of nitpicks. Also it would be useful to have implicit group names assigned for @scaladoc and @JavaDoc directives (mentioned initially here)

2m · 2017-04-20T08:53:31Z

core/src/main/scala/com/lightbend/paradox/markdown/Directive.scala

@@ -311,7 +311,8 @@ case class SnipDirective(page: Page, variables: Map[String, String])
        } else new File(page.file.getParentFile, source)
      val text = Snippet(file, labels)
      val lang = Option(node.attributes.value("type")).getOrElse(Snippet.language(file))
-      new VerbatimNode(text, lang).accept(visitor)
+      val group = Option(node.attributes.value("group")).getOrElse("")


What do you think about the idea mentioned here: #95 (comment)

That would allow easier adaptation of the group functionality. All of the already written docs could use this feature without any changes to the docs.

Completely agreed ;)

Removes the need to define the 'supergroup' in the markdown. Next up is of course switching from the dropdown.

ktoso · 2017-04-24T05:32:47Z

docs/src/main/paradox/features/snippet-inclusion.md

+First-scala
+:   @@snip [example-first.scala](../../resources/tab-switching/examples.scala) { #scala_first group=scala }
+
+Some separator with text describing the @java[Java variant] @scala[Scala variant containing ***markdown*** and @ref:[Linking](linking.md)]


ktoso

LGTM, I like this a lot - can't wait to use it

2m · 2017-04-24T13:09:23Z

When merging, make sure to create a merge commit (as opposed to squash and merge), as this PR contains commits from more than one author.

2m · 2017-04-24T13:47:27Z

docs/src/main/paradox/features/snippet-inclusion.md

+:   @@snip [example-second.java](../../resources/tab-switching/examples.java)
+
+Scala
+:   @@snip [example-second.scala](../../resources/tab-switching/examples.scala)


The example markdown does not match the markdown for render.

2m · 2017-04-24T13:51:07Z

Its a pity I was not able to try it out, as paradox itself does not use the same code to generate the docs.

For snippets, the group now defaults to the type of snippet (e.g. java/scala).

pvlugter · 2017-05-04T00:36:09Z

I tried this out on the Cinnamon docs. The Cinnamon docs also uses tabs that shouldn't be switched. We have example Configuration snippets with a second tab called Defaults that displays the default configuration from a reference.conf (for example). It would be good if the switching could be disabled for these. It would also be great to support tabs without snippets (with text or direct code examples). I also got javascript errors for a direct code example in a tab.

Given that we now have a declarative list of the switchable groups in the build, I'm wondering if we could use that as a whitelist for switching (by injecting it into the template for the javascript part). And instead of looking for classes on code blocks in tabs, could we simply use the tab name itself (and match against the known groups). So for the Cinnamon docs, we would define the switchable tabs as "language" -> ("scala, "java), "build tool" -> ("sbt", "maven", "gradle"). And the configuration tabs would be left as is. We could also store something like language=java build-tool=gradle in the cookie then, rather than appending the latest group.

raboof · 2017-05-08T08:19:17Z

@pvlugter yes that makes a lot of sense to me!

eed3si9n · 2017-05-10T21:09:55Z

What's the status on this PR? Is it ready to be merged?

raboof · 2017-05-10T21:27:31Z

@eed3si9n I think it might make sense to implement the ideas by @pvlugter before merging, and perhaps add hooks to customize the behavior on tab change (as e.g. for the akka docs we might want to do a page refresh instead of client-side switching until we've migrated all pages to support that). @pvlugter WDYT?

eed3si9n · 2017-05-10T21:29:24Z

ok. Sounds good.

pvlugter · 2017-05-11T00:16:43Z

SGTM

pvlugter · 2017-05-11T07:04:04Z

@raboof are you going to work on these changes?

raboof · 2017-05-11T07:15:26Z

Yes if that doesn't interfere with your work I think I can look into it today!

pvlugter · 2017-05-11T07:16:47Z

Great, sounds good.

Though definition lists that don't contain any code snippets currently don't become tabs, this makes things a bit more robust.

raboof · 2017-05-11T23:53:19Z

I've made some changes, including:

only switch groups declared in the paradox config
switch based on tab name when group property is missing (should be the common case)
use 'neater' cookie format
don't assume tabs contain snippets so heavily
allow extending group switch javascript
added documentation

I think this makes this PR ready for merge, review welcome.

pvlugter

Nice! LGTM!

Also tried it out on the Cinnamon docs and works great there.

gsechaud and others added 5 commits February 1, 2017 15:15

Add tab-group switching

dc6a0e9

Update docs

dc37626

Add scripted test

b39cf76

Add tab snippets to cookie

f07cad6

Allow any fragment to be switched as part of a group

c09450d

Expanding on the proposal in lightbend#95, added support for having other parts of the documentation change as well when changing a group.

raboof mentioned this pull request Apr 19, 2017

Merge Scala and Java documentation akka/akka-http#527

Closed

2m approved these changes Apr 20, 2017

View reviewed changes

raboof added 3 commits April 20, 2017 16:46

Allow group shorthand, configured from sbt

09f0ccd

Generate 'groups' block on the page

de72f11

Removes the need to define the 'supergroup' in the markdown. Next up is of course switching from the dropdown.

Merge remote-tracking branch 'origin/master' into switch-groups

c326e73

raboof force-pushed the switch-groups branch from 97ba9f5 to c326e73 Compare April 21, 2017 07:27

raboof mentioned this pull request Apr 21, 2017

Tab-group switching for snippets #95

Closed

ktoso reviewed Apr 24, 2017

View reviewed changes

ktoso approved these changes Apr 24, 2017

View reviewed changes

2m reviewed Apr 24, 2017

View reviewed changes

2m approved these changes Apr 24, 2017

View reviewed changes

raboof force-pushed the switch-groups branch from fcb9175 to 73dd536 Compare April 24, 2017 14:03

Show group dropdown, default groups

0a01685

For snippets, the group now defaults to the type of snippet (e.g. java/scala).

raboof force-pushed the switch-groups branch from 73dd536 to 0a01685 Compare April 24, 2017 14:06

raboof added 2 commits May 11, 2017 10:00

Merge remote-tracking branch 'origin/master' into switch-groups

ab03fa8

Only switch groups declared in the configuration

27b9bfe

raboof force-pushed the switch-groups branch from cfcf299 to 27b9bfe Compare May 11, 2017 09:39

raboof added 3 commits May 11, 2017 13:53

Also switch tabs which are not code snippets

be0bf4b

Though definition lists that don't contain any code snippets currently don't become tabs, this makes things a bit more robust.

Documentation section for groups

13de02a

Don't autogenerate 'group' attribute, prefer tab name

4cf24e5

raboof force-pushed the switch-groups branch from c70fcbb to 3784db8 Compare May 11, 2017 23:43

Allow extending group switch functionality

637831b

raboof force-pushed the switch-groups branch from 3784db8 to 637831b Compare May 11, 2017 23:45

Put groups/tabs logic in its own .js file

7f55c0c

pvlugter approved these changes May 12, 2017

View reviewed changes

pvlugter merged commit f71a5c3 into lightbend:master May 12, 2017

raboof deleted the switch-groups branch May 12, 2017 07:19

This was referenced May 15, 2017

Make it possible to switch all tabs on a page #11

Closed

Tab selection preference should be remembered in a cookie #63

Closed

Allow text to change along with selected snippet alternative #62

Closed

Text switching #106

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Switching tabs as well as other fragments #107

Switching tabs as well as other fragments #107

raboof commented Apr 19, 2017

raboof commented Apr 19, 2017

pvlugter commented Apr 19, 2017 •

edited

Loading

raboof commented Apr 20, 2017

2m left a comment

2m Apr 20, 2017

raboof Apr 20, 2017

ktoso Apr 24, 2017

ktoso left a comment

2m commented Apr 24, 2017 •

edited

Loading

2m Apr 24, 2017

2m commented Apr 24, 2017

pvlugter commented May 4, 2017

raboof commented May 8, 2017

eed3si9n commented May 10, 2017

raboof commented May 10, 2017

eed3si9n commented May 10, 2017

pvlugter commented May 11, 2017

pvlugter commented May 11, 2017

raboof commented May 11, 2017

pvlugter commented May 11, 2017

raboof commented May 11, 2017

pvlugter left a comment

Switching tabs as well as other fragments #107

Switching tabs as well as other fragments #107

Conversation

raboof commented Apr 19, 2017

raboof commented Apr 19, 2017

pvlugter commented Apr 19, 2017 • edited Loading

raboof commented Apr 20, 2017

2m left a comment

Choose a reason for hiding this comment

2m Apr 20, 2017

Choose a reason for hiding this comment

raboof Apr 20, 2017

Choose a reason for hiding this comment

ktoso Apr 24, 2017

Choose a reason for hiding this comment

ktoso left a comment

Choose a reason for hiding this comment

2m commented Apr 24, 2017 • edited Loading

2m Apr 24, 2017

Choose a reason for hiding this comment

2m commented Apr 24, 2017

pvlugter commented May 4, 2017

raboof commented May 8, 2017

eed3si9n commented May 10, 2017

raboof commented May 10, 2017

eed3si9n commented May 10, 2017

pvlugter commented May 11, 2017

pvlugter commented May 11, 2017

raboof commented May 11, 2017

pvlugter commented May 11, 2017

raboof commented May 11, 2017

pvlugter left a comment

Choose a reason for hiding this comment

pvlugter commented Apr 19, 2017 •

edited

Loading

2m commented Apr 24, 2017 •

edited

Loading