nchammas commented on a change in pull request #26719: [SPARK-30084] Document how to trigger Jekyll build on Python API doc changes URL: https://github.com/apache/spark/pull/26719#discussion_r352295923
########## File path: docs/README.md ########## @@ -102,3 +102,17 @@ using [MkDocs](https://www.mkdocs.org/). NOTE: To skip the step of building and copying over the Scala, Java, Python, R and SQL API docs, run `SKIP_API=1 jekyll build`. In addition, `SKIP_SCALADOC=1`, `SKIP_PYTHONDOC=1`, `SKIP_RDOC=1` and `SKIP_SQLDOC=1` can be used to skip a single step of the corresponding language. `SKIP_SCALADOC` indicates skipping both the Scala and Java docs. + +### Automatically Rebuilding API Docs + +`jekyll serve --watch` will only watch what's in `docs/`, and it [won't follow symlinks](https://github.com/jekyll/jekyll/issues/233). That means it won't monitor your API docs. Review comment: Tried again. It doesn't work. It looks like Jekyll has bounced around many times on supporting symlinks or not, and it varies depending on the context (main site content vs. themes vs. whatever else). I don't claim to understand it all. What I can assert, though, is that `jekyll serve --watch` does not follow symlinks under Jekyll 4.0.0. Here's the change I tested: ```diff --- a/docs/_plugins/copy_api_dirs.rb +++ b/docs/_plugins/copy_api_dirs.rb @@ -123,11 +123,14 @@ if not (ENV['SKIP_API'] == '1') puts "Moving back into docs dir." cd("../../docs") - puts "Making directory api/python" - mkdir_p "api/python" + system("rm -rf api/python") + system("ln -sf " + pwd + "/../python/docs/_build/html ./api/python") - puts "cp -r ../python/docs/_build/html/. api/python" - cp_r("../python/docs/_build/html/.", "api/python") + # puts "Making directory api/python" + # mkdir_p "api/python" + + # puts "cp -r ../python/docs/_build/html/. api/python" + # cp_r("../python/docs/_build/html/.", "api/python") end if not (ENV['SKIP_RDOC'] == '1') ``` Rebuilding the docs does not trigger a Jekyll update. Even if it did, we still need a way to trigger `make html` to rebuild the Python API docs, which Jekyll is currently not going to do as part of `--watch`. Maybe I'm misunderstanding how Jekyll works. If someone else knows how to get Jekyll to automatically pick up and serve API doc updates, I'm all ears. Maybe there is a better way to do this via Jekyll [hooks](https://jekyllrb.com/docs/plugins/hooks/)? Or by getting Jekyll to [reload plugins](https://github.com/jekyll/jekyll/issues/4774) when files change (which would address the `make html` issue)? ---------------------------------------------------------------- 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. For queries about this service, please contact Infrastructure at: [email protected] With regards, Apache Git Services --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
