nchammas commented on code in PR #699: URL: https://github.com/apache/spark-website/pull/699#discussion_r3729846372
########## README.md: ########## @@ -21,29 +45,16 @@ the Markdown files in the Docker container. .dev/build-docs.sh ``` -## Docs sub-dir - -The docs are not generated as part of the website. They are built separately for each release -of Spark from the Spark source repository and then copied to the website under the docs -directory. See the instructions for building those in the readme in the Spark -project's `/docs` directory. - -## Rouge and Pygments - -We also use [Rouge](https://github.com/rouge-ruby/rouge) for syntax highlighting in documentation Markdown pages. -Its HTML output is compatible with CSS files designed for [Pygments](https://pygments.org/). +## Deploying to production -To mark a block of code in your Markdown to be syntax highlighted by `jekyll` during the -compile phase, use the following syntax: +The website is deployed automatically by [ASF Infra][infra]. The deployment configuration is tracked by [.asf.yaml](./.asf.yaml) and is [documented here][asf-docs]. - {% highlight scala %} - // Your Scala code goes here, you can replace Scala with many other - // supported languages too. - {% endhighlight %} +One deployment detail that appears to be critical is the presence of the [`content`](./content/) symlink to `site/`. Even though ASF Infra is [aware of Jekyll][jek], we perhaps do not have the exact setup required for them to automatically use our [Jekyll config](./_config.yml) to understand where the site content lives. Without the `content` symlink, the website will just show a plain directory listing of the files in this repo. Review Comment: The background here is that in #697 I attempted to remove this symlink because there was no documentation anywhere about it -- neither here nor on ASF Infra's website -- and it seemed to be a vestigial leftover [from 10 years ago](https://github.com/apache/spark-website/commit/fff0f57013b88c7b3f2906564421323f357e6d01). As you can see from the commit message, even when it was added the author was not sure it was needed. When we merged #697 it broke the site. We are not 100% sure the removal of `content/` was the cause, but it's the most likely explanation. In the absence of a proper staging site, we cannot be sure until we merge this new PR here. The purpose of this note is specifically to capture this learning experience so it's not repeated. Assuming my analysis is correct, not knowing the purpose of `content/` _did_ hurt us. -- 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: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
