bazelbuild / bazel-website Goto Github PK

https://docs.bazel.build/versions/main/build-ref.html#labels explains the @workspace//… and @//… forms of labels containing workspace references. However, these are missing from https://docs.bazel.build/versions/main/build-ref.html#lexi (in particular, that doesn't explain the lexical syntax of workspace names), and also from https://docs.bazel.build/versions/main/glossary.html#label. It would be great to extend these places accordingly.

Links to pages previously under docs/ or versions/master/doc should be changed to point to docs.bazel.build/, and links to pages previously under blog/ should be changed to point to blog.bazel.build/.

Plan:

• Just do it with the rename.
• Anyone with an outstanding PR can just fix it
• Fix the CI pipeline to point to main instead of master.

Most of the logic for gathering the docs generated from source files can be removed since the marketing site is now completely static.

Some pages are accessible only from the footer (which is easy to miss). In particular, the FAQ and the support policy should be moved to a proper menu.

ENV:

$ uname -a
Linux Think 4.4.0-18362-Microsoft #1049-Microsoft Thu Aug 14 12:01:00 PST 2020 x86_64 x86_64 x86_64 GNU/Linux

$ ruby -v
ruby 2.5.1p57 (2018-03-29 revision 63029) [x86_64-linux-gnu]

$ gem -v
2.7.6

$ jekyll -v
jekyll 3.6.2

$ bundle -v
Bundler version 1.6.2

build info:

$ bazel build :site
INFO: Analyzed target //:site (0 packages loaded, 151 targets configured).
INFO: Found 1 target...
ERROR: /home/chengmingyi/workspace/github/bazel-website/BUILD:107:13: Action site-build failed (Exit 1) jekyll failed: error executing command jekyll build -q -s bazel-out/k8-fastbuild/bin/site-srcs -d bazel-out/k8-fastbuild/bin/site-build

Use --sandbox_debug to see verbose messages from the sandbox
/usr/lib/ruby/2.5.0/rubygems.rb:289:in `find_spec_for_exe': can't find gem jekyll (>= 0.a) with executable jekyll (Gem::GemNotFoundException)
        from /usr/lib/ruby/2.5.0/rubygems.rb:308:in `activate_bin_path'
        from /home/chengmingyi/gems/bin/jekyll:23:in `<main>'
Target //:site failed to build
Use --verbose_failures to see the command lines of failed build steps.
INFO: Elapsed time: 1.585s, Critical Path: 1.21s
INFO: 0 processes.
FAILED: Build did NOT complete successfully

i have tried to different ruby or jekyll or bundle version. None success.

The serve-docs script does not enable fast iteration. I would expect to very easily be able to rebuild the docs. Pressing r does not work for me:

$ ./scripts/serve-docs.sh
..
Type q to quit, r to rebuild docs and restart jekyll
Rebuilding docs and restarting jekyll
The 'build' command is only supported from within a workspace.

The site currently does not render properly because the Bootstrap and Font Awesome CSS, JS, and font assets are missing.

In the bazelbuild/bazel repo, these assets live separately under third_party. @steren - do we need also need to keep these assets separate under a third_party directory in this repo as well or would it be fine to directly add them to the assets/ directory?

Under contributors guide.
The patch acceptance page https://bazel.build/basics/patching.html should point to it

Things to mention

• tests are required for all new/changed behavior
• that license headers are required in all source files. list the exceptions
• that the PR description must have well worded release notes for new features or visible behavior changes

Things to warn about

• assuming / is the path separator
• assuming local execution only
• there must be others....

I think this needs an update: https://www.bazel.build/faq.html#does-bazel-require-a-build-cluster

We need to clean-up the roadmap also because 0.6 will certainly not include workspace loading.

/cc @steren

Pasting my comment on commit aaf0f33:

One problem with this change is that we have two files named contributing.md and CONTRIBUTING.md in the root of the source tree. Unfortunately, file systems that are case-insensitive by default, such as HFS+ on macOS, get confused because of this. :/

How about if we either rename CONTRIBUTING.md back to CONTRIBUTING or rename contributing.md to contribute.md? The former might be the safer change since the latter changes the URL of a page on the site and may result in dead links.

1. Go to https://ci.bazel.build/buildStatus/icon?job=rules_docker (it works as expected)
2. Go to https://ci.bazel.io/buildStatus/icon?job=rules_docker (it doesn't work)

The latter URL redirects to https://ci.bazel.build/buildStatus/icon?job=rules_docker?job=rules_docker, which returns 404. This breaks the build icon on rules_docker's README.

We moved the content of the Bazel website to https://bazel.build, https://docs.bazel.build and https://blog.bazel.build

Today, searching using the search widget in the top bar still returns URL results from the old structure.

We should confirm that the index is rebuilt properly and that the new subdomains are correctly indexed.

Repo

• Create a window in portrait mode. Best done with a monitor in portrait mode
• open https://docs.bazel.build/versions/master/test-encyclopedia.html and scroll to "Initial Conditions"
• observe that
  • the table of environment variables hangs off the window edge (but there is scrollbar - good)
  • the table overlaps the right navigation.
  • the texts of both divs merge rather than the content pane occluding the navigation pane

Screenshot

There was a change to this page that did not make it to this new repo.

See diff:
bazelbuild/bazel@354bf17#diff-bd6b18ec06d00ae0990444f4b6e5ed71

I get this error:

steren:bazel-website steren$ ./scripts/serve-docs.sh
expr: syntax error
INFO: Found 1 target...
ERROR: /Users/steren/work/bazel-website/BUILD:84:1: Generating site tarball. failed: Process exited with status 1 [sandboxed].
Cannot create redirect file docs/skylark/lib/provider.html. File exists.
Use --strategy=SiteTar=standalone to disable sandboxing for the failing actions.
Target //:jekyll-tree.tar failed to build
Use --verbose_failures to see the command lines of failed build steps.
INFO: Elapsed time: 3.448s, Critical Path: 1.76s

There are several js redirects in the bazel.build source (and docs.bazel.build). Port these to the "http redirector" service; they will be redirected via cacheable response headers.

OBSOLETE: REMOVE THESE

      var bad_url = new RegExp("^https?://(bazelbuild.github.io/bazel|(www\.)?bazel.io)/");
      if (bad_url.test(current_url)) {
        window.location.replace(current_url.replace(bad_url, "https://bazel.build/"));
      }
      var http_url = new RegExp("^http://(www\.)?bazel.build/");
      if (http_url.test(current_url)) {
        window.location.replace(current_url.replace(http_url, "https://bazel.build/"));
      }

a) bazel.build.github.io/bazel --> bazel.build : unnecessary; github does this for us
b) bazel.io --> bazel.build : no longer needed; http redirector does this now
c) http --> https : no longer needed; http redirector does this now

DO NOTHING: (these are necessary if the user starts from https (b/c those requests bypass the http-->https redirector; we may want to change routing so that everything routes through a global dispatcher, but that impacts a lot of things)

      // Do a shortcut so that be.bazel.build redirect to the build encyclopedia
      var be_url = new RegExp("^https?://be(\.bazel.build)?/?");
      if (be_url.test(current_url)) {
        window.location.replace(current_url.replace(be_url, "https://docs.bazel.build/be/overview.html"));
      }
      var be_url = new RegExp("^https?://be(\.bazel.build)?/([a-zA-Z0-9_-]+)([/#](.*))?");
      if (be_url.test(current_url)) {
        window.location.replace(current_url.replace(be_url, "https://docs.bazel.build/be/$2.html#$4"));
      }
      // And a short to code reviews
      var cr_url = new RegExp("^https?://cr(\.bazel.build)?/([0-9]+)")
      if (cr_url.test(current_url)) {
        window.location.replace(current_url.replace(cr_url, "https://bazel-review.googlesource.com/c/$2"));
      }
      // Code review dashboard
      var cr_url = new RegExp("^https?://cr(\.bazel.build)?/?")
      if (cr_url.test(current_url)) {
        window.location.replace(current_url.replace(cr_url, "https://bazel-review.googlesource.com/"));
      }

I'm unable to run target //:site, Is this a known issue?

$ bazel run //:site

INFO: Analyzed target //:site (1 packages loaded, 150 targets configured).
INFO: Found 1 target...
ERROR: [redacted]/bazel-website/BUILD:101:9: Generating site tarball. failed (Exit 1) build-jekyll-tree failed: error executing command bazel-out/host/bin/build-jekyll-tree bazel-out/darwin-fastbuild/bin/jekyll-tree.tar bazel-out/darwin-fastbuild/bin/jekyll-base.tar bazel-out/darwin-fastbuild/bin/jekyll-tree_redirects.redirects

Use --sandbox_debug to see verbose messages from the sandbox
Cannot create redirect file docs/skylark/lib/provider.html. File exists.
Target //:site failed to build
Use --verbose_failures to see the command lines of failed build steps.
INFO: Elapsed time: 2.144s, Critical Path: 1.94s
INFO: 2 processes: 2 darwin-sandbox.
FAILED: Build did NOT complete successfully

In a comment, @ulfjack mentioned that an action can be marked as "nosandbox". This is not documented anywhere that I can find. Can you add it to the web page?

I'm pretty sure, from looking at the code, that this is a marker that can be put in the "execution_requirements" for ctx.action.run() or ctx.actions.run_shell() (or the older, deprecated ctx.action()). For each of those, under execution_requirements, it says, "information for scheduling the action. See tags for useful keys," and the word "tags" is a a (currently broken) link to https://docs.bazel.build/versions/master/be/common-definitions.html#common-attributes.

Two things:

1. Are an action's execution_requirements and a rule's tags really the same thing? If not, then they need to be treated separately in the docs.
2. Can you add nosandbox to the appropriate place in the docs, wherever that may be?

Due the the fact that some of the Bazel documentation (such as the User Manual, Test Encyclopedia, most of the Skylark docs, etc.) are also published internally, and due to some annoying differences between the internal documentation framework and Jekyll (namely .md links rather than .html), it would be a good idea to provide some documentation in the Contribution Guidelines around this.

In particular, perhaps we should clarify which kinds of documentation changes should be avoided, such as changing .md links to .html for docs that are also published internally.

Some other ideas that might be useful:

• Documentation linter for catching these kinds of changes.
• Tests for validating the docs generated by //site:jekyll-tree (such as verifying that the jekyll-tree.sh script correctly converted all .md links to .html.
• Adding a design doc describing how the external documentation pipeline works (from Build Encyclopedia and Skylark Library docgen to packaging the Jekyll tree).

This question is in the FAQ:

Why do other Google projects (Android, Chrome) use other build tools?
Until the first (Alpha) release, Bazel was not available externally, so open source projects such as Chromium, Android, etc. could not use it. In addition, the original lack of Windows support was a problem for building Windows applications, such as Chrome.

Is it worth adding a note here that Android is, in fact, moving to Bazel now?

Complementary bug to bazelbuild/bazel#11883

cc: @floriographygoth

On the java rule's page, java_binary's jvm_flags redirects you to a stale link.

A list of flags to embed in the wrapper script generated for running this binary. Subject to $(location) and "Make variable" substitution, and Bourne shell tokenization.

The link on the page directs you to https://docs.bazel.build/versions/master/be/java.html#location.
However, there is currently no "location" section on the java rules page.

Twitter is not showing an image preview when posting https://bazel.build:
https://twitter.com/bazelbuild/status/880100968213426176

And G+ is using the Huawei logo. This logo is the only .png on the page.

Our page contains an og:image tag, so this is surprising.

Let's try to add schema.org metadata to be sure (docs at https://developers.google.com/+/web/snippet/)

At the bottom of https://bazel.build/contributing.html, under "Usign Bazel Continuous Integration".

https://www.bazel.build/designs/index.html

Under "Technical Docs", we have "Skyframe" and "Maintaining Bazel Chocolatey package on Windows". These two pages seem misplaced. If we remove them from the menu, we can move "Design Documents" to the top and remove the Technical Docs" section.

In this section

https://docs.bazel.build/versions/master/be/common-definitions.html#common.tags

the "sandbox" link is broken :)

• Navbar should collapse into hamburger menu sooner
• Large logo appears below the reset of the hero, which is visually awkward.

• One of the Why Bazel sections is misaligned.

• Logos are overlapping.
• Quotes appear a bit scrunched together. Perhaps at this resolution, each testimonial should be on its own line.

• Footer sections can still be all on one line at this resolution.

Problem:

Links on bazel.build to android and ios tutorial are broken they redirect to error 404 page.

Solution:

update the link

P.S I am taking this.

Hi,
I was browsing the issues and stumbled on to one which I might want to take but I'm not sure if it will be welcomed for various reasons.
WDYT about marking issues as "up-for-grab" and thus signaling to community members their help would be appreciated there?

The style of https://docs.bazel.build/versions/master/bazel-overview.html is quite different from https://www.bazel.build/contributing.html.

When I click the link for Building for Platforms in the main left-hand site navigation, I get a 404 message returned from the server.

The current footer has a "Stay Connected" section that points to twiter, slack, bazel-discuss@... but it omits significant other discussion

Some are:
[email protected] - general discussion and annoucements
[email protected] - technical discussion for people contributing to bazel
[email protected] - discussion specifically about external dependencies

And there are a handful of repo specific lists for rule sets.

Prompting context:
Yesterday, someone sent an e-mail to [email protected], asking to be subscribed. That obviously doesn’t work, because it’s a Google Group. After some searching on groups.google.com, I found the URL https://groups.google.com/a/bazel.build/g/external-deps that that person could use to sign up successfully. Question: is that URL documented anywhere, so that people can sign up themselves?

This conflates two entirely distinct topics. The guidelines for engagement with the community should be distinct from the tips about how to get started.

We should split this in to at last 2 pages.

It no longer works and instructs you to find someone to invite you.

Today, the footer is only showing the copyright info.

We could use it to:

• provide more useful links. (like Support: Issue, StackOverflow, FAQ)
• free up the top navigation bar: I do not think 'FAQ' should belong to the top bar.

https://bazel.build/faq.html#what-about-python acts like there's no built-in Python support in Bazel, but there is now, per
https://docs.bazel.build/versions/master/be/python.html and bazelbuild/bazel@4229823
Furthermore, the FAQ entry refers to https://github.com/bazelbuild/bazel/blob/master/tools/build_rules/py_rules.bzl , which does not exist.

We are still running Jekyll 2. Tracking bug for upgrading to the latest Jekyll release (currently 3.5), which will allow us to take advantage of new features, such as packaging the Bazel site theme as a Gem that can be reused across the different parts of the Bazel site.

(See #74)

Currently, be.bazel.build and cr.bazel.build are resolved to https://bazel.build, and then redirect to other places via javascript. Implement these server-side instead.

This will allow us to share the theme across the different parts of the Bazel site without all the code duplication we currently have.

We want other repositories to be able to point to the master Bazel contributing page. That is a central place to talk about project governance and the need for design documents.

[Setting up the coding environment] is currently very skewed towards developing Bazel itself rather than rule sets.

The self-inviter we're using uses the legacy token mechanism, which Slack has turned down.

Turns out that we don't need that anymore, since Slack now supports non-expiring invite links: https://bazelbuild.slack.com/join/shared_invite/zt-dzm4qj0h-maSR3EcEr8SWE1f7dA55zw#/

If you're signed in to the workspace, clicking on this link redirects you to the workspace.

If you're not signed in to the workspace. clicking on this link provides you with a sign up form. I think we can turn down the self-inviter service and configure the service behind slack.bazel.build to redirect to https://bazelbuild.slack.com/join/shared_invite/zt-dzm4qj0h-maSR3EcEr8SWE1f7dA55zw#/.

cc @philwo @fweikert

If you use search from the blog, the site returns 404.

As I touched on in #79, I've been seeing some broken documentation links on the website recently. Some links take me to a 404 page.

One example: Go to https://docs.bazel.build/versions/master/skylark/lib/ctx.html#action, then scroll down to execution_requirements. Where it says "See tags for useful keys," click the "tags" link. It will take you to a 404 page — the URL of the page is:

https://docs.bazel.build/docs/be/common-definitions.html#common.tags

I think the actual desired URL (which I found through a Google search) is:

https://docs.bazel.build/versions/master/be/common-definitions.html#common-attributes

Notice two things about that: (1) the URL is different, and (2) the fragment (the part after #) is different.

I wanted to edit this page: https://bazel.build/maintaining/maintainers-guide.html

But it doesn't have an "Edit this page" link, which makes it hard to do so.

In contrast, other sites like e.g. https://docs.bazel.build/versions/3.2.0/bazel-overview.html have that link. Can we add it to the other pages, too?

This page https://docs.bazel.build/versions/3.7.0/remote-execution.html
should be split so that

• the list of vendors is moved to this site.
• the page contains a reference to the newly created list

Rationale: The group of vendors is independent of the Bazel version. New ones can start up at any time, and can service most existing Bazel versions. We serve the community best by keeping them in a place where new services are seen by users of all Bazel versions.

This will make it easier to navigate from a specific roadmap back to the main roadmaps page by editing the URL.