You are viewing a plain text version of this content. The canonical link for it is here.
Posted to reviews@spark.apache.org by GitBox <gi...@apache.org> on 2022/02/15 15:02:37 UTC
[GitHub] [spark] srowen commented on a change in pull request #35516: [SPARK-38210][DOCS] Improve documentation generation README
srowen commented on a change in pull request #35516:
URL: https://github.com/apache/spark/pull/35516#discussion_r806915067
##########
File path: docs/README.md
##########
@@ -26,13 +26,20 @@ Read on to learn more about viewing documentation in plain text (i.e., markdown)
documentation yourself. Why build it yourself? So that you have the docs that correspond to
whichever version of Spark you currently have checked out of revision control.
-## Prerequisites
+## Building documentation
+There are two ways to build Spark documentation, complete and partial. Complete will build a site similar
Review comment:
-> "similar to the main documentation site at ..."
Start a new sentence like "with all APIs documented. Partial ..."
I think this could be clarified: "Partial documentation builds, for a specific language or API, are also possible"
##########
File path: docs/README.md
##########
@@ -111,7 +112,15 @@ $ bundle exec jekyll serve --watch
$ PRODUCTION=1 bundle exec jekyll build
```
-## API Docs (Scaladoc, Javadoc, Sphinx, roxygen2, MkDocs)
+You can optionally skip API build (for partial build) as it takes time
Review comment:
This needs a rewrite: "To create a partial build without API docs (which can take a long time), use SKIP_API=1:"
But then I thought partial builds were _just_ the API docs? this addition is confusing
##########
File path: docs/README.md
##########
@@ -26,13 +26,20 @@ Read on to learn more about viewing documentation in plain text (i.e., markdown)
documentation yourself. Why build it yourself? So that you have the docs that correspond to
whichever version of Spark you currently have checked out of revision control.
-## Prerequisites
+## Building documentation
+There are two ways to build Spark documentation, complete and partial. Complete will build a site similar
+to one you can find https://spark.apache.org/documentation.html with all APIs documented and partial
+one can be used to build a language/API specific documentation.
+
+### Prerequisites
The Spark documentation build uses a number of tools to build HTML docs and API docs in Scala, Java,
Python, R and SQL.
-You need to have [Ruby](https://www.ruby-lang.org/en/documentation/installation/) and
-[Python](https://docs.python.org/2/using/unix.html#getting-and-installing-the-latest-version-of-python)
+For complete documentation all below tools must be installed **including Optionals**.
Review comment:
below tools -> tools below
##########
File path: docs/README.md
##########
@@ -26,13 +26,20 @@ Read on to learn more about viewing documentation in plain text (i.e., markdown)
documentation yourself. Why build it yourself? So that you have the docs that correspond to
whichever version of Spark you currently have checked out of revision control.
-## Prerequisites
+## Building documentation
+There are two ways to build Spark documentation, complete and partial. Complete will build a site similar
+to one you can find https://spark.apache.org/documentation.html with all APIs documented and partial
+one can be used to build a language/API specific documentation.
+
+### Prerequisites
The Spark documentation build uses a number of tools to build HTML docs and API docs in Scala, Java,
Python, R and SQL.
-You need to have [Ruby](https://www.ruby-lang.org/en/documentation/installation/) and
-[Python](https://docs.python.org/2/using/unix.html#getting-and-installing-the-latest-version-of-python)
+For complete documentation all below tools must be installed **including Optionals**.
+
+You need to have JDK, Scala, [Ruby](https://www.ruby-lang.org/en/documentation/installation/) and
Review comment:
JDK -> the JDK
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org