[SPARK-18923][DOC][BUILD] Support skipping R/Python API docs
## What changes were proposed in this pull request? We can build Python API docs by `cd ./python/docs && make html for Python` and R API docs by `cd ./R && sh create-docs.sh for R` separately. However, `jekyll` fails in some environments. This PR aims to support `SKIP_PYTHONDOC` and `SKIP_RDOC` for documentation build in `docs` folder. Currently, we can use `SKIP_SCALADOC` or `SKIP_API`. The reason providing additional options is that the Spark documentation build uses a number of tools to build HTML docs and API docs in Scala, Python and R. Specifically, for Python and R, - Python API docs requires `sphinx`. - R API docs requires `R` installation and `knitr` (and more others libraries). In other words, we cannot generate Python API docs without R installation. Also, we cannot generate R API docs without Python `sphinx` installation. If Spark provides `SKIP_PYTHONDOC` and `SKIP_RDOC` like `SKIP_SCALADOC`, it would be more convenient. ## How was this patch tested? Manual. **Skipping Scala/Java/Python API Doc Build** ```bash $ cd docs $ SKIP_SCALADOC=1 SKIP_PYTHONDOC=1 jekyll build $ ls api DESCRIPTION R ``` **Skipping Scala/Java/R API Doc Build** ```bash $ cd docs $ SKIP_SCALADOC=1 SKIP_RDOC=1 jekyll build $ ls api python ``` Author: Dongjoon Hyun <dongjoon@apache.org> Closes #16336 from dongjoon-hyun/SPARK-18923.
This commit is contained in:
parent
24c0c94128
commit
ba4468bb24
|
@ -69,4 +69,5 @@ may take some time as it generates all of the scaladoc. The jekyll plugin also
|
|||
PySpark docs using [Sphinx](http://sphinx-doc.org/).
|
||||
|
||||
NOTE: To skip the step of building and copying over the Scala, Python, R API docs, run `SKIP_API=1
|
||||
jekyll`.
|
||||
jekyll`. In addition, `SKIP_SCALADOC=1`, `SKIP_PYTHONDOC=1`, and `SKIP_RDOC=1` can be used to skip a single
|
||||
step of the corresponding language.
|
||||
|
|
|
@ -113,36 +113,41 @@ if not (ENV['SKIP_API'] == '1')
|
|||
File.open(css_file, 'a') { |f| f.write("\n" + css.join()) }
|
||||
end
|
||||
|
||||
# Build Sphinx docs for Python
|
||||
if not (ENV['SKIP_PYTHONDOC'] == '1')
|
||||
# Build Sphinx docs for Python
|
||||
|
||||
puts "Moving to python/docs directory and building sphinx."
|
||||
cd("../python/docs")
|
||||
system("make html") || raise("Python doc generation failed")
|
||||
puts "Moving to python/docs directory and building sphinx."
|
||||
cd("../python/docs")
|
||||
system("make html") || raise("Python doc generation failed")
|
||||
|
||||
puts "Moving back into home dir."
|
||||
cd("../../")
|
||||
puts "Moving back into docs dir."
|
||||
cd("../../docs")
|
||||
|
||||
puts "Making directory api/python"
|
||||
mkdir_p "docs/api/python"
|
||||
puts "Making directory api/python"
|
||||
mkdir_p "api/python"
|
||||
|
||||
puts "cp -r python/docs/_build/html/. docs/api/python"
|
||||
cp_r("python/docs/_build/html/.", "docs/api/python")
|
||||
puts "cp -r ../python/docs/_build/html/. api/python"
|
||||
cp_r("../python/docs/_build/html/.", "api/python")
|
||||
end
|
||||
|
||||
# Build SparkR API docs
|
||||
puts "Moving to R directory and building roxygen docs."
|
||||
cd("R")
|
||||
system("./create-docs.sh") || raise("R doc generation failed")
|
||||
if not (ENV['SKIP_RDOC'] == '1')
|
||||
# Build SparkR API docs
|
||||
|
||||
puts "Moving back into home dir."
|
||||
cd("../")
|
||||
puts "Moving to R directory and building roxygen docs."
|
||||
cd("../R")
|
||||
system("./create-docs.sh") || raise("R doc generation failed")
|
||||
|
||||
puts "Making directory api/R"
|
||||
mkdir_p "docs/api/R"
|
||||
puts "Moving back into docs dir."
|
||||
cd("../docs")
|
||||
|
||||
puts "cp -r R/pkg/html/. docs/api/R"
|
||||
cp_r("R/pkg/html/.", "docs/api/R")
|
||||
puts "Making directory api/R"
|
||||
mkdir_p "api/R"
|
||||
|
||||
puts "cp R/pkg/DESCRIPTION docs/api"
|
||||
cp("R/pkg/DESCRIPTION", "docs/api")
|
||||
puts "cp -r ../R/pkg/html/. api/R"
|
||||
cp_r("../R/pkg/html/.", "api/R")
|
||||
|
||||
puts "cp ../R/pkg/DESCRIPTION api"
|
||||
cp("../R/pkg/DESCRIPTION", "api")
|
||||
end
|
||||
|
||||
end
|
||||
|
|
Loading…
Reference in a new issue