[Website] Update documentations for 6.0.1

[kou]

No description provided.

[jorisvandenbossche]

@kou thanks for building the docs!
Checking it out locally, I see there is still something wrong with the version dropdown (it appears behind the sidebar, instead of on top). I think I didn't notice this when developing it because of working with the dev version of the theme. Will take a look at it tomorrow!

[jorisvandenbossche]

I added the same fix to the upstream repo as well: apache/arrow#11802 (but for 6.0.1 the patch I pushed should be sufficient)

[kou]

Thanks. I've also confirmed the commit fix the version dropdown.

I'll merge this.

[amol-]

@kou quick question, when building the docs did you have to turn off WARN_AS_ERROR in apidocs? ( https://github.com/apache/arrow/blob/master/cpp/apidoc/Doxyfile#L815 ). When I tried to build the docs for 6.0.1 I faced warnings in both XSIMD and Flight and thus couldn't build the docs unless I disabled erroring on warnings.

Also I guess you haven't gone through the post-09-docs.sh script ( https://github.com/apache/arrow/blob/master/dev/release/post-09-docs.sh ) as that one currently seems to throw away all the past versions of the docs (1.0, 2.0, 3.0, and so on) by virtue of the rm -rf that it does

[kou]

I didn't touch WARN_AS_ERROR and get any error. What warnings are you faced? Did you fix them in master? It seems that there are no Doxygen related warnings in the latest docs job: https://dev.azure.com/ursacomputing/crossbow/_build/results?buildId=16538&view=logs&j=0da5d1d9-276d-5173-c4c4-9d4d4ed14fdb&t=d9b15392-e4ce-5e4c-0c8c-b69645229181&l=21283

I used post-09-docs.sh but needed to update it:

@@ -34,20 +34,32 @@ release_tag="apache-arrow-${version}"
 branch_name=release-docs-${version}
 
 pushd "${ARROW_SITE_DIR}"
-git checkout asf-site
+git fetch --all --prune --tags --force -j$(nproc)
+git checkout .
+git branch -D asf-site || :
+git checkout -b asf-site origin/asf-site
+git rebase apache/asf-site
+git branch -D ${branch_name} || :
 git checkout -b ${branch_name}
+versioned_paths=()
+for versioned_path in docs/*.0/; do
+  versioned_paths+=(${versioned_path})
+done
 rm -rf docs/*
+git checkout "${versioned_paths[@]}"
 popd
 
 pushd "${ARROW_DIR}"
 git checkout "${release_tag}"
 
-UBUNTU=20.10 archery docker run \
+archery docker run \
   -v "${ARROW_SITE_DIR}/docs:/build/docs" \
   -e ARROW_DOCS_VERSION="${version}" \
   ubuntu-docs
 
+git checkout -
+
 : ${PUSH:=1}
 
 if [ ${PUSH} -gt 0 ]; then
   pushed "${ARROW_SITE_DIR}"
+  sudo chown -R ${USER}: docs || : # For Linux
+  git checkout docs/c_glib/index.html

One of the problems in post-09-docs.sh is the past versions of docs as you said. But there are mote problems such as apache/arrow#11815 .

I want to avoid building docs on local. I want to build docs in CI and just use built docs like our packaging tasks. I'm working on this. I'll open a pull request to update post-09-docs.sh in the work.

[amol-]

@kou This are the errors that I get if I build the doxygen docs:

/arrow/cpp/src/xsimd_ep/include/xsimd/types/xsimd_generic_arch.hpp:15: warning: missing title after \defgroup arch
/arrow/cpp/src/arrow/flight/Flight.pb.h:2741: warning: no uniquely matching class member found for 
  void arrow::flight::protocol::HandshakeRequest::clear_protocol_version()

/arrow/cpp/src/arrow/flight/Flight.pb.h:2744: warning: no uniquely matching class member found for 
  PROTOBUF_NAMESPACE_ID::uint64 arrow::flight::protocol::HandshakeRequest::_internal_protocol_version() const

/arrow/cpp/src/arrow/flight/Flight.pb.h:2747: warning: no uniquely matching class member found for 
  PROTOBUF_NAMESPACE_ID::uint64 arrow::flight::protocol::HandshakeRequest::protocol_version() const

/arrow/cpp/src/arrow/flight/Flight.pb.h:2751: warning: no uniquely matching class member found for 
  void arrow::flight::protocol::HandshakeRequest::_internal_set_protocol_version(::PROTOBUF_NAMESPACE_ID::uint64 value)

/arrow/cpp/src/arrow/flight/Flight.pb.h:2755: warning: no uniquely matching class member found for 
  void arrow::flight::protocol::HandshakeRequest::set_protocol_version(::PROTOBUF_NAMESPACE_ID::uint64 value)

/arrow/cpp/src/arrow/flight/Flight.pb.h:2761: warning: no uniquely matching class member found for 
  void arrow::flight::protocol::HandshakeRequest::clear_payload()

/arrow/cpp/src/arrow/flight/Flight.pb.h:2764: warning: no uniquely matching class member found for 
  const std::string & arrow::flight::protocol::HandshakeRequest::payload() const

/arrow/cpp/src/arrow/flight/Flight.pb.h:2768: warning: no uniquely matching class member found for 
  void arrow::flight::protocol::HandshakeRequest::set_payload(const std::string &value)

/arrow/cpp/src/arrow/flight/Flight.pb.h:2772: warning: no uniquely matching class member found for 
  std::string * arrow::flight::protocol::HandshakeRequest::mutable_payload()

/arrow/cpp/src/arrow/flight/Flight.pb.h:2776: warning: no uniquely matching class member found for 
  const std::string & arrow::flight::protocol::HandshakeRequest::_internal_payload() const

/arrow/cpp/src/arrow/flight/Flight.pb.h:2779: warning: no uniquely matching class member found for 
  void arrow::flight::protocol::HandshakeRequest::_internal_set_payload(const std::string &value)

/arrow/cpp/src/arrow/flight/Flight.pb.h:2783: warning: no uniquely matching class member found for 
  void arrow::flight::protocol::HandshakeRequest::set_payload(std::string &&value)

/arrow/cpp/src/arrow/flight/Flight.pb.h:2789: warning: no uniquely matching class member found for 
  void arrow::flight::protocol::HandshakeRequest::set_payload(const char *value)

/arrow/cpp/src/arrow/flight/Flight.pb.h:2795: warning: no uniquely matching class member found for 
  void arrow::flight::protocol::HandshakeRequest::set_payload(const void *value, size_t size)

/arrow/cpp/src/arrow/flight/Flight.pb.h:2802: warning: no uniquely matching class member found for 
  std::string * arrow::flight::protocol::HandshakeRequest::_internal_mutable_payload()

/arrow/cpp/src/arrow/flight/Flight.pb.h:2806: warning: no uniquely matching class member found for 
  std::string * arrow::flight::protocol::HandshakeRequest::release_payload()

[kou]

They are files generated in build process. (It seems that you don't use "out-of-source" build.)
If you use clean source directory, these warnings will not be shown.

[amol-]

Uhm, I did run from a clean checkout of the codebase (cloned as arrow-upstream) and used archery docker run ubuntu-docs in it to build the docs. The docker compose runs a ci/scripts/cpp_build.sh script which does configure and build the source code thus generating the files you mentioned. Thus the documented docs build process does seem to lead to those errors.

[kou]

I couldn't reproduce this on local.

Could you try again from git clone https://github.com/apache/arrow.git arrow-upstream and provide logs of all command lines and outputs of them?

(Should we create a Jira issue for this?)