3 | */
4 |
5 | package play.doc
6 |
7 | import org.specs2.mutable._
8 | import java.io.File
9 |
10 | class PlayDocSpec extends Specification {
11 | def fileFromClasspath(name: String) = new File(Thread.currentThread.getContextClassLoader.getResource(name).toURI)
12 | val repo = new FilesystemRepository(fileFromClasspath("file-placeholder").getParentFile)
13 | val oldRenderer = new PlayDoc(repo, repo, "resources", "2.1.3", None, new TranslatedPlayDocTemplates("Next"), None)
14 |
15 | val renderer =
16 | new PlayDoc(
17 | repo,
18 | repo,
19 | "resources",
20 | "2.4.0",
21 | PageIndex.parseFrom(repo, "Home", Some("example")),
22 | new TranslatedPlayDocTemplates("Next"),
23 | None
24 | )
25 |
26 | "code snippet handling" should {
27 | def test(label: String, rendered: String, file: String = "code/sample.txt") = {
28 | oldRenderer.render(s"@[$label]($file)") must_==
29 | s"""$rendered
"""
30 | }
31 |
32 | def failTest(label: String) = {
33 | oldRenderer.render("@[" + label + "](code/sample.txt)") must_==
34 | """Unable to find label """ + label + """ in source file """ + "code/sample.txt"
35 | }
36 |
37 | "allow extracting code snippets" in test("simple", "Snippet")
38 |
39 | "allow extracting code snippets using string that exists as substring elsewhere" in test("one", "One")
40 | "allow extracting code snippets using string as full string" in test(
41 | "onetwothree",
42 | "One Two Three"
43 | ) // paired with previous test
44 | "fail on substring code snippets using string as trailing" in failTest("three") // paired with previous test
45 |
46 | "fail on substring with no full string match" in failTest("leading")
47 | "should match on full string" in test("leading-following", "Leading Following") // paired with test for exception
48 | "fail on substring when looking for a trailing match" in failTest("following")
49 |
50 | "strip indent of shallowest line" in test("indent", " deep\nshallow")
51 | "ignore other characters on label delimiter line" in test("otherchars", "Snippet")
52 | "allow skipping lines" in test("skipping", "Snippet")
53 | "allow skipping multiple lines" in test("skipmultiple", "Snippet")
54 | "allow replacing lines" in test("replacing", "Replaced\nSnippet")
55 | "allow replacing lines with limited text" in test("replacelimited", "Replaced")
56 | "allow inserting lines" in test("inserting", "Inserted\nSnippet")
57 | "allow inserting lines with limited text" in test("insertlimited", "Inserted")
58 |
59 | "allow including a whole file" in test("", "This is the whole file", "code/whole.txt")
60 | }
61 |
62 | "page rendering" should {
63 | "old renderer" in {
64 | "render the page and the sidebar" in {
65 | val result = oldRenderer.renderPage("Foo")
66 | result must beSome[RenderedPage].like { case RenderedPage(main, maybeSidebar, path, maybeBreadcrumbs) =>
67 | main must contain("Some markdown")
68 | main must not contain "Sidebar"
69 | maybeSidebar must beSome[String].like { case sidebar =>
70 | sidebar must contain("Sidebar")
71 | sidebar must not contain "Some markdown"
72 | }
73 | maybeBreadcrumbs must beSome[String].like { case breadcrumbs =>
74 | breadcrumbs must contain("Breadcrumbs")
75 | breadcrumbs must not contain "Some markdown"
76 | }
77 | path must_== "example/docs/Foo.md"
78 | }
79 | }
80 | }
81 |
82 | "new renderer" in {
83 | "render the page and sidebar" in {
84 | val result = renderer.renderPage("Foo")
85 | result must beSome[RenderedPage].like { case RenderedPage(main, maybeSidebar, path, maybeBreadcrumbs) =>
86 | main must contain("Some markdown")
87 | maybeSidebar must beSome[String].like { case sidebar =>
88 | sidebar must contain("Documentation Home")
89 | }
90 | maybeBreadcrumbs must beSome[String].like { case breadcrumbs =>
91 | breadcrumbs must contain(
92 | "Home"
93 | )
94 | }
95 | path must_== "example/docs/Foo.md"
96 | }
97 | }
98 | }
99 | }
100 |
101 | "play version variables" should {
102 | "be substituted with the Play version" in {
103 | oldRenderer.render(
104 | "The current Play version is %PLAY_VERSION%"
105 | ) must_== "The current Play version is 2.1.3
"
106 | }
107 | "work in verbatim blocks" in {
108 | oldRenderer.render("""
109 | | Here is some code:
110 | |
111 | | addSbtPlugin("org.playframework" % "sbt-plugin" % "%PLAY_VERSION%")
112 | |
113 | """.stripMargin) must contain("% "2.1.3")")
114 | }
115 | "work in code blocks" in {
116 | oldRenderer.render("Play `%PLAY_VERSION%` is cool.") must_== "Play 2.1.3 is cool.
"
117 | }
118 | }
119 |
120 | "play table of contents support" should {
121 | "render a table of contents" in {
122 | renderer.renderPage("Home") must beSome[RenderedPage].like { case page =>
123 | page.html must contain("Sub Documentation
")
124 | page.html must contain("Foo Page")
125 | page.html must contain("Sub Section")
126 | page.html must contain("Sub Foo Page 1")
127 | }
128 | }
129 | }
130 |
131 | "header link rendering" should {
132 | "render header links" in {
133 | renderer.render("# Hello World") must_==
134 | """§Hello World
"""
135 | }
136 | }
137 | }
138 |
--------------------------------------------------------------------------------
/src/main/scala/play/doc/PageIndex.scala:
--------------------------------------------------------------------------------
1 | /*
2 | * Copyright (C) from 2022 The Play Framework Contributors , 2011-2021 Lightbend Inc.
3 | */
4 |
5 | package play.doc
6 |
7 | import org.apache.commons.io.IOUtils
8 |
9 | /**
10 | * A table of contents node
11 | */
12 | sealed trait TocTree {
13 |
14 | /**
15 | * The page that this node should point to
16 | */
17 | def page: String
18 |
19 | /**
20 | * The title of this node
21 | */
22 | def title: String
23 | }
24 |
25 | /**
26 | * A table of contents
27 | *
28 | * @param title
29 | * The title of this table of contents
30 | * @param nodes
31 | * The nodes in the table of contents
32 | * @param descend
33 | * Whether a table of contents should descend into this table of contents
34 | */
35 | case class Toc(name: String, title: String, nodes: List[(String, TocTree)], descend: Boolean = true) extends TocTree {
36 | require(nodes.nonEmpty)
37 |
38 | def page = nodes.head._2.page
39 | }
40 |
41 | /**
42 | * A page (leaf node) pointed to by the table of contents
43 | *
44 | * @param page
45 | * The page
46 | * @param title
47 | * The title of the page
48 | * @param next
49 | * Explicitly provided next links. If None, then the index structure are used to generate the next links, otherwise
50 | * these links should be used. Note that `Some(Nil)` is distinct from `None`, in that `Some(Nil)` means there should
51 | * be no next links, whereas `None` means let the index decide what the next link should be.
52 | */
53 | case class TocPage(page: String, title: String, next: Option[List[String]]) extends TocTree
54 |
55 | /**
56 | * The page index
57 | *
58 | * @param toc
59 | * The table of contents
60 | */
61 | class PageIndex(val toc: Toc, path: Option[String] = None) {
62 | private val byPage: Map[String, Page] = {
63 | // First, create a by name index
64 | def indexByName(node: TocTree): List[(String, TocTree)] =
65 | node match {
66 | case Toc(name, _, nodes, _) =>
67 | (name -> node) :: nodes.map(_._2).flatMap(indexByName)
68 | case TocPage(name, _, _) =>
69 | List(name -> node)
70 | }
71 | val byNameMap = indexByName(toc).toMap
72 |
73 | def indexPages(path: Option[String], nav: List[Toc], toc: Toc): List[Page] = {
74 | toc.nodes.flatMap {
75 | case (_, TocPage(page, title, explicitNext)) =>
76 | val nextLinks = explicitNext
77 | .map { links => links.collect(Function.unlift(byNameMap.get)) }
78 | .getOrElse {
79 | findNext(page, nav).toList
80 | }
81 | List(Page(page, path, title, nav, nextLinks))
82 | case (pathPart, tocPart: Toc) =>
83 | indexPages(
84 | path.map(_ + "/" + pathPart).orElse(Some(pathPart)),
85 | tocPart :: nav,
86 | tocPart
87 | )
88 | }
89 | }
90 |
91 | indexPages(path, List(toc), toc).map(p => p.page -> p).toMap
92 | }
93 |
94 | private def findNext(name: String, nav: List[Toc]): Option[TocTree] = {
95 | nav match {
96 | case Nil => None
97 | case toc :: rest =>
98 | toc.nodes.view
99 | .dropWhile(_._1 != name)
100 | .drop(1)
101 | .headOption
102 | .map(_._2)
103 | .orElse(
104 | findNext(toc.name, rest)
105 | )
106 | }
107 | }
108 |
109 | /**
110 | * Get the page for the given page name
111 | */
112 | def get(page: String): Option[Page] = byPage.get(page)
113 | }
114 |
115 | /**
116 | * A page
117 | *
118 | * @param page
119 | * The page name
120 | * @param path
121 | * The path to the page
122 | * @param title
123 | * The title of the page
124 | * @param nav
125 | * The navigation associated with the page, this is a list of all the table of contents nodes, starting from the one
126 | * that this page is in, all the way up the tree to the root node
127 | * @param nextLinks
128 | * A list of next links
129 | */
130 | case class Page(page: String, path: Option[String], title: String, nav: List[Toc], nextLinks: List[TocTree]) {
131 | def fullPath = path.fold(page)(_ + "/" + page)
132 |
133 | def next: Option[TocTree] = nextLinks.headOption
134 | }
135 |
136 | object PageIndex {
137 | def parseFrom(repo: FileRepository, home: String, path: Option[String] = None): Option[PageIndex] = {
138 | parseToc(repo, path, "", home) match {
139 | case toc: Toc => Some(new PageIndex(toc, path))
140 | case _ => None
141 | }
142 | }
143 |
144 | private def parseToc(
145 | repo: FileRepository,
146 | path: Option[String],
147 | page: String,
148 | title: String,
149 | descend: Boolean = true,
150 | next: Option[List[String]] = None
151 | ): TocTree = {
152 | repo
153 | .loadFile(path.fold("index.toc")(_ + "/index.toc"))(IOUtils.toString(_, "utf-8"))
154 | .fold[TocTree](
155 | TocPage(page, title, next)
156 | ) { content =>
157 | // https://github.com/scala/bug/issues/11125#issuecomment-423375868
158 | val lines = augmentString(content).linesIterator.toList.map(_.trim).filter(_.nonEmpty)
159 | // Remaining lines are the entries of the contents
160 | val tocNodes = lines.map { entry =>
161 | val linkAndTitle :: params = entry.split(";").toList
162 | val (link, title) = {
163 | linkAndTitle.split(":", 2) match {
164 | case Array(p) => p -> p
165 | case Array(p, t) => p -> t
166 | }
167 | }
168 | val parsedParams = params.map { param =>
169 | param.split("=", 2) match {
170 | case Array(k) => k -> k
171 | case Array(k, v) => k -> v
172 | }
173 | }.toMap
174 |
175 | val next = parsedParams.get("next").map { n => n.split(",").toList }
176 |
177 | val (relPath, descend) = if (link.startsWith("!")) {
178 | link.drop(1) -> false
179 | } else {
180 | link -> true
181 | }
182 |
183 | relPath -> parseToc(repo, path.map(_ + "/" + relPath).orElse(Some(relPath)), relPath, title, descend, next)
184 | }
185 | Toc(page, title, tocNodes, descend)
186 | }
187 | }
188 | }
189 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | Apache License
2 | Version 2.0, January 2004
3 | http://www.apache.org/licenses/
4 |
5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6 |
7 | 1. Definitions.
8 |
9 | "License" shall mean the terms and conditions for use, reproduction,
10 | and distribution as defined by Sections 1 through 9 of this document.
11 |
12 | "Licensor" shall mean the copyright owner or entity authorized by
13 | the copyright owner that is granting the License.
14 |
15 | "Legal Entity" shall mean the union of the acting entity and all
16 | other entities that control, are controlled by, or are under common
17 | control with that entity. For the purposes of this definition,
18 | "control" means (i) the power, direct or indirect, to cause the
19 | direction or management of such entity, whether by contract or
20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the
21 | outstanding shares, or (iii) beneficial ownership of such entity.
22 |
23 | "You" (or "Your") shall mean an individual or Legal Entity
24 | exercising permissions granted by this License.
25 |
26 | "Source" form shall mean the preferred form for making modifications,
27 | including but not limited to software source code, documentation
28 | source, and configuration files.
29 |
30 | "Object" form shall mean any form resulting from mechanical
31 | transformation or translation of a Source form, including but
32 | not limited to compiled object code, generated documentation,
33 | and conversions to other media types.
34 |
35 | "Work" shall mean the work of authorship, whether in Source or
36 | Object form, made available under the License, as indicated by a
37 | copyright notice that is included in or attached to the work
38 | (an example is provided in the Appendix below).
39 |
40 | "Derivative Works" shall mean any work, whether in Source or Object
41 | form, that is based on (or derived from) the Work and for which the
42 | editorial revisions, annotations, elaborations, or other modifications
43 | represent, as a whole, an original work of authorship. For the purposes
44 | of this License, Derivative Works shall not include works that remain
45 | separable from, or merely link (or bind by name) to the interfaces of,
46 | the Work and Derivative Works thereof.
47 |
48 | "Contribution" shall mean any work of authorship, including
49 | the original version of the Work and any modifications or additions
50 | to that Work or Derivative Works thereof, that is intentionally
51 | submitted to Licensor for inclusion in the Work by the copyright owner
52 | or by an individual or Legal Entity authorized to submit on behalf of
53 | the copyright owner. For the purposes of this definition, "submitted"
54 | means any form of electronic, verbal, or written communication sent
55 | to the Licensor or its representatives, including but not limited to
56 | communication on electronic mailing lists, source code control systems,
57 | and issue tracking systems that are managed by, or on behalf of, the
58 | Licensor for the purpose of discussing and improving the Work, but
59 | excluding communication that is conspicuously marked or otherwise
60 | designated in writing by the copyright owner as "Not a Contribution."
61 |
62 | "Contributor" shall mean Licensor and any individual or Legal Entity
63 | on behalf of whom a Contribution has been received by Licensor and
64 | subsequently incorporated within the Work.
65 |
66 | 2. Grant of Copyright License. Subject to the terms and conditions of
67 | this License, each Contributor hereby grants to You a perpetual,
68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69 | copyright license to reproduce, prepare Derivative Works of,
70 | publicly display, publicly perform, sublicense, and distribute the
71 | Work and such Derivative Works in Source or Object form.
72 |
73 | 3. Grant of Patent License. Subject to the terms and conditions of
74 | this License, each Contributor hereby grants to You a perpetual,
75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76 | (except as stated in this section) patent license to make, have made,
77 | use, offer to sell, sell, import, and otherwise transfer the Work,
78 | where such license applies only to those patent claims licensable
79 | by such Contributor that are necessarily infringed by their
80 | Contribution(s) alone or by combination of their Contribution(s)
81 | with the Work to which such Contribution(s) was submitted. If You
82 | institute patent litigation against any entity (including a
83 | cross-claim or counterclaim in a lawsuit) alleging that the Work
84 | or a Contribution incorporated within the Work constitutes direct
85 | or contributory patent infringement, then any patent licenses
86 | granted to You under this License for that Work shall terminate
87 | as of the date such litigation is filed.
88 |
89 | 4. Redistribution. You may reproduce and distribute copies of the
90 | Work or Derivative Works thereof in any medium, with or without
91 | modifications, and in Source or Object form, provided that You
92 | meet the following conditions:
93 |
94 | (a) You must give any other recipients of the Work or
95 | Derivative Works a copy of this License; and
96 |
97 | (b) You must cause any modified files to carry prominent notices
98 | stating that You changed the files; and
99 |
100 | (c) You must retain, in the Source form of any Derivative Works
101 | that You distribute, all copyright, patent, trademark, and
102 | attribution notices from the Source form of the Work,
103 | excluding those notices that do not pertain to any part of
104 | the Derivative Works; and
105 |
106 | (d) If the Work includes a "NOTICE" text file as part of its
107 | distribution, then any Derivative Works that You distribute must
108 | include a readable copy of the attribution notices contained
109 | within such NOTICE file, excluding those notices that do not
110 | pertain to any part of the Derivative Works, in at least one
111 | of the following places: within a NOTICE text file distributed
112 | as part of the Derivative Works; within the Source form or
113 | documentation, if provided along with the Derivative Works; or,
114 | within a display generated by the Derivative Works, if and
115 | wherever such third-party notices normally appear. The contents
116 | of the NOTICE file are for informational purposes only and
117 | do not modify the License. You may add Your own attribution
118 | notices within Derivative Works that You distribute, alongside
119 | or as an addendum to the NOTICE text from the Work, provided
120 | that such additional attribution notices cannot be construed
121 | as modifying the License.
122 |
123 | You may add Your own copyright statement to Your modifications and
124 | may provide additional or different license terms and conditions
125 | for use, reproduction, or distribution of Your modifications, or
126 | for any such Derivative Works as a whole, provided Your use,
127 | reproduction, and distribution of the Work otherwise complies with
128 | the conditions stated in this License.
129 |
130 | 5. Submission of Contributions. Unless You explicitly state otherwise,
131 | any Contribution intentionally submitted for inclusion in the Work
132 | by You to the Licensor shall be under the terms and conditions of
133 | this License, without any additional terms or conditions.
134 | Notwithstanding the above, nothing herein shall supersede or modify
135 | the terms of any separate license agreement you may have executed
136 | with Licensor regarding such Contributions.
137 |
138 | 6. Trademarks. This License does not grant permission to use the trade
139 | names, trademarks, service marks, or product names of the Licensor,
140 | except as required for reasonable and customary use in describing the
141 | origin of the Work and reproducing the content of the NOTICE file.
142 |
143 | 7. Disclaimer of Warranty. Unless required by applicable law or
144 | agreed to in writing, Licensor provides the Work (and each
145 | Contributor provides its Contributions) on an "AS IS" BASIS,
146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147 | implied, including, without limitation, any warranties or conditions
148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149 | PARTICULAR PURPOSE. You are solely responsible for determining the
150 | appropriateness of using or redistributing the Work and assume any
151 | risks associated with Your exercise of permissions under this License.
152 |
153 | 8. Limitation of Liability. In no event and under no legal theory,
154 | whether in tort (including negligence), contract, or otherwise,
155 | unless required by applicable law (such as deliberate and grossly
156 | negligent acts) or agreed to in writing, shall any Contributor be
157 | liable to You for damages, including any direct, indirect, special,
158 | incidental, or consequential damages of any character arising as a
159 | result of this License or out of the use or inability to use the
160 | Work (including but not limited to damages for loss of goodwill,
161 | work stoppage, computer failure or malfunction, or any and all
162 | other commercial damages or losses), even if such Contributor
163 | has been advised of the possibility of such damages.
164 |
165 | 9. Accepting Warranty or Additional Liability. While redistributing
166 | the Work or Derivative Works thereof, You may choose to offer,
167 | and charge a fee for, acceptance of support, warranty, indemnity,
168 | or other liability obligations and/or rights consistent with this
169 | License. However, in accepting such obligations, You may act only
170 | on Your own behalf and on Your sole responsibility, not on behalf
171 | of any other Contributor, and only if You agree to indemnify,
172 | defend, and hold each Contributor harmless for any liability
173 | incurred by, or claims asserted against, such Contributor by reason
174 | of your accepting any such warranty or additional liability.
175 |
176 | END OF TERMS AND CONDITIONS
177 |
178 | APPENDIX: How to apply the Apache License to your work.
179 |
180 | To apply the Apache License to your work, attach the following
181 | boilerplate notice, with the fields enclosed by brackets "[]"
182 | replaced with your own identifying information. (Don't include
183 | the brackets!) The text should be enclosed in the appropriate
184 | comment syntax for the file format. We also recommend that a
185 | file or class name and description of purpose be included on the
186 | same "printed page" as the copyright notice for easier
187 | identification within third-party archives.
188 |
189 | Copyright [yyyy] [name of copyright owner]
190 |
191 | Licensed under the Apache License, Version 2.0 (the "License");
192 | you may not use this file except in compliance with the License.
193 | You may obtain a copy of the License at
194 |
195 | http://www.apache.org/licenses/LICENSE-2.0
196 |
197 | Unless required by applicable law or agreed to in writing, software
198 | distributed under the License is distributed on an "AS IS" BASIS,
199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200 | See the License for the specific language governing permissions and
201 | limitations under the License.
202 |
--------------------------------------------------------------------------------
/src/main/scala/play/doc/PlayDoc.scala:
--------------------------------------------------------------------------------
1 | /*
2 | * Copyright (C) from 2022 The Play Framework Contributors , 2011-2021 Lightbend Inc.
3 | */
4 |
5 | package play.doc
6 |
7 | import java.io.InputStream
8 | import java.io.File
9 | import java.util.Collections
10 | import java.util.Arrays
11 | import org.pegdown.*
12 | import org.pegdown.plugins.ToHtmlSerializerPlugin
13 | import org.pegdown.plugins.PegDownPlugins
14 | import org.pegdown.ast.*
15 | import org.apache.commons.io.IOUtils
16 | import scala.collection.JavaConverters.*
17 |
18 | /**
19 | * A rendered page
20 | *
21 | * @param html
22 | * The HTML for the page
23 | * @param sidebarHtml
24 | * The HTML for the sidebar
25 | * @param path
26 | * The path that the page was found at
27 | * @param breadcrumbsHtml
28 | * The HTML for the breadcrumbs.
29 | */
30 | case class RenderedPage(html: String, sidebarHtml: Option[String], path: String, breadcrumbsHtml: Option[String])
31 |
32 | /**
33 | * Play documentation support
34 | *
35 | * @param markdownRepository
36 | * Repository for finding markdown files
37 | * @param codeRepository
38 | * Repository for finding code samples
39 | * @param resources
40 | * The resources path
41 | * @param playVersion
42 | * The version of Play we are rendering docs for.
43 | * @param pageIndex
44 | * An optional page index. If None, will use the old approach of searching up the heirarchy for sidebar pages,
45 | * otherwise will use the page index to render the sidebar.
46 | * @param templates
47 | * The templates to render snippets.
48 | * @param pageExtension
49 | * The extension to add to rendered pages - used for rendering links.
50 | */
51 | class PlayDoc(
52 | markdownRepository: FileRepository,
53 | codeRepository: FileRepository,
54 | resources: String,
55 | playVersion: String,
56 | val pageIndex: Option[PageIndex],
57 | templates: PlayDocTemplates,
58 | pageExtension: Option[String]
59 | ) {
60 |
61 | val PlayVersionVariableName = "%PLAY_VERSION%"
62 |
63 | /**
64 | * Render some markdown.
65 | */
66 | def render(markdown: String, relativePath: Option[File] = None): String = {
67 | withRenderer(relativePath.map(_.getPath), None)(_(markdown))
68 | }
69 |
70 | /**
71 | * Render a Play documentation page.
72 | *
73 | * @param pageName
74 | * The page to render, without path or markdown extension.
75 | * @return
76 | * If found a tuple of the rendered page and the rendered sidebar, if the sidebar was found.
77 | */
78 | def renderPage(pageName: String): Option[RenderedPage] = {
79 | pageIndex.fold {
80 | renderOldPage(pageName)
81 | } { index =>
82 | index.get(pageName).flatMap { page =>
83 | withRenderer(page.path, page.nav.headOption) { renderer =>
84 | val pagePath = page.fullPath + ".md"
85 | val renderedPage = markdownRepository.loadFile(pagePath)(inputStreamToString).map(renderer)
86 |
87 | renderedPage.map { html =>
88 | val withNext = html + templates.nextLinks(page.nextLinks)
89 | RenderedPage(withNext, Some(templates.sidebar(page.nav)), pagePath, Some(templates.breadcrumbs(page.nav)))
90 | }
91 | }
92 | }
93 | }
94 | }
95 |
96 | /**
97 | * Render all the pages of the documentation
98 | *
99 | * @param singlePage
100 | * Whether the pages are being rendered to be formatted on a single page
101 | */
102 | def renderAllPages(singlePage: Boolean): List[(String, String)] = {
103 | pageIndex match {
104 | case Some(idx) =>
105 | def collectPagesInOrder(node: TocTree): List[String] = {
106 | node match {
107 | case TocPage(page, _, _) => List(page)
108 | case toc: Toc => toc.nodes.flatMap(n => collectPagesInOrder(n._2))
109 | }
110 | }
111 | val pages = collectPagesInOrder(idx.toc)
112 | pages.flatMap { pageName =>
113 | idx
114 | .get(pageName)
115 | .flatMap { page =>
116 | withRenderer(page.path, page.nav.headOption, singlePage = singlePage) { renderer =>
117 | val pagePath = page.fullPath + ".md"
118 | markdownRepository.loadFile(pagePath)(inputStreamToString).map(renderer)
119 | }
120 | }
121 | .map { pageName -> _ }
122 | }
123 | case None =>
124 | throw new IllegalStateException("Can only render all pages if there's a page index")
125 | }
126 | }
127 |
128 | /**
129 | * Render a Play documentation page.
130 | *
131 | * @param page
132 | * The page to render, without path or markdown extension.
133 | * @return
134 | * If found a tuple of the rendered page and the rendered sidebar, if the sidebar was found.
135 | */
136 | private def renderOldPage(page: String): Option[RenderedPage] = {
137 | // Find the markdown file
138 | markdownRepository.findFileWithName(page + ".md").flatMap { pagePath =>
139 | val file = new File(pagePath)
140 | // Work out the relative path for the file
141 | val relativePath = Option(file.getParentFile).map(_.getPath)
142 |
143 | def render(path: String, headerIds: Boolean = true): Option[String] = {
144 | withRenderer(relativePath, None, headerIds = headerIds) { renderer =>
145 | markdownRepository.loadFile(path)(inputStreamToString).map(renderer)
146 | }
147 | }
148 |
149 | // Recursively search for Sidebar
150 | def findSideBar(file: Option[File]): Option[String] =
151 | file match {
152 | case None => None
153 | case Some(parent) =>
154 | val sidebar = render(parent.getPath + "/_Sidebar.md", headerIds = false)
155 | sidebar.orElse(findSideBar(Option(parent.getParentFile)))
156 | }
157 |
158 | def findBreadcrumbs(file: Option[File]): Option[String] =
159 | file match {
160 | case None => None
161 | case Some(parent) =>
162 | val breadcrumbs = render(parent.getPath + "/_Breadcrumbs.md", headerIds = false)
163 | breadcrumbs.orElse(findBreadcrumbs(Option(parent.getParentFile)))
164 | }
165 |
166 | // Render both the markdown and the sidebar
167 | render(pagePath).map { markdown =>
168 | RenderedPage(
169 | markdown,
170 | findSideBar(Option(file.getParentFile)),
171 | pagePath,
172 | findBreadcrumbs(Option(file.getParentFile))
173 | )
174 | }
175 | }
176 | }
177 |
178 | private def addExtension(href: String) = {
179 | pageExtension match {
180 | case Some(extension) =>
181 | // Need to add before the fragment
182 | if (href.contains("#")) {
183 | val parts = href.split('#')
184 | s"${parts.head}.$extension#${parts.tail.mkString("#")}"
185 | } else {
186 | s"$href.$extension"
187 | }
188 | case None => href
189 | }
190 | }
191 |
192 | private def withRenderer[T](
193 | relativePath: Option[String],
194 | toc: Option[Toc],
195 | headerIds: Boolean = true,
196 | singlePage: Boolean = false
197 | )(block: (String => String) => T): T = {
198 | // Link renderer
199 | val link: (String => (String, String)) = {
200 | case link if link.contains("|") =>
201 | val parts = link.split('|')
202 | val href = if (singlePage) "#" + parts.tail.head else addExtension(parts.tail.head)
203 | (href, parts.head)
204 | case image if Seq("png", "svg").exists(suffix => image.endsWith("." + suffix)) =>
205 | val link = image match {
206 | case full if full.startsWith("http://") => full
207 | case absolute if absolute.startsWith("/") => resources + absolute
208 | case relative => resources + "/" + relativePath.map(_ + "/").getOrElse("") + relative
209 | }
210 | (link, """![]()
""")
211 | case link =>
212 | if (singlePage) ("#" + link, link) else (addExtension(link), link)
213 | }
214 |
215 | val links = new LinkRenderer {
216 | override def render(node: WikiLinkNode) = {
217 | val (href, text) = link(node.getText)
218 | new LinkRenderer.Rendering(href, text)
219 | }
220 | }
221 |
222 | // Markdown parser
223 | val processor = new PegDownProcessor(
224 | Extensions.ALL & ~Extensions.ANCHORLINKS,
225 | PegDownPlugins
226 | .builder()
227 | .withPlugin(classOf[CodeReferenceParser])
228 | .withPlugin(classOf[VariableParser], PlayVersionVariableName)
229 | .withPlugin(classOf[TocParser])
230 | .build
231 | )
232 |
233 | // ToHtmlSerializer's are stateful and so not reusable
234 | def htmlSerializer =
235 | new ToHtmlSerializer(
236 | links,
237 | Collections.singletonMap(VerbatimSerializer.DEFAULT, new VerbatimSerializerWrapper(PrettifyVerbatimSerializer)),
238 | Arrays.asList[ToHtmlSerializerPlugin](
239 | new CodeReferenceSerializer(relativePath.map(_ + "/").getOrElse("")),
240 | new VariableSerializer(Map(PlayVersionVariableName -> FastEncoder.encode(playVersion))),
241 | new TocSerializer(toc)
242 | )
243 | ) {
244 | var headingsSeen = Map.empty[String, Int]
245 | def headingToAnchor(heading: String) = {
246 | val anchor = FastEncoder.encode(heading.replace(' ', '-'))
247 | headingsSeen
248 | .get(anchor)
249 | .fold {
250 | headingsSeen += anchor -> 1
251 | anchor
252 | } { seen =>
253 | headingsSeen += anchor -> (seen + 1)
254 | anchor + seen
255 | }
256 | }
257 |
258 | override def visit(node: CodeNode) = {
259 | super.visit(new CodeNode(node.getText.replace(PlayVersionVariableName, playVersion)))
260 | }
261 |
262 | override def visit(node: HeaderNode) = {
263 | // Put an id on header nodes
264 | printer
265 | .print(" Seq(t.getText)
275 | case other => collectTextNodes(other)
276 | }
277 | }
278 | val title = collectTextNodes(node).mkString
279 | val anchorId = headingToAnchor(title)
280 |
281 | printer
282 | .print(anchorId)
283 | .print("\"")
284 |
285 | printer.print(">")
286 |
287 | // Add section marker
288 | printer
289 | .print("")
293 | .print("§")
294 | .print("")
295 | } else {
296 | printer.print(">")
297 | }
298 |
299 | visitChildren(node)
300 | printer.print("")
301 | }
302 | }
303 |
304 | def render(markdown: String): String = {
305 | val astRoot = processor.parseMarkdown(markdown.toCharArray)
306 | htmlSerializer.toHtml(astRoot)
307 | }
308 |
309 | block(render)
310 | }
311 |
312 | // Directives to insert code, skip code and replace code
313 | private val Insert = """.*###insert: (.*?)(?:###.*)?""".r
314 | private val SkipN = """.*###skip:\s*(\d+).*""".r
315 | private val Skip = """.*###skip.*""".r
316 | private val ReplaceNext = """.*###replace: (.*?)(?:###.*)?""".r
317 |
318 | private class CodeReferenceSerializer(pagePath: String) extends ToHtmlSerializerPlugin {
319 | // Most files will be accessed multiple times from the same markdown file, no point in opening them many times
320 | // so memoize them. This cache is only per file rendered, so does not need to be thread safe.
321 | val repo = Memoize[String, Option[Seq[String]]] { path =>
322 | codeRepository.loadFile(path) { is => IOUtils.readLines(is, "utf-8").asScala.toSeq }
323 | }
324 |
325 | def visit(node: Node, visitor: Visitor, printer: Printer) =
326 | node match {
327 | case code: CodeReferenceNode => {
328 | // Label is after the #, or if no #, then is the link label
329 | val (source, label) = code.getSource.split("#", 2) match {
330 | case Array(source, label) => (source, label)
331 | case Array(source) => (source, code.getLabel)
332 | }
333 |
334 | // The file is either relative to current page or absolute, under the root
335 | val sourceFile = if (source.startsWith("/")) {
336 | repo(source.drop(1))
337 | } else {
338 | repo(pagePath + source)
339 | }
340 |
341 | val segment = if (label.nonEmpty) {
342 | val labelPattern = ("""\s*#\Q""" + label + """\E(\s|\z)""").r
343 | sourceFile.flatMap { sourceCode =>
344 | val notLabel = (s: String) => labelPattern.findFirstIn(s).isEmpty
345 | val segment = sourceCode.dropWhile(notLabel).drop(1).takeWhile(notLabel)
346 | if (segment.isEmpty) {
347 | None
348 | } else {
349 | Some(segment)
350 | }
351 | }
352 | } else {
353 | sourceFile
354 | }
355 |
356 | segment
357 | .map { segment =>
358 | // Calculate the indent, which is equal to the smallest indent of any line, excluding lines that only consist
359 | // of space characters
360 | val indent = segment
361 | .map { line => if (!line.exists(_ != ' ')) None else Some(line.indexWhere(_ != ' ')) }
362 | .reduce((i1, i2) =>
363 | (i1, i2) match {
364 | case (None, None) => None
365 | case (i, None) => i
366 | case (None, i) => i
367 | case (Some(i1), Some(i2)) => Some(math.min(i1, i2))
368 | }
369 | )
370 | .getOrElse(0)
371 |
372 | // Process directives in segment
373 | case class State(buffer: StringBuilder = new StringBuilder, skip: Option[Int] = None) {
374 | def dropIndentAndAppendLine(s: String): State = {
375 | buffer.append(s.drop(indent)).append("\n")
376 | this
377 | }
378 | def appendLine(s: String): State = {
379 | buffer.append(s).append("\n")
380 | this
381 | }
382 | }
383 | val compiledSegment = segment
384 | .foldLeft(State()) { (state, line) =>
385 | state.skip match {
386 | case Some(n) if n > 1 => state.copy(skip = Some(n - 1))
387 | case Some(n) => state.copy(skip = None)
388 | case None =>
389 | line match {
390 | case Insert(code) => state.appendLine(code)
391 | case SkipN(n) => state.copy(skip = Some(n.toInt))
392 | case Skip() => state
393 | case ReplaceNext(code) => state.appendLine(code).copy(skip = Some(1))
394 | case _ => state.dropIndentAndAppendLine(line)
395 | }
396 | }
397 | }
398 | .buffer /* Drop last newline */
399 | .dropRight(1)
400 | .toString()
401 |
402 | // Guess the type of the file
403 | val fileType = source.split("\\.") match {
404 | case withExtension if withExtension.length > 1 => Some(withExtension.last)
405 | case _ => None
406 | }
407 |
408 | // And visit it
409 | fileType
410 | .map(t => new VerbatimNode(compiledSegment, t))
411 | .getOrElse(new VerbatimNode(compiledSegment))
412 | .accept(visitor)
413 |
414 | true
415 | }
416 | .getOrElse {
417 | printer.print("Unable to find label " + label + " in source file " + source)
418 | true
419 | }
420 | }
421 | case _ => false
422 | }
423 | }
424 |
425 | private class VariableSerializer(variables: Map[String, String]) extends ToHtmlSerializerPlugin {
426 | def visit(node: Node, visitor: Visitor, printer: Printer) =
427 | node match {
428 | case variable: VariableNode => {
429 | new TextNode(variables.get(variable.getName).getOrElse("Unknown variable: " + variable.getName))
430 | .accept(visitor)
431 | true
432 | }
433 | case _ => false
434 | }
435 | }
436 |
437 | private class VerbatimSerializerWrapper(wrapped: VerbatimSerializer) extends VerbatimSerializer {
438 | def serialize(node: VerbatimNode, printer: Printer): Unit = {
439 | val text = node.getText.replace(PlayVersionVariableName, playVersion)
440 | wrapped.serialize(new VerbatimNode(text, node.getType), printer)
441 | }
442 | }
443 |
444 | private class TocSerializer(maybeToc: Option[Toc]) extends ToHtmlSerializerPlugin {
445 | def visit(node: Node, visitor: Visitor, printer: Printer) =
446 | node match {
447 | case tocNode: TocNode =>
448 | maybeToc.fold(false) { t =>
449 | printer.print(templates.toc(t))
450 | true
451 | }
452 | case _ => false
453 | }
454 | }
455 |
456 | private val inputStreamToString: InputStream => String = IOUtils.toString(_, "utf-8")
457 | }
458 |
459 | private class Memoize[-T, +R](f: T => R) extends (T => R) {
460 | import scala.collection.mutable
461 | private[this] val vals = mutable.Map.empty[T, R]
462 |
463 | def apply(x: T): R = {
464 | if (vals.contains(x)) {
465 | vals(x)
466 | } else {
467 | val y = f(x)
468 | vals + ((x, y))
469 | y
470 | }
471 | }
472 | }
473 |
474 | private object Memoize {
475 | def apply[T, R](f: T => R) = new Memoize(f)
476 | }
477 |
--------------------------------------------------------------------------------